1 #![deny(
2     missing_debug_implementations,
3     missing_copy_implementations,
4     missing_docs,
5     trivial_casts,
6     trivial_numeric_casts,
7     unused_extern_crates,
8     unused_import_braces,
9     unused_qualifications,
10     variant_size_differences
11 )]
12 #![cfg_attr(feature = "cargo-clippy", allow(renamed_and_removed_lints))]
13 #![doc(html_root_url = "https://docs.rs/serde_with/1.4.0")]
14 
15 //! [![docs.rs badge](https://docs.rs/serde_with/badge.svg)](https://docs.rs/serde_with/)
16 //! [![crates.io badge](https://img.shields.io/crates/v/serde_with.svg)](https://crates.io/crates/serde_with/)
17 //! [![Build Status](https://travis-ci.org/jonasbb/serde_with.svg?branch=master)](https://travis-ci.org/jonasbb/serde_with)
18 //! [![codecov](https://codecov.io/gh/jonasbb/serde_with/branch/master/graph/badge.svg)](https://codecov.io/gh/jonasbb/serde_with)
19 //!
20 //! ---
21 //!
22 //! This crate provides custom de/serialization helpers to use in combination with [serde's with-annotation][with-annotation].
23 //!
24 //! Serde tracks a wishlist of similar helpers at [serde#553].
25 //!
26 //! # Usage
27 //!
28 //! Add this to your `Cargo.toml`:
29 //!
30 //! ```toml
31 //! [dependencies.serde_with]
32 //! version = "1.4.0"
33 //! features = [ "..." ]
34 //! ```
35 //!
36 //! The crate is divided into different modules.
37 //! They contain helpers for external crates and must be enabled with the correspondig feature.
38 //!
39 //! Annotate your struct or enum to enable the custom de/serializer.
40 //!
41 //! ```rust
42 //! # extern crate serde;
43 //! # extern crate serde_derive;
44 //! # extern crate serde_with;
45 //! # use serde_derive::{Deserialize, Serialize};
46 //! #[derive(Deserialize, Serialize)]
47 //! struct Foo {
48 //!     #[serde(with = "serde_with::rust::display_fromstr")]
49 //!     bar: u8,
50 //! }
51 //! # fn main() {}
52 //! ```
53 //!
54 //! Most helpers implement both deserialize and serialize.
55 //! If you do not want to derive both, you can simply derive only the necessary parts.
56 //! If you want to mix different helpers, you can write your annotations like
57 //!
58 //! ```rust
59 //! # extern crate serde;
60 //! # extern crate serde_derive;
61 //! # extern crate serde_with;
62 //! # use serde_derive::{Deserialize, Serialize};
63 //! # #[cfg(feature = "json")]
64 //! #[derive(Deserialize, Serialize)]
65 //! struct Foo {
66 //!     #[serde(
67 //!         deserialize_with = "serde_with::rust::display_fromstr::deserialize",
68 //!         serialize_with = "serde_with::json::nested::serialize"
69 //!     )]
70 //!     bar: u8,
71 //! }
72 //! # fn main() {}
73 //! ```
74 //!
75 //! However, this will prohibit you from applying deserialize on the value returned by serializing a struct.
76 //!
77 //! # Attributes
78 //!
79 //! The crate comes with custom attributes, which futher extend how serde serialization can be customized.
80 //! They are enabled by default, but can be disabled, by removing the default features from this crate.
81 //!
82 //! The `serde_with` crate re-exports all items from `serde_with_macros`.
83 //! This means, if you want to use any proc_macros, import them like `use serde_with::skip_serializing_none`.
84 //!
85 //! [The documentation for the custom attributes can be found here.](serde_with_macros)
86 //!
87 //! [with-annotation]: https://serde.rs/field-attrs.html#serdewith--module
88 //! [serde#553]: https://github.com/serde-rs/serde/issues/553
89 
90 #[cfg(feature = "chrono")]
91 extern crate chrono as chrono_crate;
92 #[doc(hidden)]
93 pub extern crate serde;
94 #[cfg(feature = "json")]
95 extern crate serde_json;
96 #[cfg(feature = "macros")]
97 extern crate serde_with_macros;
98 
99 #[cfg(feature = "chrono")]
100 pub mod chrono;
101 mod duplicate_key_impls;
102 mod flatten_maybe;
103 #[cfg(feature = "json")]
104 pub mod json;
105 pub mod rust;
106 #[doc(hidden)]
107 pub mod with_prefix;
108 
109 // Re-Export all proc_macros, as these should be seen as part of the serde_with crate
110 #[cfg(feature = "macros")]
111 #[doc(inline)]
112 pub use serde_with_macros::*;
113 
114 /// Separator for string-based collection de/serialization
115 pub trait Separator {
116     /// Return the string delimiting two elements in the string-based collection
separator() -> &'static str117     fn separator() -> &'static str;
118 }
119 
120 /// Predefined separator using a single space
121 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Default)]
122 pub struct SpaceSeparator;
123 
124 impl Separator for SpaceSeparator {
125     #[inline]
separator() -> &'static str126     fn separator() -> &'static str {
127         " "
128     }
129 }
130 
131 /// Predefined separator using a single comma
132 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Default)]
133 pub struct CommaSeparator;
134 
135 impl Separator for CommaSeparator {
136     #[inline]
separator() -> &'static str137     fn separator() -> &'static str {
138         ","
139     }
140 }
141