{"id":13546089,"url":"https://github.com/rust-fuzz/arbitrary","last_synced_at":"2025-05-13T17:13:27.586Z","repository":{"id":20678524,"uuid":"90591032","full_name":"rust-fuzz/arbitrary","owner":"rust-fuzz","description":"Generating structured data from arbitrary, unstructured input.","archived":false,"fork":false,"pushed_at":"2025-04-18T17:32:18.000Z","size":344,"stargazers_count":767,"open_issues_count":34,"forks_count":82,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-05-03T02:07:14.768Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.rs/arbitrary/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rust-fuzz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-05-08T05:51:27.000Z","updated_at":"2025-05-02T15:25:55.000Z","dependencies_parsed_at":"2023-02-16T02:16:10.146Z","dependency_job_id":"a0f5facf-0b76-4256-a89b-5120230eb9df","html_url":"https://github.com/rust-fuzz/arbitrary","commit_stats":{"total_commits":275,"total_committers":54,"mean_commits":5.092592592592593,"dds":0.5418181818181818,"last_synced_commit":"cd62300dc0e800a4ad0fb513c362bd33386ff11b"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-fuzz%2Farbitrary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-fuzz%2Farbitrary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-fuzz%2Farbitrary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-fuzz%2Farbitrary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rust-fuzz","download_url":"https://codeload.github.com/rust-fuzz/arbitrary/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253990492,"owners_count":21995776,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T12:00:31.360Z","updated_at":"2025-05-13T17:13:22.576Z","avatar_url":"https://github.com/rust-fuzz.png","language":"Rust","readme":"\u003cdiv align=\"center\"\u003e\n\n  \u003ch1\u003e\u003ccode\u003eArbitrary\u003c/code\u003e\u003c/h1\u003e\n\n  \u003cp\u003e\u003cstrong\u003eThe trait for generating structured data from arbitrary, unstructured input.\u003c/strong\u003e\u003c/p\u003e\n\n  \u003cimg alt=\"GitHub Actions Status\" src=\"https://github.com/rust-fuzz/rust_arbitrary/workflows/Rust/badge.svg\"/\u003e\n\n\u003c/div\u003e\n\n## About\n\nThe `Arbitrary` crate lets you construct arbitrary instances of a type.\n\nThis crate is primarily intended to be combined with a fuzzer like [libFuzzer\nand `cargo-fuzz`](https://github.com/rust-fuzz/cargo-fuzz) or\n[AFL](https://github.com/rust-fuzz/afl.rs), and to help you turn the raw,\nuntyped byte buffers that they produce into well-typed, valid, structured\nvalues. This allows you to combine structure-aware test case generation with\ncoverage-guided, mutation-based fuzzers.\n\n## Documentation\n\n[**Read the API documentation on `docs.rs`!**](https://docs.rs/arbitrary)\n\n## Example\n\nSay you're writing a color conversion library, and you have an `Rgb` struct to\nrepresent RGB colors. You might want to implement `Arbitrary` for `Rgb` so that\nyou could take arbitrary `Rgb` instances in a test function that asserts some\nproperty (for example, asserting that RGB converted to HSL and converted back to\nRGB always ends up exactly where we started).\n\n### Automatically Deriving `Arbitrary`\n\nAutomatically deriving the `Arbitrary` trait is the recommended way to implement\n`Arbitrary` for your types.\n\nAutomatically deriving `Arbitrary` requires you to enable the `\"derive\"` cargo\nfeature:\n\n```toml\n# Cargo.toml\n\n[dependencies]\narbitrary = { version = \"1\", features = [\"derive\"] }\n```\n\nAnd then you can simply add `#[derive(Arbitrary)]` annotations to your types:\n\n```rust\n// rgb.rs\n\nuse arbitrary::Arbitrary;\n\n#[derive(Arbitrary)]\npub struct Rgb {\n    pub r: u8,\n    pub g: u8,\n    pub b: u8,\n}\n```\n\n#### Customizing single fields\n\nThis 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.\n\n```rust\n#[derive(Arbitrary)]\npub struct Rgba {\n    // set `r` to Default::default()\n    #[arbitrary(default)]\n    pub r: u8,\n\n    // set `g` to 255\n    #[arbitrary(value = 255)]\n    pub g: u8,\n\n    // Generate `b` with a custom function of type\n    //\n    //    fn(\u0026mut Unstructured) -\u003e arbitrary::Result\u003cT\u003e\n    //\n    // where `T` is the field's type.\n    #[arbitrary(with = arbitrary_b)]\n    pub b: u8,\n\n    // Generate `a` with a custom closure (shortcut to avoid a custom function)\n    #[arbitrary(with = |u: \u0026mut Unstructured| u.int_in_range(0..=64))]\n    pub a: u8,\n}\n\nfn arbitrary_b(u: \u0026mut Unstructured) -\u003e arbitrary::Result\u003cu8\u003e {\n    u.int_in_range(64..=128)\n}\n```\n\n### Implementing `Arbitrary` By Hand\n\nAlternatively, you can write an `Arbitrary` implementation by hand:\n\n```rust\n// rgb.rs\n\nuse arbitrary::{Arbitrary, Result, Unstructured};\n\n#[derive(Copy, Clone, Debug)]\npub struct Rgb {\n    pub r: u8,\n    pub g: u8,\n    pub b: u8,\n}\n\nimpl\u003c'a\u003e Arbitrary\u003c'a\u003e for Rgb {\n    fn arbitrary(u: \u0026mut Unstructured\u003c'a\u003e) -\u003e Result\u003cSelf\u003e {\n        let r = u8::arbitrary(u)?;\n        let g = u8::arbitrary(u)?;\n        let b = u8::arbitrary(u)?;\n        Ok(Rgb { r, g, b })\n    }\n}\n```\n\n## Minimum Supported Rust Version (MSRV)\n\n\u003c!-- NB: Keep this number in sync with the `rust-version` in `Cargo.toml`. --\u003e\n\nThis crate is guaranteed to compile on stable Rust **1.63.0** and up. It might\ncompile with older versions but that may change in any new patch release.\n\nWe reserve the right to increment the MSRV on minor releases, however we will\nstrive to only do it deliberately and for good reasons.\n\n## License\n\nLicensed under dual MIT or Apache-2.0 at your choice.\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in this project by you, as defined in the Apache-2.0 license,\nshall be dual licensed as above, without any additional terms or conditions.\n","funding_links":[],"categories":["Vulnerability Assessment","Rust"],"sub_categories":["Fuzzing"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frust-fuzz%2Farbitrary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frust-fuzz%2Farbitrary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frust-fuzz%2Farbitrary/lists"}