1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

#![deny(
    missing_debug_implementations,
    missing_copy_implementations,
    missing_docs,
    trivial_casts,
    trivial_numeric_casts,
    unused_extern_crates,
    unused_import_braces,
    unused_qualifications,
    variant_size_differences
)]
#![cfg_attr(feature = "cargo-clippy", allow(renamed_and_removed_lints))]
#![doc(html_root_url = "https://docs.rs/serde_with/1.4.0")]

//! [![docs.rs badge](https://docs.rs/serde_with/badge.svg)](https://docs.rs/serde_with/)
//! [![crates.io badge](https://img.shields.io/crates/v/serde_with.svg)](https://crates.io/crates/serde_with/)
//! [![Build Status](https://travis-ci.org/jonasbb/serde_with.svg?branch=master)](https://travis-ci.org/jonasbb/serde_with)
//! [![codecov](https://codecov.io/gh/jonasbb/serde_with/branch/master/graph/badge.svg)](https://codecov.io/gh/jonasbb/serde_with)
//!
//! ---
//!
//! This crate provides custom de/serialization helpers to use in combination with [serde's with-annotation][with-annotation].
//!
//! Serde tracks a wishlist of similar helpers at [serde#553].
//!
//! # Usage
//!
//! Add this to your `Cargo.toml`:
//!
//! ```toml
//! [dependencies.serde_with]
//! version = "1.4.0"
//! features = [ "..." ]
//! ```
//!
//! The crate is divided into different modules.
//! They contain helpers for external crates and must be enabled with the correspondig feature.
//!
//! Annotate your struct or enum to enable the custom de/serializer.
//!
//! ```rust
//! # extern crate serde;
//! # extern crate serde_derive;
//! # extern crate serde_with;
//! # use serde_derive::{Deserialize, Serialize};
//! #[derive(Deserialize, Serialize)]
//! struct Foo {
//!     #[serde(with = "serde_with::rust::display_fromstr")]
//!     bar: u8,
//! }
//! # fn main() {}
//! ```
//!
//! Most helpers implement both deserialize and serialize.
//! If you do not want to derive both, you can simply derive only the necessary parts.
//! If you want to mix different helpers, you can write your annotations like
//!
//! ```rust
//! # extern crate serde;
//! # extern crate serde_derive;
//! # extern crate serde_with;
//! # use serde_derive::{Deserialize, Serialize};
//! # #[cfg(feature = "json")]
//! #[derive(Deserialize, Serialize)]
//! struct Foo {
//!     #[serde(
//!         deserialize_with = "serde_with::rust::display_fromstr::deserialize",
//!         serialize_with = "serde_with::json::nested::serialize"
//!     )]
//!     bar: u8,
//! }
//! # fn main() {}
//! ```
//!
//! However, this will prohibit you from applying deserialize on the value returned by serializing a struct.
//!
//! # Attributes
//!
//! The crate comes with custom attributes, which futher extend how serde serialization can be customized.
//! They are enabled by default, but can be disabled, by removing the default features from this crate.
//!
//! The `serde_with` crate re-exports all items from `serde_with_macros`.
//! This means, if you want to use any proc_macros, import them like `use serde_with::skip_serializing_none`.
//!
//! [The documentation for the custom attributes can be found here.](serde_with_macros)
//!
//! [with-annotation]: https://serde.rs/field-attrs.html#serdewith--module
//! [serde#553]: https://github.com/serde-rs/serde/issues/553

#[cfg(feature = "chrono")]
extern crate chrono as chrono_crate;
#[doc(hidden)]
pub extern crate serde;
#[cfg(feature = "json")]
extern crate serde_json;
#[cfg(feature = "macros")]
extern crate serde_with_macros;

#[cfg(feature = "chrono")]
pub mod chrono;
mod duplicate_key_impls;
mod flatten_maybe;
#[cfg(feature = "json")]
pub mod json;
pub mod rust;
#[doc(hidden)]
pub mod with_prefix;

// Re-Export all proc_macros, as these should be seen as part of the serde_with crate
#[cfg(feature = "macros")]
#[doc(inline)]
pub use serde_with_macros::*;

/// Separator for string-based collection de/serialization
pub trait Separator {
    /// Return the string delimiting two elements in the string-based collection
    fn separator() -> &'static str;
}

/// Predefined separator using a single space
#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Default)]
pub struct SpaceSeparator;

impl Separator for SpaceSeparator {
    #[inline]
    fn separator() -> &'static str {
        " "
    }
}

/// Predefined separator using a single comma
#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Default)]
pub struct CommaSeparator;

impl Separator for CommaSeparator {
    #[inline]
    fn separator() -> &'static str {
        ","
    }
}