• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..--

.github/workflows/23-Nov-2023-3633

examples/23-Nov-2023-

patches/23-Nov-2023-2119

src/23-Nov-2023-1,9761,178

tests/23-Nov-2023-219172

.cargo_vcs_info.jsonD23-Nov-202374 65

.gitignoreD23-Nov-202330 43

Android.bpD23-Nov-20232 KiB5853

CHANGELOG.mdD23-Nov-20238.5 KiB284167

Cargo.tomlD23-Nov-20231.4 KiB4236

Cargo.toml.origD23-Nov-20231.1 KiB4033

LICENSED23-Nov-202310.6 KiB202169

LICENSE-APACHED23-Nov-202310.6 KiB202169

LICENSE-MITD23-Nov-20231 KiB2823

METADATAD23-Nov-2023406 2019

MODULE_LICENSE_APACHE2D23-Nov-20230

NOTICED23-Nov-202310.6 KiB202169

OWNERSD23-Nov-202362 32

README.mdD23-Nov-20232.5 KiB9767

publish.shD23-Nov-2023182 156

README.md

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