Merge pull request #162 from quodlibetor/update-serde-docs

Update serde docs
This commit is contained in:
Brandon W Maister 2017-06-21 18:41:20 -05:00 committed by GitHub
commit 6f69ab758b
3 changed files with 51 additions and 37 deletions

View File

@ -634,15 +634,12 @@ mod rustc_serialize {
} }
/// Ser/de helpers /// documented at re-export site
///
/// The various modules in here are intended to be used with serde's [`with`
/// annotation](https://serde.rs/attributes.html#field-attributes).
#[cfg(feature = "serde")] #[cfg(feature = "serde")]
pub mod serde { pub mod serde {
use std::fmt; use std::fmt;
use super::DateTime; use super::DateTime;
use offset::{TimeZone, LocalResult, Utc, Local, FixedOffset}; use offset::{TimeZone, Utc, Local, FixedOffset};
use serdelib::{ser, de}; use serdelib::{ser, de};
/// Ser/de to/from timestamps in seconds /// Ser/de to/from timestamps in seconds
@ -686,8 +683,7 @@ pub mod serde {
use serdelib::{ser, de}; use serdelib::{ser, de};
use {DateTime, Utc, FixedOffset}; use {DateTime, Utc, FixedOffset};
use offset::TimeZone; use offset::{LocalResult, TimeZone};
use super::from;
/// Deserialize a DateTime from a seconds timestamp /// Deserialize a DateTime from a seconds timestamp
/// ///
@ -786,11 +782,28 @@ pub mod serde {
} }
} }
// try!-like function to convert a LocalResult into a serde-ish Result
fn from<T, E, V>(me: LocalResult<T>, ts: V) -> Result<T, E>
where E: de::Error,
V: fmt::Display,
T: fmt::Display,
{
match me {
LocalResult::None => Err(E::custom(
format!("value is not a legal timestamp: {}", ts))),
LocalResult::Ambiguous(min, max) => Err(E::custom(
format!("value is an ambiguous timestamp: {}, could be either of {}, {}",
ts, min, max))),
LocalResult::Single(val) => Ok(val)
}
}
} }
// TODO not very optimized for space (binary formats would want something better)
impl<Tz: TimeZone> ser::Serialize for DateTime<Tz> { impl<Tz: TimeZone> ser::Serialize for DateTime<Tz> {
/// Serialize into a rfc3339 time string
///
/// See [the `serde` module](./serde/index.html) for alternate
/// serializations.
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where S: ser::Serializer where S: ser::Serializer
{ {
@ -809,22 +822,6 @@ pub mod serde {
} }
} }
// try!-like function to convert a LocalResult into a serde-ish Result
fn from<T, E, V>(me: LocalResult<T>, ts: V) -> Result<T, E>
where E: de::Error,
V: fmt::Display,
T: fmt::Display,
{
match me {
LocalResult::None => Err(E::custom(
format!("value is not a legal timestamp: {}", ts))),
LocalResult::Ambiguous(min, max) => Err(E::custom(
format!("value is an ambiguous timestamp: {}, could be either of {}, {}",
ts, min, max))),
LocalResult::Single(val) => Ok(val)
}
}
struct DateTimeVisitor; struct DateTimeVisitor;
impl<'de> de::Visitor<'de> for DateTimeVisitor { impl<'de> de::Visitor<'de> for DateTimeVisitor {
@ -845,8 +842,10 @@ pub mod serde {
/// Deserialize a value that optionally includes a timezone offset in its /// Deserialize a value that optionally includes a timezone offset in its
/// string representation /// string representation
/// ///
/// The serialized value can be either a string representation or a unix /// The value to be deserialized must be an rfc3339 string.
/// timestamp ///
/// See [the `serde` module](./serde/index.html) for alternate
/// deserialization formats.
impl<'de> de::Deserialize<'de> for DateTime<FixedOffset> { impl<'de> de::Deserialize<'de> for DateTime<FixedOffset> {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where D: de::Deserializer<'de> where D: de::Deserializer<'de>
@ -857,8 +856,10 @@ pub mod serde {
/// Deserialize into a UTC value /// Deserialize into a UTC value
/// ///
/// The serialized value can be either a string representation or a unix /// The value to be deserialized must be an rfc3339 string.
/// timestamp ///
/// See [the `serde` module](./serde/index.html) for alternate
/// deserialization formats.
impl<'de> de::Deserialize<'de> for DateTime<Utc> { impl<'de> de::Deserialize<'de> for DateTime<Utc> {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where D: de::Deserializer<'de> where D: de::Deserializer<'de>
@ -870,8 +871,10 @@ pub mod serde {
/// Deserialize a value that includes no timezone in its string /// Deserialize a value that includes no timezone in its string
/// representation /// representation
/// ///
/// The serialized value can be either a string representation or a unix /// The value to be deserialized must be an rfc3339 string.
/// timestamp ///
/// See [the `serde` module](./serde/index.html) for alternate
/// serialization formats.
impl<'de> de::Deserialize<'de> for DateTime<Local> { impl<'de> de::Deserialize<'de> for DateTime<Local> {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where D: de::Deserializer<'de> where D: de::Deserializer<'de>

View File

@ -412,7 +412,14 @@ pub mod naive {
pub use self::time::NaiveTime; pub use self::time::NaiveTime;
pub use self::datetime::{NaiveDateTime, TsSeconds}; pub use self::datetime::{NaiveDateTime, TsSeconds};
/// Tools to help serializing/deserializing naive types. /// Serialization/Deserialization of naive types in alternate formats
///
/// The various modules in here are intended to be used with serde's [`with`
/// annotation][1] to serialize as something other than the default [RFC
/// 3339][2] format.
///
/// [1]: https://serde.rs/attributes.html#field-attributes
/// [2]: https://tools.ietf.org/html/rfc3339
#[cfg(feature = "serde")] #[cfg(feature = "serde")]
pub mod serde { pub mod serde {
pub use super::datetime::serde::*; pub use super::datetime::serde::*;
@ -422,10 +429,14 @@ mod date;
mod datetime; mod datetime;
pub mod format; pub mod format;
/// Ser/de helpers /// Serialization/Deserialization in alternate formats
/// ///
/// The various modules in here are intended to be used with serde's [`with` /// The various modules in here are intended to be used with serde's [`with`
/// annotation](https://serde.rs/attributes.html#field-attributes). /// annotation][1] to serialize as something other than the default [RFC
/// 3339][2] format.
///
/// [1]: https://serde.rs/attributes.html#field-attributes
/// [2]: https://tools.ietf.org/html/rfc3339
#[cfg(feature = "serde")] #[cfg(feature = "serde")]
pub mod serde { pub mod serde {
pub use super::datetime::serde::*; pub use super::datetime::serde::*;

View File

@ -1525,10 +1525,10 @@ pub mod serde {
use super::{NaiveDateTime}; use super::{NaiveDateTime};
use serdelib::{ser, de}; use serdelib::{ser, de};
/// Serialize a NaiveDateTime as a string /// Serialize a NaiveDateTime as an RFC 3339 string
/// ///
/// See the [`ts_seconds`](./serde/ts_seconds/index.html) module to serialize as /// See [the `serde` module](./serde/index.html) for alternate
/// a timestamp. /// serialization formats.
impl ser::Serialize for NaiveDateTime { impl ser::Serialize for NaiveDateTime {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where S: ser::Serializer where S: ser::Serializer