1<div align="center"> 2 3 <h1><code>Arbitrary</code></h1> 4 5 <p><strong>The trait for generating structured data from arbitrary, unstructured input.</strong></p> 6 7 <img alt="GitHub Actions Status" src="https://github.com/rust-fuzz/rust_arbitrary/workflows/Rust/badge.svg"/> 8 9</div> 10 11## About 12 13The `Arbitrary` crate lets you construct arbitrary instance of a type. 14 15This crate is primarily intended to be combined with a fuzzer like [libFuzzer 16and `cargo-fuzz`](https://github.com/rust-fuzz/cargo-fuzz) or 17[AFL](https://github.com/rust-fuzz/afl.rs), and to help you turn the raw, 18untyped byte buffers that they produce into well-typed, valid, structured 19values. This allows you to combine structure-aware test case generation with 20coverage-guided, mutation-based fuzzers. 21 22## Documentation 23 24[**Read the API documentation on `docs.rs`!**](https://docs.rs/arbitrary) 25 26## Example 27 28Say you're writing a color conversion library, and you have an `Rgb` struct to 29represent RGB colors. You might want to implement `Arbitrary` for `Rgb` so that 30you could take arbitrary `Rgb` instances in a test function that asserts some 31property (for example, asserting that RGB converted to HSL and converted back to 32RGB always ends up exactly where we started). 33 34### Automatically Deriving `Arbitrary` 35 36Automatically deriving the `Arbitrary` trait is the recommended way to implement 37`Arbitrary` for your types. 38 39Automatically deriving `Arbitrary` requires you to enable the `"derive"` cargo 40feature: 41 42```toml 43# Cargo.toml 44 45[dependencies] 46arbitrary = { version = "1", features = ["derive"] } 47``` 48 49And then you can simply add `#[derive(Arbitrary)]` annotations to your types: 50 51```rust 52// rgb.rs 53 54use arbitrary::Arbitrary; 55 56#[derive(Arbitrary)] 57pub struct Rgb { 58 pub r: u8, 59 pub g: u8, 60 pub b: u8, 61} 62``` 63 64### Implementing `Arbitrary` By Hand 65 66Alternatively, you can write an `Arbitrary` implementation by hand: 67 68```rust 69// rgb.rs 70 71use arbitrary::{Arbitrary, Result, Unstructured}; 72 73#[derive(Copy, Clone, Debug)] 74pub struct Rgb { 75 pub r: u8, 76 pub g: u8, 77 pub b: u8, 78} 79 80impl<'a> Arbitrary<'a> for Rgb { 81 fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> { 82 let r = u8::arbitrary(u)?; 83 let g = u8::arbitrary(u)?; 84 let b = u8::arbitrary(u)?; 85 Ok(Rgb { r, g, b }) 86 } 87} 88``` 89 90## License 91 92Licensed under dual MIT or Apache-2.0 at your choice. 93 94Unless you explicitly state otherwise, any contribution intentionally submitted 95for inclusion in this project by you, as defined in the Apache-2.0 license, 96shall be dual licensed as above, without any additional terms or conditions. 97
