Debian Codegraph @

.cargo/vendor/arbitrary/README.md

raw
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
13 The `Arbitrary` crate lets you construct arbitrary instances of a type.
14
15 This crate is primarily intended to be combined with a fuzzer like [libFuzzer
16 and `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,
18 untyped byte buffers that they produce into well-typed, valid, structured
19 values. This allows you to combine structure-aware test case generation with
20 coverage-guided, mutation-based fuzzers.
21
22 ## Documentation
23
24 [**Read the API documentation on `docs.rs`!**](https://docs.rs/arbitrary)
25
26 ## Example
27
28 Say you're writing a color conversion library, and you have an `Rgb` struct to
29 represent RGB colors. You might want to implement `Arbitrary` for `Rgb` so that
30 you could take arbitrary `Rgb` instances in a test function that asserts some
31 property (for example, asserting that RGB converted to HSL and converted back to
32 RGB always ends up exactly where we started).
33
34 ### Automatically Deriving `Arbitrary`
35
36 Automatically deriving the `Arbitrary` trait is the recommended way to implement
37 `Arbitrary` for your types.
38
39 Automatically deriving `Arbitrary` requires you to enable the `"derive"` cargo
40 feature:
41
42 ```toml
43 # Cargo.toml
44
45 [dependencies]
46 arbitrary = { version = "1", features = ["derive"] }
47 ```
48
49 And then you can simply add `#[derive(Arbitrary)]` annotations to your types:
50
51 ```rust
52 // rgb.rs
53
54 use arbitrary::Arbitrary;
55
56 #[derive(Arbitrary)]
57 pub struct Rgb {
58 pub r: u8,
59 pub g: u8,
60 pub b: u8,
61 }
62 ```
63
64 #### Customizing single fields
65
66 This can be particular handy if your structure uses a type that does not implement `Arbitrary` or you want to have more customization for particular fields.
67
68 ```rust
69 #[derive(Arbitrary)]
70 pub struct Rgba {
71 // set `r` to Default::default()
72 #[arbitrary(default)]
73 pub r: u8,
74
75 // set `g` to 255
76 #[arbitrary(value = 255)]
77 pub g: u8,
78
79 // Generate `b` with a custom function of type
80 //
81 // fn(&mut Unstructured) -> arbitrary::Result<T>
82 //
83 // where `T` is the field's type.
84 #[arbitrary(with = arbitrary_b)]
85 pub b: u8,
86
87 // Generate `a` with a custom closure (shortcut to avoid a custom function)
88 #[arbitrary(with = |u: &mut Unstructured| u.int_in_range(0..=64))]
89 pub a: u8,
90 }
91
92 fn arbitrary_b(u: &mut Unstructured) -> arbitrary::Result<u8> {
93 u.int_in_range(64..=128)
94 }
95 ```
96
97 ### Implementing `Arbitrary` By Hand
98
99 Alternatively, you can write an `Arbitrary` implementation by hand:
100
101 ```rust
102 // rgb.rs
103
104 use arbitrary::{Arbitrary, Result, Unstructured};
105
106 #[derive(Copy, Clone, Debug)]
107 pub struct Rgb {
108 pub r: u8,
109 pub g: u8,
110 pub b: u8,
111 }
112
113 impl<'a> Arbitrary<'a> for Rgb {
114 fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> {
115 let r = u8::arbitrary(u)?;
116 let g = u8::arbitrary(u)?;
117 let b = u8::arbitrary(u)?;
118 Ok(Rgb { r, g, b })
119 }
120 }
121 ```
122
123 ## Minimum Supported Rust Version (MSRV)
124
125 <!-- NB: Keep this number in sync with the `rust-version` in `Cargo.toml`. -->
126
127 This crate is guaranteed to compile on stable Rust **1.63.0** and up. It might
128 compile with older versions but that may change in any new patch release.
129
130 We reserve the right to increment the MSRV on minor releases, however we will
131 strive to only do it deliberately and for good reasons.
132
133 ## License
134
135 Licensed under dual MIT or Apache-2.0 at your choice.
136
137 Unless you explicitly state otherwise, any contribution intentionally submitted
138 for inclusion in this project by you, as defined in the Apache-2.0 license,
139 shall be dual licensed as above, without any additional terms or conditions.