xeos
/
chrono
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

More cross-references.

This commit is contained in:
Kang Seonghoon 2016-08-02 20:52:45 +09:00
parent 4475ee5a48
commit 00858c6363
3 changed files with 59 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
src/format/mod.rs
View File

@ -2,9 +2,7 @@
// Copyright (c) 2014-2015, Kang Seonghoon. // Copyright (c) 2014-2015, Kang Seonghoon.
// See README.md and LICENSE.txt for details. // 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::fmt;
use std::error::Error; use std::error::Error;
@ -35,7 +33,8 @@ pub enum Pad {
/// They have associated formatting width (FW) and parsing width (PW). /// They have associated formatting width (FW) and parsing width (PW).
/// ///
/// The **formatting width** is the minimal width to be formatted. /// 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. /// 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. /// The **parsing width** is the maximal width to be scanned.
@ -45,14 +44,14 @@ pub enum Pad {
/// parsed with the same formatting items. /// parsed with the same formatting items.
#[derive(Copy, Clone, PartialEq, Eq, Debug)] #[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub enum Numeric { 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. /// May accept years before 1 BCE or after 9999 CE, given an initial sign.
Year, Year,
/// Gregorian year divided by 100 (century number; FW=PW=2). Implies the non-negative year. /// Gregorian year divided by 100 (century number; FW=PW=2). Implies the non-negative year.
YearDiv100, YearDiv100,
/// Gregorian year modulo 100 (FW=PW=2). Cannot be negative. /// Gregorian year modulo 100 (FW=PW=2). Cannot be negative.
YearMod100, 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. /// May accept years before 1 BCE or after 9999 CE, given an initial sign.
IsoYear, IsoYear,
/// Year in the ISO week date, divided by 100 (FW=PW=2). Implies the non-negative year. /// 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). /// The number of seconds since the last whole minute (FW=PW=2).
Second, Second,
/// The number of nanoseconds since the last whole second (FW=PW=9). /// 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, 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. /// For formatting, it assumes UTC upon the absence of time zone offset.
Timestamp, Timestamp,
} }
@ -123,13 +123,13 @@ pub enum Fixed {
UpperAmPm, UpperAmPm,
/// An optional dot plus one or more digits for left-aligned nanoseconds. /// 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. /// 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, 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, 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, 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, Nanosecond9,
/// Timezone name. /// Timezone name.
/// ///
@ -138,17 +138,21 @@ pub enum Fixed {
/// Offset from the local time to UTC (`+09:00` or `-04:00` or `+00:00`). /// 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. /// 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, TimezoneOffsetColon,
/// Offset from the local time to UTC (`+09:00` or `-04:00` or `Z`). /// 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, /// 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. /// 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, 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, 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, TimezoneOffsetZ,
/// RFC 2822 date and time syntax. Commonly used for email and MIME date and time. /// RFC 2822 date and time syntax. Commonly used for email and MIME date and time.
RFC2822, RFC2822,

12
src/format/parse.rs
View File

@ -3,9 +3,7 @@
// Portions copyright (c) 2015, John Nagle. // Portions copyright (c) 2015, John Nagle.
// See README.md and LICENSE.txt for details. // See README.md and LICENSE.txt for details.
/*! //! Date and time parsing routines.
* Date and time parsing routines.
*/
use std::usize; 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. /// 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). /// 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: /// This particular date and time parser is:
/// ///
/// - Greedy. It will consume the longest possible prefix. /// - Greedy. It will consume the longest possible prefix.
/// For example, `April` is always consumed entirely when the long month name is requested; /// 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. /// 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. /// 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`. /// - (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<()> pub fn parse<'a, I>(parsed: &mut Parsed, mut s: &str, items: I) -> ParseResult<()>
where I: Iterator<Item=Item<'a>> { where I: Iterator<Item=Item<'a>> {

39
src/lib.rs
View File

@ -372,9 +372,10 @@ pub mod date;
pub mod datetime; pub mod datetime;
pub mod format; pub mod format;
/// The day of week (DOW). /// The day of week.
/// ///
/// The order of the days of week depends on the context. /// 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. /// One should prefer `*_from_monday` or `*_from_sunday` methods to get the correct result.
#[derive(PartialEq, Eq, Copy, Clone, Debug)] #[derive(PartialEq, Eq, Copy, Clone, Debug)]
#[cfg_attr(feature = "rustc-serialize", derive(RustcEncodable, RustcDecodable))] #[cfg_attr(feature = "rustc-serialize", derive(RustcEncodable, RustcDecodable))]
@ -397,6 +398,10 @@ pub enum Weekday {
impl Weekday { impl Weekday {
/// The next day in the week. /// The next day in the week.
///
/// `w`: | `Mon` | `Tue` | `Wed` | `Thu` | `Fri` | `Sat` | `Sun`
/// ----------- | ----- | ----- | ----- | ----- | ----- | ----- | -----
/// `w.succ()`: | `Tue` | `Wed` | `Thu` | `Fri` | `Sat` | `Sun` | `Mon`
#[inline] #[inline]
pub fn succ(&self) -> Weekday { pub fn succ(&self) -> Weekday {
match *self { match *self {
@ -411,6 +416,10 @@ impl Weekday {
} }
/// The previous day in the week. /// The previous day in the week.
///
/// `w`: | `Mon` | `Tue` | `Wed` | `Thu` | `Fri` | `Sat` | `Sun`
/// ----------- | ----- | ----- | ----- | ----- | ----- | ----- | -----
/// `w.pred()`: | `Sun` | `Mon` | `Tue` | `Wed` | `Thu` | `Fri` | `Sat`
#[inline] #[inline]
pub fn pred(&self) -> Weekday { pub fn pred(&self) -> Weekday {
match *self { 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] #[inline]
pub fn number_from_monday(&self) -> u32 { pub fn number_from_monday(&self) -> u32 {
match *self { 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] #[inline]
pub fn number_from_sunday(&self) -> u32 { pub fn number_from_sunday(&self) -> u32 {
match *self { 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] #[inline]
pub fn num_days_from_monday(&self) -> u32 { pub fn num_days_from_monday(&self) -> u32 {
match *self { 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] #[inline]
pub fn num_days_from_sunday(&self) -> u32 { pub fn num_days_from_sunday(&self) -> u32 {
match *self { match *self {
@ -481,8 +506,8 @@ impl Weekday {
} }
} }
/// Any weekday can be represented as an integer from 0 to 6, /// Any weekday can be represented as an integer from 0 to 6, which equals to
/// which equals to `Weekday::num_days_from_monday` in this implementation. /// [`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. /// Do not heavily depend on this though; use explicit methods whenever possible.
impl num::traits::FromPrimitive for Weekday { impl num::traits::FromPrimitive for Weekday {
#[inline] #[inline]