diff --git a/src/format/mod.rs b/src/format/mod.rs index ff9162a..271c4be 100644 --- a/src/format/mod.rs +++ b/src/format/mod.rs @@ -2,9 +2,7 @@ // Copyright (c) 2014-2015, Kang Seonghoon. // See README.md and LICENSE.txt for details. -/*! - * Formatting utilities for date and time. - */ +//! Formatting utilities for date and time. use std::fmt; use std::error::Error; @@ -35,7 +33,8 @@ pub enum Pad { /// They have associated formatting width (FW) and parsing width (PW). /// /// The **formatting width** is the minimal width to be formatted. -/// If the number is too short, and the padding is not `Pad::None`, then it is left-padded. +/// If the number is too short, and the padding is not [`Pad::None`](./enum.Pad.html#variant.None), +/// then it is left-padded. /// If the number is too long or (in some cases) negative, it is printed as is. /// /// The **parsing width** is the maximal width to be scanned. @@ -45,14 +44,14 @@ pub enum Pad { /// parsed with the same formatting items. #[derive(Copy, Clone, PartialEq, Eq, Debug)] pub enum Numeric { - /// Full Gregorian year (FW=4, PW=infinity). + /// Full Gregorian year (FW=4, PW=∞). /// May accept years before 1 BCE or after 9999 CE, given an initial sign. Year, /// Gregorian year divided by 100 (century number; FW=PW=2). Implies the non-negative year. YearDiv100, /// Gregorian year modulo 100 (FW=PW=2). Cannot be negative. YearMod100, - /// Year in the ISO week date (FW=4, PW=infinity). + /// Year in the ISO week date (FW=4, PW=∞). /// May accept years before 1 BCE or after 9999 CE, given an initial sign. IsoYear, /// Year in the ISO week date, divided by 100 (FW=PW=2). Implies the non-negative year. @@ -84,9 +83,10 @@ pub enum Numeric { /// The number of seconds since the last whole minute (FW=PW=2). Second, /// The number of nanoseconds since the last whole second (FW=PW=9). - /// Note that this is *not* left-aligned; see also `Fixed::Nanosecond`. + /// Note that this is *not* left-aligned; + /// see also [`Fixed::Nanosecond`](./enum.Fixed.html#variant.Nanosecond). Nanosecond, - /// The number of non-leap seconds since January 1, 1970 0:00:00 UTC (FW=1, PW=infinity). + /// The number of non-leap seconds since the midnight UTC on January 1, 1970 (FW=1, PW=∞). /// For formatting, it assumes UTC upon the absence of time zone offset. Timestamp, } @@ -123,13 +123,13 @@ pub enum Fixed { UpperAmPm, /// An optional dot plus one or more digits for left-aligned nanoseconds. /// May print nothing, 3, 6 or 9 digits according to the available accuracy. - /// See also `Numeric::Nanosecond`. + /// See also [`Numeric::Nanosecond`](./enum.Numeric.html#variant.Nanosecond). Nanosecond, - /// Fixed prescision at Nanosecond3 where 3 is the left aligned accuracy. + /// Same to [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 3. Nanosecond3, - /// Fixed prescision at Nanosecond6 where 6 is the left aligned accuracy. + /// Same to [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 6. Nanosecond6, - /// Fixed prescision at Nanosecond9 where 9 is the left aligned accuracy. + /// Same to [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 9. Nanosecond9, /// Timezone name. /// @@ -138,17 +138,21 @@ pub enum Fixed { /// Offset from the local time to UTC (`+09:00` or `-04:00` or `+00:00`). /// /// In the parser, the colon can be omitted and/or surrounded with any amount of whitespaces. - /// The offset is limited from `-24:00` to `+24:00`, which is same to `FixedOffset`'s range. + /// The offset is limited from `-24:00` to `+24:00`, + /// which is same to [`FixedOffset`](../offset/fixed/struct.FixedOffset.html)'s range. TimezoneOffsetColon, /// Offset from the local time to UTC (`+09:00` or `-04:00` or `Z`). /// /// In the parser, the colon can be omitted and/or surrounded with any amount of whitespaces, /// and `Z` can be either in upper case or in lower case. - /// The offset is limited from `-24:00` to `+24:00`, which is same to `FixedOffset`'s range. + /// The offset is limited from `-24:00` to `+24:00`, + /// which is same to [`FixedOffset`](../offset/fixed/struct.FixedOffset.html)'s range. TimezoneOffsetColonZ, - /// Same to `TimezoneOffsetColon` but prints no colon. Parsing allows an optional colon. + /// Same to [`TimezoneOffsetColon`](#variant.TimezoneOffsetColon) but prints no colon. + /// Parsing allows an optional colon. TimezoneOffset, - /// Same to `TimezoneOffsetColonZ` but prints no colon. Parsing allows an optional colon. + /// Same to [`TimezoneOffsetColonZ`](#variant.TimezoneOffsetColonZ) but prints no colon. + /// Parsing allows an optional colon. TimezoneOffsetZ, /// RFC 2822 date and time syntax. Commonly used for email and MIME date and time. RFC2822, diff --git a/src/format/parse.rs b/src/format/parse.rs index 13c44ab..59c38cf 100644 --- a/src/format/parse.rs +++ b/src/format/parse.rs @@ -3,9 +3,7 @@ // Portions copyright (c) 2015, John Nagle. // See README.md and LICENSE.txt for details. -/*! - * Date and time parsing routines. - */ +//! Date and time parsing routines. use std::usize; @@ -193,15 +191,19 @@ fn parse_rfc3339<'a>(parsed: &mut Parsed, mut s: &'a str) -> ParseResult<(&'a st /// Tries to parse given string into `parsed` with given formatting items. /// Returns `Ok` when the entire string has been parsed (otherwise `parsed` should not be used). -/// There should be no trailing string after parsing; use a stray `Item::Space` to trim whitespaces. +/// There should be no trailing string after parsing; +/// use a stray [`Item::Space`](./enum.Item.html#variant.Space) to trim whitespaces. /// /// This particular date and time parser is: /// /// - Greedy. It will consume the longest possible prefix. /// For example, `April` is always consumed entirely when the long month name is requested; /// it equally accepts `Apr`, but prefers the longer prefix in this case. -/// - Padding-agnostic (for numeric items). The `Pad` field is completely ignored, +/// +/// - Padding-agnostic (for numeric items). +/// The [`Pad`](./enum.Pad.html) field is completely ignored, /// so one can prepend any number of whitespace then any number of zeroes before numbers. +/// /// - (Still) obeying the intrinsic parsing width. This allows, for example, parsing `HHMMSS`. pub fn parse<'a, I>(parsed: &mut Parsed, mut s: &str, items: I) -> ParseResult<()> where I: Iterator> { diff --git a/src/lib.rs b/src/lib.rs index 1af9005..0ebf4f6 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -372,9 +372,10 @@ pub mod date; pub mod datetime; pub mod format; -/// The day of week (DOW). +/// The day of week. /// /// The order of the days of week depends on the context. +/// (This is why this type does *not* implement `PartialOrd` or `Ord` traits.) /// One should prefer `*_from_monday` or `*_from_sunday` methods to get the correct result. #[derive(PartialEq, Eq, Copy, Clone, Debug)] #[cfg_attr(feature = "rustc-serialize", derive(RustcEncodable, RustcDecodable))] @@ -397,6 +398,10 @@ pub enum Weekday { impl Weekday { /// The next day in the week. + /// + /// `w`: | `Mon` | `Tue` | `Wed` | `Thu` | `Fri` | `Sat` | `Sun` + /// ----------- | ----- | ----- | ----- | ----- | ----- | ----- | ----- + /// `w.succ()`: | `Tue` | `Wed` | `Thu` | `Fri` | `Sat` | `Sun` | `Mon` #[inline] pub fn succ(&self) -> Weekday { match *self { @@ -411,6 +416,10 @@ impl Weekday { } /// The previous day in the week. + /// + /// `w`: | `Mon` | `Tue` | `Wed` | `Thu` | `Fri` | `Sat` | `Sun` + /// ----------- | ----- | ----- | ----- | ----- | ----- | ----- | ----- + /// `w.pred()`: | `Sun` | `Mon` | `Tue` | `Wed` | `Thu` | `Fri` | `Sat` #[inline] pub fn pred(&self) -> Weekday { match *self { @@ -424,7 +433,11 @@ impl Weekday { } } - /// Returns a DOW number starting from Monday = 1. (ISO 8601 weekday number) + /// Returns a day-of-week number starting from Monday = 1. (ISO 8601 weekday number) + /// + /// `w`: | `Mon` | `Tue` | `Wed` | `Thu` | `Fri` | `Sat` | `Sun` + /// ------------------------- | ----- | ----- | ----- | ----- | ----- | ----- | ----- + /// `w.number_from_monday()`: | 1 | 2 | 3 | 4 | 5 | 6 | 7 #[inline] pub fn number_from_monday(&self) -> u32 { match *self { @@ -438,7 +451,11 @@ impl Weekday { } } - /// Returns a DOW number starting from Sunday = 1. + /// Returns a day-of-week number starting from Sunday = 1. + /// + /// `w`: | `Mon` | `Tue` | `Wed` | `Thu` | `Fri` | `Sat` | `Sun` + /// ------------------------- | ----- | ----- | ----- | ----- | ----- | ----- | ----- + /// `w.number_from_sunday()`: | 2 | 3 | 4 | 5 | 6 | 7 | 1 #[inline] pub fn number_from_sunday(&self) -> u32 { match *self { @@ -452,7 +469,11 @@ impl Weekday { } } - /// Returns a DOW number starting from Monday = 0. + /// Returns a day-of-week number starting from Monday = 0. + /// + /// `w`: | `Mon` | `Tue` | `Wed` | `Thu` | `Fri` | `Sat` | `Sun` + /// --------------------------- | ----- | ----- | ----- | ----- | ----- | ----- | ----- + /// `w.num_days_from_monday()`: | 0 | 1 | 2 | 3 | 4 | 5 | 6 #[inline] pub fn num_days_from_monday(&self) -> u32 { match *self { @@ -466,7 +487,11 @@ impl Weekday { } } - /// Returns a DOW number starting from Sunday = 0. + /// Returns a day-of-week number starting from Sunday = 0. + /// + /// `w`: | `Mon` | `Tue` | `Wed` | `Thu` | `Fri` | `Sat` | `Sun` + /// --------------------------- | ----- | ----- | ----- | ----- | ----- | ----- | ----- + /// `w.num_days_from_sunday()`: | 1 | 2 | 3 | 4 | 5 | 6 | 0 #[inline] pub fn num_days_from_sunday(&self) -> u32 { match *self { @@ -481,8 +506,8 @@ impl Weekday { } } -/// Any weekday can be represented as an integer from 0 to 6, -/// which equals to `Weekday::num_days_from_monday` in this implementation. +/// Any weekday can be represented as an integer from 0 to 6, which equals to +/// [`Weekday::num_days_from_monday`](#method.num_days_from_monday) in this implementation. /// Do not heavily depend on this though; use explicit methods whenever possible. impl num::traits::FromPrimitive for Weekday { #[inline]