{"id":13502962,"url":"https://github.com/jonasbb/serde_with","last_synced_at":"2025-05-13T17:11:06.246Z","repository":{"id":28676054,"uuid":"100649664","full_name":"jonasbb/serde_with","owner":"jonasbb","description":"This crate provides custom de/serialization helpers to use in combination with serde's `with`-annotation and with the improved `serde_as`-annotation.","archived":false,"fork":false,"pushed_at":"2025-05-10T01:42:16.000Z","size":2364,"stargazers_count":738,"open_issues_count":23,"forks_count":77,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-12T03:10:44.994Z","etag":null,"topics":["annotations","base64","chrono","crates","hacktoberfest","hex","json","macros","rust","serde"],"latest_commit_sha":null,"homepage":"https://docs.rs/serde_with","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/jonasbb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"jonasbb","thanks_dev":"u/gh/jonasbb"}},"created_at":"2017-08-17T22:20:21.000Z","updated_at":"2025-05-11T05:52:32.000Z","dependencies_parsed_at":"2023-10-15T14:30:03.689Z","dependency_job_id":"4426fbb6-e243-4182-8ebb-5120721a4e7c","html_url":"https://github.com/jonasbb/serde_with","commit_stats":{"total_commits":993,"total_committers":47,"mean_commits":"21.127659574468087","dds":"0.20140986908358505","last_synced_commit":"9f8f6077b5fdde197fd4640cb7dbb231899f56fd"},"previous_names":[],"tags_count":80,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonasbb%2Fserde_with","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonasbb%2Fserde_with/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonasbb%2Fserde_with/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonasbb%2Fserde_with/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonasbb","download_url":"https://codeload.github.com/jonasbb/serde_with/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253666147,"owners_count":21944624,"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":["annotations","base64","chrono","crates","hacktoberfest","hex","json","macros","rust","serde"],"created_at":"2024-07-31T22:02:31.887Z","updated_at":"2025-05-13T17:11:01.184Z","avatar_url":"https://github.com/jonasbb.png","language":"Rust","readme":"# Custom de/serialization functions for Rust's [serde](https://serde.rs)\n\n[![crates.io badge](https://img.shields.io/crates/v/serde_with.svg)](https://crates.io/crates/serde_with/)\n[![Build Status](https://github.com/jonasbb/serde_with/actions/workflows/ci.yaml/badge.svg)](https://github.com/jonasbb/serde_with)\n[![codecov](https://codecov.io/gh/jonasbb/serde_with/branch/master/graph/badge.svg)](https://codecov.io/gh/jonasbb/serde_with)\n[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4322/badge)](https://bestpractices.coreinfrastructure.org/projects/4322)\n[![Rustexplorer](https://img.shields.io/badge/Try%20on-rustexplorer-lightgrey?logo=rust\u0026logoColor=orange)](https://www.rustexplorer.com/b/py7ida)\n\n---\n\nThis crate provides custom de/serialization helpers to use in combination with [serde's `with` annotation][with-annotation] and with the improved [`serde_as`][as-annotation]-annotation.\nSome common use cases are:\n\n* De/Serializing a type using the `Display` and `FromStr` traits, e.g., for `u8`, `url::Url`, or `mime::Mime`.\n     Check [`DisplayFromStr`] for details.\n* Support for arrays larger than 32 elements or using const generics.\n    With `serde_as` large arrays are supported, even if they are nested in other types.\n    `[bool; 64]`, `Option\u003c[u8; M]\u003e`, and `Box\u003c[[u8; 64]; N]\u003e` are all supported, as [this examples shows](#large-and-const-generic-arrays).\n* Skip serializing all empty `Option` types with [`#[skip_serializing_none]`][skip_serializing_none].\n* Apply a prefix / suffix to each field name of a struct, without changing the de/serialize implementations of the struct using [`with_prefix!`][] / [`with_suffix!`][].\n* Deserialize a comma separated list like `#hash,#tags,#are,#great` into a `Vec\u003cString\u003e`.\n     Check the documentation for [`serde_with::StringWithSeparator::\u003cCommaSeparator, T\u003e`][StringWithSeparator].\n\n### Getting Help\n\n**Check out the [user guide][user guide] to find out more tips and tricks about this crate.**\n\nFor further help using this crate, you can [open a new discussion](https://github.com/jonasbb/serde_with/discussions/new) or ask on [users.rust-lang.org](https://users.rust-lang.org/).\nFor bugs, please open a [new issue](https://github.com/jonasbb/serde_with/issues/new) on GitHub.\n\n## Use `serde_with` in your Project\n\n```bash\n# Add the current version to your Cargo.toml\ncargo add serde_with\n```\n\nThe crate contains different features for integration with other common crates.\nCheck the [feature flags][] section for information about all available features.\n\n## Examples\n\nAnnotate your struct or enum to enable the custom de/serializer.\nThe `#[serde_as]` attribute must be placed *before* the `#[derive]`.\n\nThe `as` is analogous to the `with` attribute of serde.\nYou mirror the type structure of the field you want to de/serialize.\nYou can specify converters for the inner types of a field, e.g., `Vec\u003cDisplayFromStr\u003e`.\nThe default de/serialization behavior can be restored by using `_` as a placeholder, e.g., `BTreeMap\u003c_, DisplayFromStr\u003e`.\n\n### `DisplayFromStr`\n\n[![Rustexplorer](https://img.shields.io/badge/Try%20on-rustexplorer-lightgrey?logo=rust\u0026logoColor=orange)](https://www.rustexplorer.com/b/py7ida)\n```rust\n#[serde_as]\n#[derive(Deserialize, Serialize)]\nstruct Foo {\n    // Serialize with Display, deserialize with FromStr\n    #[serde_as(as = \"DisplayFromStr\")]\n    bar: u8,\n}\n\n// This will serialize\nFoo {bar: 12}\n\n// into this JSON\n{\"bar\": \"12\"}\n```\n\n### Large and const-generic arrays\n\nserde does not support arrays with more than 32 elements or using const-generics.\nThe `serde_as` attribute allows circumventing this restriction, even for nested types and nested arrays.\n\nOn top of it, `[u8; N]` (aka, bytes) can use the specialized `\"Bytes\"` for efficiency much like the `serde_bytes` crate.\n\n[![Rustexplorer](https://img.shields.io/badge/Try%20on-rustexplorer-lightgrey?logo=rust\u0026logoColor=orange)](https://www.rustexplorer.com/b/um0xyi)\n```rust\n#[serde_as]\n#[derive(Deserialize, Serialize)]\nstruct Arrays\u003cconst N: usize, const M: usize\u003e {\n    #[serde_as(as = \"[_; N]\")]\n    constgeneric: [bool; N],\n\n    #[serde_as(as = \"Box\u003c[[_; 64]; N]\u003e\")]\n    nested: Box\u003c[[u8; 64]; N]\u003e,\n\n    #[serde_as(as = \"Option\u003c[_; M]\u003e\")]\n    optional: Option\u003c[u8; M]\u003e,\n\n    #[serde_as(as = \"Bytes\")]\n    bytes: [u8; M],\n}\n\n// This allows us to serialize a struct like this\nlet arrays: Arrays\u003c100, 128\u003e = Arrays {\n    constgeneric: [true; 100],\n    nested: Box::new([[111; 64]; 100]),\n    optional: Some([222; 128]),\n    bytes: [0x42; 128],\n};\nassert!(serde_json::to_string(\u0026arrays).is_ok());\n```\n\n### `skip_serializing_none`\n\nThis situation often occurs with JSON, but other formats also support optional fields.\nIf many fields are optional, putting the annotations on the structs can become tedious.\nThe `#[skip_serializing_none]` attribute must be placed *before* the `#[derive]`.\n\n[![Rustexplorer](https://img.shields.io/badge/Try%20on-rustexplorer-lightgrey?logo=rust\u0026logoColor=orange)](https://www.rustexplorer.com/b/xr1tm0)\n```rust\n#[skip_serializing_none]\n#[derive(Deserialize, Serialize)]\nstruct Foo {\n    a: Option\u003cusize\u003e,\n    b: Option\u003cusize\u003e,\n    c: Option\u003cusize\u003e,\n    d: Option\u003cusize\u003e,\n    e: Option\u003cusize\u003e,\n    f: Option\u003cusize\u003e,\n    g: Option\u003cusize\u003e,\n}\n\n// This will serialize\nFoo {a: None, b: None, c: None, d: Some(4), e: None, f: None, g: Some(7)}\n\n// into this JSON\n{\"d\": 4, \"g\": 7}\n```\n\n### Advanced `serde_as` usage\n\nThis example is mainly supposed to highlight the flexibility of the `serde_as` annotation compared to [serde's `with` annotation][with-annotation].\nMore details about `serde_as` can be found in the [user guide].\n\n```rust\nuse std::time::Duration;\n\n#[serde_as]\n#[derive(Deserialize, Serialize)]\nenum Foo {\n    Durations(\n        // Serialize them into a list of number as seconds\n        #[serde_as(as = \"Vec\u003cDurationSeconds\u003e\")]\n        Vec\u003cDuration\u003e,\n    ),\n    Bytes {\n        // We can treat a Vec like a map with duplicates.\n        // JSON only allows string keys, so convert i32 to strings\n        // The bytes will be hex encoded\n        #[serde_as(as = \"Map\u003cDisplayFromStr, Hex\u003e\")]\n        bytes: Vec\u003c(i32, Vec\u003cu8\u003e)\u003e,\n    }\n}\n\n// This will serialize\nFoo::Durations(\n    vec![Duration::new(5, 0), Duration::new(3600, 0), Duration::new(0, 0)]\n)\n// into this JSON\n{\n    \"Durations\": [5, 3600, 0]\n}\n\n// and serializes\nFoo::Bytes {\n    bytes: vec![\n        (1, vec![0, 1, 2]),\n        (-100, vec![100, 200, 255]),\n        (1, vec![0, 111, 222]),\n    ],\n}\n// into this JSON\n{\n    \"Bytes\": {\n        \"bytes\": {\n            \"1\": \"000102\",\n            \"-100\": \"64c8ff\",\n            \"1\": \"006fde\"\n        }\n    }\n}\n```\n\n[`DisplayFromStr`]: https://docs.rs/serde_with/3.12.0/serde_with/struct.DisplayFromStr.html\n[`with_prefix!`]: https://docs.rs/serde_with/3.12.0/serde_with/macro.with_prefix.html\n[`with_suffix!`]: https://docs.rs/serde_with/3.12.0/serde_with/macro.with_suffix.html\n[feature flags]: https://docs.rs/serde_with/3.12.0/serde_with/guide/feature_flags/index.html\n[skip_serializing_none]: https://docs.rs/serde_with/3.12.0/serde_with/attr.skip_serializing_none.html\n[StringWithSeparator]: https://docs.rs/serde_with/3.12.0/serde_with/struct.StringWithSeparator.html\n[user guide]: https://docs.rs/serde_with/3.12.0/serde_with/guide/index.html\n[with-annotation]: https://serde.rs/field-attrs.html#with\n[as-annotation]: https://docs.rs/serde_with/3.12.0/serde_with/guide/serde_as/index.html\n\n## License\n\nLicensed under either of\n\n* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n## Contribution\n\nFor detailed contribution instructions please read [`CONTRIBUTING.md`].\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall\nbe dual-licensed as above, without any additional terms or conditions.\n\n[`CONTRIBUTING.md`]: https://github.com/jonasbb/serde_with/blob/master/CONTRIBUTING.md\n","funding_links":["https://github.com/sponsors/jonasbb","https://thanks.dev/u/gh/jonasbb"],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonasbb%2Fserde_with","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonasbb%2Fserde_with","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonasbb%2Fserde_with/lists"}