crates/arbitrary/src/lib.rs - platform/external/rust/android-crates-io - Git at Google

 // Copyright © 2019 The Rust Fuzz Project Developers.
 //
 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.

 //! The `Arbitrary` trait crate.
 //!
 //! This trait provides an [`Arbitrary`] trait to
 //! produce well-typed, structured values, from raw, byte buffers. It is
 //! generally intended to be used with fuzzers like AFL or libFuzzer. See the
 //! [`Arbitrary`] trait's documentation for details on
 //! automatically deriving, implementing, and/or using the trait.

 #![deny(bad_style)]
 #![deny(missing_docs)]
 #![deny(future_incompatible)]
 #![deny(nonstandard_style)]
 #![deny(rust_2018_compatibility)]
 #![deny(rust_2018_idioms)]
 #![deny(unused)]

 mod error;
 mod foreign;
 pub mod size_hint;
 pub mod unstructured;

 #[cfg(test)]
 mod tests;

 pub use error::*;

 #[cfg(feature = "derive_arbitrary")]
 pub use derive_arbitrary::*;

 #[doc(inline)]
 pub use unstructured::Unstructured;

 /// Error indicating that the maximum recursion depth has been reached while calculating [`Arbitrary::size_hint`]()
 #[derive(Debug, Clone)]
 #[non_exhaustive]
 pub struct MaxRecursionReached {}

 impl core::fmt::Display for MaxRecursionReached {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         f.write_str("Maximum recursion depth has been reached")
     }
 }

 impl std::error::Error for MaxRecursionReached {}

 /// Generate arbitrary structured values from raw, unstructured data.
 ///
 /// The `Arbitrary` trait allows you to generate valid structured values, like
 /// `HashMap`s, or ASTs, or `MyTomlConfig`, or any other data structure from
 /// raw, unstructured bytes provided by a fuzzer.
 ///
 /// # Deriving `Arbitrary`
 ///
 /// Automatically deriving the `Arbitrary` trait is the recommended way to
 /// implement `Arbitrary` for your types.
 ///
 /// Using the custom derive requires that you enable the `"derive"` cargo
 /// feature in your `Cargo.toml`:
 ///
 /// ```toml
 /// [dependencies]
 /// arbitrary = { version = "1", features = ["derive"] }
 /// ```
 ///
 /// Then, you add the `#[derive(Arbitrary)]` annotation to your `struct` or
 /// `enum` type definition:
 ///
 /// ```
 /// # #[cfg(feature = "derive")] mod foo {
 /// use arbitrary::Arbitrary;
 /// use std::collections::HashSet;
 ///
 /// #[derive(Arbitrary)]
 /// pub struct AddressBook {
 ///     friends: HashSet<Friend>,
 /// }
 ///
 /// #[derive(Arbitrary, Hash, Eq, PartialEq)]
 /// pub enum Friend {
 ///     Buddy { name: String },
 ///     Pal { age: usize },
 /// }
 /// # }
 /// ```
 ///
 /// Every member of the `struct` or `enum` must also implement `Arbitrary`.
 ///
 /// It is also possible to change the default bounds added by the derive:
 ///
 /// ```
 /// # #[cfg(feature = "derive")] mod foo {
 /// use arbitrary::Arbitrary;
 ///
 /// trait Trait {
 ///     type Assoc: for<'a> Arbitrary<'a>;
 /// }
 ///
 /// #[derive(Arbitrary)]
 /// // The bounds are used verbatim, so any existing trait bounds will need to be repeated.
 /// #[arbitrary(bound = "T: Trait")]
 /// struct Point<T: Trait> {
 ///     x: T::Assoc,
 /// }
 /// # }
 /// ```
 ///
 /// # Implementing `Arbitrary` By Hand
 ///
 /// Implementing `Arbitrary` mostly involves nested calls to other `Arbitrary`
 /// arbitrary implementations for each of your `struct` or `enum`'s members. But
 /// sometimes you need some amount of raw data, or you need to generate a
 /// variably-sized collection type, or something of that sort. The
 /// [`Unstructured`] type helps you with these tasks.
 ///
 /// ```
 /// # #[cfg(feature = "derive")] mod foo {
 /// # pub struct MyCollection<T> { _t: std::marker::PhantomData<T> }
 /// # impl<T> MyCollection<T> {
 /// #     pub fn new() -> Self { MyCollection { _t: std::marker::PhantomData } }
 /// #     pub fn insert(&mut self, element: T) {}
 /// # }
 /// use arbitrary::{Arbitrary, Result, Unstructured};
 ///
 /// impl<'a, T> Arbitrary<'a> for MyCollection<T>
 /// where
 ///     T: Arbitrary<'a>,
 /// {
 ///     fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> {
 ///         // Get an iterator of arbitrary `T`s.
 ///         let iter = u.arbitrary_iter::<T>()?;
 ///
 ///         // And then create a collection!
 ///         let mut my_collection = MyCollection::new();
 ///         for elem_result in iter {
 ///             let elem = elem_result?;
 ///             my_collection.insert(elem);
 ///         }
 ///
 ///         Ok(my_collection)
 ///     }
 /// }
 /// # }
 /// ```
 ///
 /// # A Note On Output Distributions
 ///
 /// There is no requirement for a particular distribution of the values. For
 /// example, it is not required that every value appears with the same
 /// probability. That being said, the main use for `Arbitrary` is for fuzzing,
 /// so in many cases a uniform distribution will make the most sense in order to
 /// provide the best coverage of the domain. In other cases this is not
 /// desirable or even possible, for example when sampling from a uniform
 /// distribution is computationally expensive or in the case of collections that
 /// may grow indefinitely.
 pub trait Arbitrary<'a>: Sized {
     /// Generate an arbitrary value of `Self` from the given unstructured data.
     ///
     /// Calling `Arbitrary::arbitrary` requires that you have some raw data,
     /// perhaps given to you by a fuzzer like AFL or libFuzzer. You wrap this
     /// raw data in an `Unstructured`, and then you can call `<MyType as
     /// Arbitrary>::arbitrary` to construct an arbitrary instance of `MyType`
     /// from that unstructured data.
     ///
     /// Implementations may return an error if there is not enough data to
     /// construct a full instance of `Self`, or they may fill out the rest of
     /// `Self` with dummy values. Using dummy values when the underlying data is
     /// exhausted can help avoid accidentally "defeating" some of the fuzzer's
     /// mutations to the underlying byte stream that might otherwise lead to
     /// interesting runtime behavior or new code coverage if only we had just a
     /// few more bytes. However, it also requires that implementations for
     /// recursive types (e.g. `struct Foo(Option<Box<Foo>>)`) avoid infinite
     /// recursion when the underlying data is exhausted.
     ///
     /// ```
     /// # #[cfg(feature = "derive")] fn foo() {
     /// use arbitrary::{Arbitrary, Unstructured};
     ///
     /// #[derive(Arbitrary)]
     /// pub struct MyType {
     ///     // ...
     /// }
     ///
     /// // Get the raw data from the fuzzer or wherever else.
     /// # let get_raw_data_from_fuzzer = || &[];
     /// let raw_data: &[u8] = get_raw_data_from_fuzzer();
     ///
     /// // Wrap that raw data in an `Unstructured`.
     /// let mut unstructured = Unstructured::new(raw_data);
     ///
     /// // Generate an arbitrary instance of `MyType` and do stuff with it.
     /// if let Ok(value) = MyType::arbitrary(&mut unstructured) {
     /// #   let do_stuff = |_| {};
     ///     do_stuff(value);
     /// }
     /// # }
     /// ```
     ///
     /// See also the documentation for [`Unstructured`].
     fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self>;

     /// Generate an arbitrary value of `Self` from the entirety of the given
     /// unstructured data.
     ///
     /// This is similar to Arbitrary::arbitrary, however it assumes that it is
     /// the last consumer of the given data, and is thus able to consume it all
     /// if it needs.  See also the documentation for
     /// [`Unstructured`].
     fn arbitrary_take_rest(mut u: Unstructured<'a>) -> Result<Self> {
         Self::arbitrary(&mut u)
     }

     /// Get a size hint for how many bytes out of an `Unstructured` this type
     /// needs to construct itself.
     ///
     /// This is useful for determining how many elements we should insert when
     /// creating an arbitrary collection.
     ///
     /// The return value is similar to [`Iterator::size_hint`]: it returns a
     /// tuple where the first element is a lower bound on the number of bytes
     /// required, and the second element is an optional upper bound.
     ///
     /// The default implementation return `(0, None)` which is correct for any
     /// type, but not ultimately that useful. Using `#[derive(Arbitrary)]` will
     /// create a better implementation. If you are writing an `Arbitrary`
     /// implementation by hand, and your type can be part of a dynamically sized
     /// collection (such as `Vec`), you are strongly encouraged to override this
     /// default with a better implementation, and also override
     /// [`try_size_hint`].
     ///
     /// ## How to implement this
     ///
     /// If the size hint calculation is a trivial constant and does not recurse
     /// into any other `size_hint` call, you should implement it in `size_hint`:
     ///
     /// ```
     /// use arbitrary::{size_hint, Arbitrary, Result, Unstructured};
     ///
     /// struct SomeStruct(u8);
     ///
     /// impl<'a> Arbitrary<'a> for SomeStruct {
     ///     fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> {
     ///         let buf = &mut [0];
     ///         u.fill_buffer(buf)?;
     ///         Ok(SomeStruct(buf[0]))
     ///     }
     ///
     ///     #[inline]
     ///     fn size_hint(depth: usize) -> (usize, Option<usize>) {
     ///         let _ = depth;
     ///         (1, Some(1))
     ///     }
     /// }
     /// ```
     ///
     /// Otherwise, it should instead be implemented in [`try_size_hint`],
     /// and the `size_hint` implementation should forward to it:
     ///
     /// ```
     /// use arbitrary::{size_hint, Arbitrary, MaxRecursionReached, Result, Unstructured};
     ///
     /// struct SomeStruct<A, B> {
     ///     a: A,
     ///     b: B,
     /// }
     ///
     /// impl<'a, A: Arbitrary<'a>, B: Arbitrary<'a>> Arbitrary<'a> for SomeStruct<A, B> {
     ///     fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> {
     ///         // ...
     /// #       todo!()
     ///     }
     ///
     ///     fn size_hint(depth: usize) -> (usize, Option<usize>) {
     ///         // Return the value of try_size_hint
     ///         //
     ///         // If the recursion fails, return the default, always valid `(0, None)`
     ///         Self::try_size_hint(depth).unwrap_or_default()
     ///     }
     ///
     ///     fn try_size_hint(depth: usize) -> Result<(usize, Option<usize>), MaxRecursionReached> {
     ///         // Protect against potential infinite recursion with
     ///         // `try_recursion_guard`.
     ///         size_hint::try_recursion_guard(depth, |depth| {
     ///             // If we aren't too deep, then `recursion_guard` calls
     ///             // this closure, which implements the natural size hint.
     ///             // Don't forget to use the new `depth` in all nested
     ///             // `try_size_hint` calls! We recommend shadowing the
     ///             // parameter, like what is done here, so that you can't
     ///             // accidentally use the wrong depth.
     ///             Ok(size_hint::and(
     ///                 <A as Arbitrary>::try_size_hint(depth)?,
     ///                 <B as Arbitrary>::try_size_hint(depth)?,
     ///             ))
     ///         })
     ///     }
     /// }
     /// ```
     ///
     /// ## Invariant
     ///
     /// It must be possible to construct every possible output using only inputs
     /// of lengths bounded by these parameters. This applies to both
     /// [`Arbitrary::arbitrary`] and [`Arbitrary::arbitrary_take_rest`].
     ///
     /// This is trivially true for `(0, None)`. To restrict this further, it
     /// must be proven that all inputs that are now excluded produced redundant
     /// outputs which are still possible to produce using the reduced input
     /// space.
     ///
     /// [iterator-size-hint]: https://doc.rust-lang.org/stable/std/iter/trait.Iterator.html#method.size_hint
     /// [`try_size_hint`]: Arbitrary::try_size_hint
     #[inline]
     fn size_hint(depth: usize) -> (usize, Option<usize>) {
         let _ = depth;
         (0, None)
     }

     /// Get a size hint for how many bytes out of an `Unstructured` this type
     /// needs to construct itself.
     ///
     /// Unlike [`size_hint`], this function keeps the information that the
     /// recursion limit was reached. This is required to "short circuit" the
     /// calculation and avoid exponential blowup with recursive structures.
     ///
     /// If you are implementing [`size_hint`] for a struct that could be
     /// recursive, you should implement `try_size_hint` and call the
     /// `try_size_hint` when recursing
     ///
     ///
     /// The return value is similar to [`core::iter::Iterator::size_hint`]: it
     /// returns a tuple where the first element is a lower bound on the number
     /// of bytes required, and the second element is an optional upper bound.
     ///
     /// The default implementation returns the value of [`size_hint`] which is
     /// correct for any type, but might lead to exponential blowup when dealing
     /// with recursive types.
     ///
     /// ## Invariant
     ///
     /// It must be possible to construct every possible output using only inputs
     /// of lengths bounded by these parameters. This applies to both
     /// [`Arbitrary::arbitrary`] and [`Arbitrary::arbitrary_take_rest`].
     ///
     /// This is trivially true for `(0, None)`. To restrict this further, it
     /// must be proven that all inputs that are now excluded produced redundant
     /// outputs which are still possible to produce using the reduced input
     /// space.
     ///
     /// ## When to implement `try_size_hint`
     ///
     /// If you 100% know that the type you are implementing `Arbitrary` for is
     /// not a recursive type, or your implementation is not transitively calling
     /// any other `size_hint` methods, you may implement [`size_hint`], and the
     /// default `try_size_hint` implementation will use it.
     ///
     /// Note that if you are implementing `Arbitrary` for a generic type, you
     /// cannot guarantee the lack of type recursion!
     ///
     /// Otherwise, when there is possible type recursion, you should implement
     /// `try_size_hint` instead.
     ///
     /// ## The `depth` parameter
     ///
     /// When implementing `try_size_hint`, you need to use
     /// [`arbitrary::size_hint::try_recursion_guard(depth)`][crate::size_hint::try_recursion_guard]
     /// to prevent potential infinite recursion when calculating size hints for
     /// potentially recursive types:
     ///
     /// ```
     /// use arbitrary::{size_hint, Arbitrary, MaxRecursionReached, Unstructured};
     ///
     /// // This can potentially be a recursive type if `L` or `R` contain
     /// // something like `Box<Option<MyEither<L, R>>>`!
     /// enum MyEither<L, R> {
     ///     Left(L),
     ///     Right(R),
     /// }
     ///
     /// impl<'a, L, R> Arbitrary<'a> for MyEither<L, R>
     /// where
     ///     L: Arbitrary<'a>,
     ///     R: Arbitrary<'a>,
     /// {
     ///     fn arbitrary(u: &mut Unstructured) -> arbitrary::Result<Self> {
     ///         // ...
     /// #       unimplemented!()
     ///     }
     ///
     ///     fn size_hint(depth: usize) -> (usize, Option<usize>) {
     ///         // Return the value of `try_size_hint`
     ///         //
     ///         // If the recursion fails, return the default `(0, None)` range,
     ///         // which is always valid.
     ///         Self::try_size_hint(depth).unwrap_or_default()
     ///     }
     ///
     ///     fn try_size_hint(depth: usize) -> Result<(usize, Option<usize>), MaxRecursionReached> {
     ///         // Protect against potential infinite recursion with
     ///         // `try_recursion_guard`.
     ///         size_hint::try_recursion_guard(depth, |depth| {
     ///             // If we aren't too deep, then `recursion_guard` calls
     ///             // this closure, which implements the natural size hint.
     ///             // Don't forget to use the new `depth` in all nested
     ///             // `try_size_hint` calls! We recommend shadowing the
     ///             // parameter, like what is done here, so that you can't
     ///             // accidentally use the wrong depth.
     ///             Ok(size_hint::or(
     ///                 <L as Arbitrary>::try_size_hint(depth)?,
     ///                 <R as Arbitrary>::try_size_hint(depth)?,
     ///             ))
     ///         })
     ///     }
     /// }
     /// ```
     #[inline]
     fn try_size_hint(depth: usize) -> Result<(usize, Option<usize>), MaxRecursionReached> {
         Ok(Self::size_hint(depth))
     }
 }

 /// Multiple conflicting arbitrary attributes are used on the same field:
 /// ```compile_fail
 /// #[derive(::arbitrary::Arbitrary)]
 /// struct Point {
 ///     #[arbitrary(value = 2)]
 ///     #[arbitrary(value = 2)]
 ///     x: i32,
 /// }
 /// ```
 ///
 /// An unknown attribute:
 /// ```compile_fail
 /// #[derive(::arbitrary::Arbitrary)]
 /// struct Point {
 ///     #[arbitrary(unknown_attr)]
 ///     x: i32,
 /// }
 /// ```
 ///
 /// An unknown attribute with a value:
 /// ```compile_fail
 /// #[derive(::arbitrary::Arbitrary)]
 /// struct Point {
 ///     #[arbitrary(unknown_attr = 13)]
 ///     x: i32,
 /// }
 /// ```
 ///
 /// `value` without RHS:
 /// ```compile_fail
 /// #[derive(::arbitrary::Arbitrary)]
 /// struct Point {
 ///     #[arbitrary(value)]
 ///     x: i32,
 /// }
 /// ```
 ///
 /// `with` without RHS:
 /// ```compile_fail
 /// #[derive(::arbitrary::Arbitrary)]
 /// struct Point {
 ///     #[arbitrary(with)]
 ///     x: i32,
 /// }
 /// ```
 ///
 /// Multiple conflicting bounds at the container-level:
 /// ```compile_fail
 /// #[derive(::arbitrary::Arbitrary)]
 /// #[arbitrary(bound = "T: Default")]
 /// #[arbitrary(bound = "T: Default")]
 /// struct Point<T: Default> {
 ///     #[arbitrary(default)]
 ///     x: T,
 /// }
 /// ```
 ///
 /// Multiple conflicting bounds in a single bound attribute:
 /// ```compile_fail
 /// #[derive(::arbitrary::Arbitrary)]
 /// #[arbitrary(bound = "T: Default, T: Default")]
 /// struct Point<T: Default> {
 ///     #[arbitrary(default)]
 ///     x: T,
 /// }
 /// ```
 ///
 /// Multiple conflicting bounds in multiple bound attributes:
 /// ```compile_fail
 /// #[derive(::arbitrary::Arbitrary)]
 /// #[arbitrary(bound = "T: Default", bound = "T: Default")]
 /// struct Point<T: Default> {
 ///     #[arbitrary(default)]
 ///     x: T,
 /// }
 /// ```
 ///
 /// Too many bounds supplied:
 /// ```compile_fail
 /// #[derive(::arbitrary::Arbitrary)]
 /// #[arbitrary(bound = "T: Default")]
 /// struct Point {
 ///     x: i32,
 /// }
 /// ```
 ///
 /// Too many bounds supplied across multiple attributes:
 /// ```compile_fail
 /// #[derive(::arbitrary::Arbitrary)]
 /// #[arbitrary(bound = "T: Default")]
 /// #[arbitrary(bound = "U: Default")]
 /// struct Point<T: Default> {
 ///     #[arbitrary(default)]
 ///     x: T,
 /// }
 /// ```
 ///
 /// Attempt to use the derive attribute on an enum variant:
 /// ```compile_fail
 /// #[derive(::arbitrary::Arbitrary)]
 /// enum Enum<T: Default> {
 ///     #[arbitrary(default)]
 ///     Variant(T),
 /// }
 /// ```
 #[cfg(all(doctest, feature = "derive"))]
 pub struct CompileFailTests;
	// Copyright © 2019 The Rust Fuzz Project Developers.
	//
	// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
	// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
	// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
	// option. This file may not be copied, modified, or distributed
	// except according to those terms.

	//! The `Arbitrary` trait crate.
	//!
	//! This trait provides an [`Arbitrary`] trait to
	//! produce well-typed, structured values, from raw, byte buffers. It is
	//! generally intended to be used with fuzzers like AFL or libFuzzer. See the
	//! [`Arbitrary`] trait's documentation for details on
	//! automatically deriving, implementing, and/or using the trait.

	#![deny(bad_style)]
	#![deny(missing_docs)]
	#![deny(future_incompatible)]
	#![deny(nonstandard_style)]
	#![deny(rust_2018_compatibility)]
	#![deny(rust_2018_idioms)]
	#![deny(unused)]

	mod error;
	mod foreign;
	pub mod size_hint;
	pub mod unstructured;

	#[cfg(test)]
	mod tests;

	pub use error::*;

	#[cfg(feature = "derive_arbitrary")]
	pub use derive_arbitrary::*;

	#[doc(inline)]
	pub use unstructured::Unstructured;

	/// Error indicating that the maximum recursion depth has been reached while calculating [`Arbitrary::size_hint`]()
	#[derive(Debug, Clone)]
	#[non_exhaustive]
	pub struct MaxRecursionReached {}

	impl core::fmt::Display for MaxRecursionReached {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
	f.write_str("Maximum recursion depth has been reached")
	}
	}

	impl std::error::Error for MaxRecursionReached {}

	/// Generate arbitrary structured values from raw, unstructured data.
	///
	/// The `Arbitrary` trait allows you to generate valid structured values, like
	/// `HashMap`s, or ASTs, or `MyTomlConfig`, or any other data structure from
	/// raw, unstructured bytes provided by a fuzzer.
	///
	/// # Deriving `Arbitrary`
	///
	/// Automatically deriving the `Arbitrary` trait is the recommended way to
	/// implement `Arbitrary` for your types.
	///
	/// Using the custom derive requires that you enable the `"derive"` cargo
	/// feature in your `Cargo.toml`:
	///
	/// ```toml
	/// [dependencies]
	/// arbitrary = { version = "1", features = ["derive"] }
	/// ```
	///
	/// Then, you add the `#[derive(Arbitrary)]` annotation to your `struct` or
	/// `enum` type definition:
	///
	/// ```
	/// # #[cfg(feature = "derive")] mod foo {
	/// use arbitrary::Arbitrary;
	/// use std::collections::HashSet;
	///
	/// #[derive(Arbitrary)]
	/// pub struct AddressBook {
	/// friends: HashSet<Friend>,
	/// }
	///
	/// #[derive(Arbitrary, Hash, Eq, PartialEq)]
	/// pub enum Friend {
	/// Buddy { name: String },
	/// Pal { age: usize },
	/// }
	/// # }
	/// ```
	///
	/// Every member of the `struct` or `enum` must also implement `Arbitrary`.
	///
	/// It is also possible to change the default bounds added by the derive:
	///
	/// ```
	/// # #[cfg(feature = "derive")] mod foo {
	/// use arbitrary::Arbitrary;
	///
	/// trait Trait {
	/// type Assoc: for<'a> Arbitrary<'a>;
	/// }
	///
	/// #[derive(Arbitrary)]
	/// // The bounds are used verbatim, so any existing trait bounds will need to be repeated.
	/// #[arbitrary(bound = "T: Trait")]
	/// struct Point<T: Trait> {
	/// x: T::Assoc,
	/// }
	/// # }
	/// ```
	///
	/// # Implementing `Arbitrary` By Hand
	///
	/// Implementing `Arbitrary` mostly involves nested calls to other `Arbitrary`
	/// arbitrary implementations for each of your `struct` or `enum`'s members. But
	/// sometimes you need some amount of raw data, or you need to generate a
	/// variably-sized collection type, or something of that sort. The
	/// [`Unstructured`] type helps you with these tasks.
	///
	/// ```
	/// # #[cfg(feature = "derive")] mod foo {
	/// # pub struct MyCollection<T> { _t: std::marker::PhantomData<T> }
	/// # impl<T> MyCollection<T> {
	/// # pub fn new() -> Self { MyCollection { _t: std::marker::PhantomData } }
	/// # pub fn insert(&mut self, element: T) {}
	/// # }
	/// use arbitrary::{Arbitrary, Result, Unstructured};
	///
	/// impl<'a, T> Arbitrary<'a> for MyCollection<T>
	/// where
	/// T: Arbitrary<'a>,
	/// {
	/// fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> {
	/// // Get an iterator of arbitrary `T`s.
	/// let iter = u.arbitrary_iter::<T>()?;
	///
	/// // And then create a collection!
	/// let mut my_collection = MyCollection::new();
	/// for elem_result in iter {
	/// let elem = elem_result?;
	/// my_collection.insert(elem);
	/// }
	///
	/// Ok(my_collection)
	/// }
	/// }
	/// # }
	/// ```
	///
	/// # A Note On Output Distributions
	///
	/// There is no requirement for a particular distribution of the values. For
	/// example, it is not required that every value appears with the same
	/// probability. That being said, the main use for `Arbitrary` is for fuzzing,
	/// so in many cases a uniform distribution will make the most sense in order to
	/// provide the best coverage of the domain. In other cases this is not
	/// desirable or even possible, for example when sampling from a uniform
	/// distribution is computationally expensive or in the case of collections that
	/// may grow indefinitely.
	pub trait Arbitrary<'a>: Sized {
	/// Generate an arbitrary value of `Self` from the given unstructured data.
	///
	/// Calling `Arbitrary::arbitrary` requires that you have some raw data,
	/// perhaps given to you by a fuzzer like AFL or libFuzzer. You wrap this
	/// raw data in an `Unstructured`, and then you can call `<MyType as
	/// Arbitrary>::arbitrary` to construct an arbitrary instance of `MyType`
	/// from that unstructured data.
	///
	/// Implementations may return an error if there is not enough data to
	/// construct a full instance of `Self`, or they may fill out the rest of
	/// `Self` with dummy values. Using dummy values when the underlying data is
	/// exhausted can help avoid accidentally "defeating" some of the fuzzer's
	/// mutations to the underlying byte stream that might otherwise lead to
	/// interesting runtime behavior or new code coverage if only we had just a
	/// few more bytes. However, it also requires that implementations for
	/// recursive types (e.g. `struct Foo(Option<Box<Foo>>)`) avoid infinite
	/// recursion when the underlying data is exhausted.
	///
	/// ```
	/// # #[cfg(feature = "derive")] fn foo() {
	/// use arbitrary::{Arbitrary, Unstructured};
	///
	/// #[derive(Arbitrary)]
	/// pub struct MyType {
	/// // ...
	/// }
	///
	/// // Get the raw data from the fuzzer or wherever else.
	/// # let get_raw_data_from_fuzzer = \|\| &[];
	/// let raw_data: &[u8] = get_raw_data_from_fuzzer();
	///
	/// // Wrap that raw data in an `Unstructured`.
	/// let mut unstructured = Unstructured::new(raw_data);
	///
	/// // Generate an arbitrary instance of `MyType` and do stuff with it.
	/// if let Ok(value) = MyType::arbitrary(&mut unstructured) {
	/// # let do_stuff = \|_\| {};
	/// do_stuff(value);
	/// }
	/// # }
	/// ```
	///
	/// See also the documentation for [`Unstructured`].
	fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self>;

	/// Generate an arbitrary value of `Self` from the entirety of the given
	/// unstructured data.
	///
	/// This is similar to Arbitrary::arbitrary, however it assumes that it is
	/// the last consumer of the given data, and is thus able to consume it all
	/// if it needs. See also the documentation for
	/// [`Unstructured`].
	fn arbitrary_take_rest(mut u: Unstructured<'a>) -> Result<Self> {
	Self::arbitrary(&mut u)
	}

	/// Get a size hint for how many bytes out of an `Unstructured` this type
	/// needs to construct itself.
	///
	/// This is useful for determining how many elements we should insert when
	/// creating an arbitrary collection.
	///
	/// The return value is similar to [`Iterator::size_hint`]: it returns a
	/// tuple where the first element is a lower bound on the number of bytes
	/// required, and the second element is an optional upper bound.
	///
	/// The default implementation return `(0, None)` which is correct for any
	/// type, but not ultimately that useful. Using `#[derive(Arbitrary)]` will
	/// create a better implementation. If you are writing an `Arbitrary`
	/// implementation by hand, and your type can be part of a dynamically sized
	/// collection (such as `Vec`), you are strongly encouraged to override this
	/// default with a better implementation, and also override
	/// [`try_size_hint`].
	///
	/// ## How to implement this
	///
	/// If the size hint calculation is a trivial constant and does not recurse
	/// into any other `size_hint` call, you should implement it in `size_hint`:
	///
	/// ```
	/// use arbitrary::{size_hint, Arbitrary, Result, Unstructured};
	///
	/// struct SomeStruct(u8);
	///
	/// impl<'a> Arbitrary<'a> for SomeStruct {
	/// fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> {
	/// let buf = &mut [0];
	/// u.fill_buffer(buf)?;
	/// Ok(SomeStruct(buf[0]))
	/// }
	///
	/// #[inline]
	/// fn size_hint(depth: usize) -> (usize, Option<usize>) {
	/// let _ = depth;
	/// (1, Some(1))
	/// }
	/// }
	/// ```
	///
	/// Otherwise, it should instead be implemented in [`try_size_hint`],
	/// and the `size_hint` implementation should forward to it:
	///
	/// ```
	/// use arbitrary::{size_hint, Arbitrary, MaxRecursionReached, Result, Unstructured};
	///
	/// struct SomeStruct<A, B> {
	/// a: A,
	/// b: B,
	/// }
	///
	/// impl<'a, A: Arbitrary<'a>, B: Arbitrary<'a>> Arbitrary<'a> for SomeStruct<A, B> {
	/// fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> {
	/// // ...
	/// # todo!()
	/// }
	///
	/// fn size_hint(depth: usize) -> (usize, Option<usize>) {
	/// // Return the value of try_size_hint
	/// //
	/// // If the recursion fails, return the default, always valid `(0, None)`
	/// Self::try_size_hint(depth).unwrap_or_default()
	/// }
	///
	/// fn try_size_hint(depth: usize) -> Result<(usize, Option<usize>), MaxRecursionReached> {
	/// // Protect against potential infinite recursion with
	/// // `try_recursion_guard`.
	/// size_hint::try_recursion_guard(depth, \|depth\| {
	/// // If we aren't too deep, then `recursion_guard` calls
	/// // this closure, which implements the natural size hint.
	/// // Don't forget to use the new `depth` in all nested
	/// // `try_size_hint` calls! We recommend shadowing the
	/// // parameter, like what is done here, so that you can't
	/// // accidentally use the wrong depth.
	/// Ok(size_hint::and(
	/// <A as Arbitrary>::try_size_hint(depth)?,
	/// <B as Arbitrary>::try_size_hint(depth)?,
	/// ))
	/// })
	/// }
	/// }
	/// ```
	///
	/// ## Invariant
	///
	/// It must be possible to construct every possible output using only inputs
	/// of lengths bounded by these parameters. This applies to both
	/// [`Arbitrary::arbitrary`] and [`Arbitrary::arbitrary_take_rest`].
	///
	/// This is trivially true for `(0, None)`. To restrict this further, it
	/// must be proven that all inputs that are now excluded produced redundant
	/// outputs which are still possible to produce using the reduced input
	/// space.
	///
	/// [iterator-size-hint]: https://doc.rust-lang.org/stable/std/iter/trait.Iterator.html#method.size_hint
	/// [`try_size_hint`]: Arbitrary::try_size_hint
	#[inline]
	fn size_hint(depth: usize) -> (usize, Option<usize>) {
	let _ = depth;
	(0, None)
	}

	/// Get a size hint for how many bytes out of an `Unstructured` this type
	/// needs to construct itself.
	///
	/// Unlike [`size_hint`], this function keeps the information that the
	/// recursion limit was reached. This is required to "short circuit" the
	/// calculation and avoid exponential blowup with recursive structures.
	///
	/// If you are implementing [`size_hint`] for a struct that could be
	/// recursive, you should implement `try_size_hint` and call the
	/// `try_size_hint` when recursing
	///
	///
	/// The return value is similar to [`core::iter::Iterator::size_hint`]: it
	/// returns a tuple where the first element is a lower bound on the number
	/// of bytes required, and the second element is an optional upper bound.
	///
	/// The default implementation returns the value of [`size_hint`] which is
	/// correct for any type, but might lead to exponential blowup when dealing
	/// with recursive types.
	///
	/// ## Invariant
	///
	/// It must be possible to construct every possible output using only inputs
	/// of lengths bounded by these parameters. This applies to both
	/// [`Arbitrary::arbitrary`] and [`Arbitrary::arbitrary_take_rest`].
	///
	/// This is trivially true for `(0, None)`. To restrict this further, it
	/// must be proven that all inputs that are now excluded produced redundant
	/// outputs which are still possible to produce using the reduced input
	/// space.
	///
	/// ## When to implement `try_size_hint`
	///
	/// If you 100% know that the type you are implementing `Arbitrary` for is
	/// not a recursive type, or your implementation is not transitively calling
	/// any other `size_hint` methods, you may implement [`size_hint`], and the
	/// default `try_size_hint` implementation will use it.
	///
	/// Note that if you are implementing `Arbitrary` for a generic type, you
	/// cannot guarantee the lack of type recursion!
	///
	/// Otherwise, when there is possible type recursion, you should implement
	/// `try_size_hint` instead.
	///
	/// ## The `depth` parameter
	///
	/// When implementing `try_size_hint`, you need to use
	/// [`arbitrary::size_hint::try_recursion_guard(depth)`][crate::size_hint::try_recursion_guard]
	/// to prevent potential infinite recursion when calculating size hints for
	/// potentially recursive types:
	///
	/// ```
	/// use arbitrary::{size_hint, Arbitrary, MaxRecursionReached, Unstructured};
	///
	/// // This can potentially be a recursive type if `L` or `R` contain
	/// // something like `Box<Option<MyEither<L, R>>>`!
	/// enum MyEither<L, R> {
	/// Left(L),
	/// Right(R),
	/// }
	///
	/// impl<'a, L, R> Arbitrary<'a> for MyEither<L, R>
	/// where
	/// L: Arbitrary<'a>,
	/// R: Arbitrary<'a>,
	/// {
	/// fn arbitrary(u: &mut Unstructured) -> arbitrary::Result<Self> {
	/// // ...
	/// # unimplemented!()
	/// }
	///
	/// fn size_hint(depth: usize) -> (usize, Option<usize>) {
	/// // Return the value of `try_size_hint`
	/// //
	/// // If the recursion fails, return the default `(0, None)` range,
	/// // which is always valid.
	/// Self::try_size_hint(depth).unwrap_or_default()
	/// }
	///
	/// fn try_size_hint(depth: usize) -> Result<(usize, Option<usize>), MaxRecursionReached> {
	/// // Protect against potential infinite recursion with
	/// // `try_recursion_guard`.
	/// size_hint::try_recursion_guard(depth, \|depth\| {
	/// // If we aren't too deep, then `recursion_guard` calls
	/// // this closure, which implements the natural size hint.
	/// // Don't forget to use the new `depth` in all nested
	/// // `try_size_hint` calls! We recommend shadowing the
	/// // parameter, like what is done here, so that you can't
	/// // accidentally use the wrong depth.
	/// Ok(size_hint::or(
	/// <L as Arbitrary>::try_size_hint(depth)?,
	/// <R as Arbitrary>::try_size_hint(depth)?,
	/// ))
	/// })
	/// }
	/// }
	/// ```
	#[inline]
	fn try_size_hint(depth: usize) -> Result<(usize, Option<usize>), MaxRecursionReached> {
	Ok(Self::size_hint(depth))
	}
	}

	/// Multiple conflicting arbitrary attributes are used on the same field:
	/// ```compile_fail
	/// #[derive(::arbitrary::Arbitrary)]
	/// struct Point {
	/// #[arbitrary(value = 2)]
	/// #[arbitrary(value = 2)]
	/// x: i32,
	/// }
	/// ```
	///
	/// An unknown attribute:
	/// ```compile_fail
	/// #[derive(::arbitrary::Arbitrary)]
	/// struct Point {
	/// #[arbitrary(unknown_attr)]
	/// x: i32,
	/// }
	/// ```
	///
	/// An unknown attribute with a value:
	/// ```compile_fail
	/// #[derive(::arbitrary::Arbitrary)]
	/// struct Point {
	/// #[arbitrary(unknown_attr = 13)]
	/// x: i32,
	/// }
	/// ```
	///
	/// `value` without RHS:
	/// ```compile_fail
	/// #[derive(::arbitrary::Arbitrary)]
	/// struct Point {
	/// #[arbitrary(value)]
	/// x: i32,
	/// }
	/// ```
	///
	/// `with` without RHS:
	/// ```compile_fail
	/// #[derive(::arbitrary::Arbitrary)]
	/// struct Point {
	/// #[arbitrary(with)]
	/// x: i32,
	/// }
	/// ```
	///
	/// Multiple conflicting bounds at the container-level:
	/// ```compile_fail
	/// #[derive(::arbitrary::Arbitrary)]
	/// #[arbitrary(bound = "T: Default")]
	/// #[arbitrary(bound = "T: Default")]
	/// struct Point<T: Default> {
	/// #[arbitrary(default)]
	/// x: T,
	/// }
	/// ```
	///
	/// Multiple conflicting bounds in a single bound attribute:
	/// ```compile_fail
	/// #[derive(::arbitrary::Arbitrary)]
	/// #[arbitrary(bound = "T: Default, T: Default")]
	/// struct Point<T: Default> {
	/// #[arbitrary(default)]
	/// x: T,
	/// }
	/// ```
	///
	/// Multiple conflicting bounds in multiple bound attributes:
	/// ```compile_fail
	/// #[derive(::arbitrary::Arbitrary)]
	/// #[arbitrary(bound = "T: Default", bound = "T: Default")]
	/// struct Point<T: Default> {
	/// #[arbitrary(default)]
	/// x: T,
	/// }
	/// ```
	///
	/// Too many bounds supplied:
	/// ```compile_fail
	/// #[derive(::arbitrary::Arbitrary)]
	/// #[arbitrary(bound = "T: Default")]
	/// struct Point {
	/// x: i32,
	/// }
	/// ```
	///
	/// Too many bounds supplied across multiple attributes:
	/// ```compile_fail
	/// #[derive(::arbitrary::Arbitrary)]
	/// #[arbitrary(bound = "T: Default")]
	/// #[arbitrary(bound = "U: Default")]
	/// struct Point<T: Default> {
	/// #[arbitrary(default)]
	/// x: T,
	/// }
	/// ```
	///
	/// Attempt to use the derive attribute on an enum variant:
	/// ```compile_fail
	/// #[derive(::arbitrary::Arbitrary)]
	/// enum Enum<T: Default> {
	/// #[arbitrary(default)]
	/// Variant(T),
	/// }
	/// ```
	#[cfg(all(doctest, feature = "derive"))]
	pub struct CompileFailTests;