diff --git a/src/format/parsed.rs b/src/format/parsed.rs index 222cd3f..8b0aab2 100644 --- a/src/format/parsed.rs +++ b/src/format/parsed.rs @@ -2,10 +2,8 @@ // Copyright (c) 2015, Kang Seonghoon. // See README.md and LICENSE.txt for details. -/*! - * A collection of parsed date and time items. - * They can be constructed incrementally while being checked for consistency. - */ +//! A collection of parsed date and time items. +//! They can be constructed incrementally while being checked for consistency. use num::traits::ToPrimitive; @@ -25,59 +23,90 @@ use super::{ParseResult, OUT_OF_RANGE, IMPOSSIBLE, NOT_ENOUGH}; /// /// - `set_*` methods try to set given field(s) while checking for the consistency. /// It may or may not check for the range constraint immediately (for efficiency reasons). +/// /// - `to_*` methods try to make a concrete date and time value out of set fields. -/// It fully checks any remaining out-of-range conditions and inconsistent/impossible fields, +/// It fully checks any remaining out-of-range conditions and inconsistent/impossible fields. #[allow(missing_copy_implementations)] #[derive(Clone, PartialEq, Debug)] pub struct Parsed { - /// Year. This can be negative unlike `year_{div,mod}_100` fields. + /// Year. + /// + /// This can be negative unlike [`year_div_100`](#structfield.year_div_100) + /// and [`year_mod_100`](#structfield.year_mod_100) fields. pub year: Option, + /// Year divided by 100. Implies that the year is >= 1 BCE when set. /// - /// Due to the common usage, if this field is missing but `year_mod_100` is present, + /// Due to the common usage, if this field is missing but + /// [`year_mod_100`](#structfield.year_mod_100) is present, /// it is inferred to 19 when `year_mod_100 >= 70` and 20 otherwise. pub year_div_100: Option, + /// Year modulo 100. Implies that the year is >= 1 BCE when set. pub year_mod_100: Option, - /// Year in the ISO week date. This can be negative unlike `isoyear_{div,mod}_100` fields. - pub isoyear: Option, - /// Year in the ISO week date, divided by 100. Implies that the year is >= 1 BCE when set. + + /// Year in the [ISO week date](../../naive/date/index.html#week-date). /// - /// Due to the common usage, if this field is missing but `isoyear_mod_100` is present, + /// This can be negative unlike [`isoyear_div_100`](#structfield.isoyear_div_100) and + /// [`isoyear_mod_100`](#structfield.isoyear_mod_100) fields. + pub isoyear: Option, + + /// Year in the [ISO week date](../../naive/date/index.html#week-date), divided by 100. + /// Implies that the year is >= 1 BCE when set. + /// + /// Due to the common usage, if this field is missing but + /// [`isoyear_mod_100`](#structfield.isoyear_mod_100) is present, /// it is inferred to 19 when `isoyear_mod_100 >= 70` and 20 otherwise. pub isoyear_div_100: Option, - /// Year in the ISO week date, modulo 100. Implies that the year is >= 1 BCE when set. + + /// Year in the [ISO week date](../../naive/date/index.html#week-date), modulo 100. + /// Implies that the year is >= 1 BCE when set. pub isoyear_mod_100: Option, + /// Month (1--12). pub month: Option, - /// Week number, where the week 1 starts at the first Sunday of January. + + /// Week number, where the week 1 starts at the first Sunday of January /// (0--53, 1--53 or 1--52 depending on the year). pub week_from_sun: Option, - /// Week number, where the week 1 starts at the first Monday of January. + + /// Week number, where the week 1 starts at the first Monday of January /// (0--53, 1--53 or 1--52 depending on the year). pub week_from_mon: Option, - /// ISO week number (1--52 or 1--53 depending on the year). + + /// [ISO week number](../../naive/date/index.html#week-date) + /// (1--52 or 1--53 depending on the year). pub isoweek: Option, + /// Day of the week. pub weekday: Option, + /// Day of the year (1--365 or 1--366 depending on the year). pub ordinal: Option, + /// Day of the month (1--28, 1--29, 1--30 or 1--31 depending on the month). pub day: Option, + /// Hour number divided by 12 (0--1). 0 indicates AM and 1 indicates PM. pub hour_div_12: Option, + /// Hour number modulo 12 (0--11). pub hour_mod_12: Option, + /// Minute number (0--59). pub minute: Option, + /// Second number (0--60, accounting for leap seconds). pub second: Option, + /// The number of nanoseconds since the whole second (0--999,999,999). pub nanosecond: Option, - /// The number of non-leap seconds since January 1, 1970 0:00:00 UTC. + + /// The number of non-leap seconds since the midnight UTC on January 1, 1970. /// - /// This can be off by one if `second` is 60 (a leap second). + /// This can be off by one if [`second`](#structfield.second) is 60 (a leap second). pub timestamp: Option, + /// Offset from the local time to UTC, in seconds. pub offset: Option, } @@ -103,87 +132,90 @@ impl Parsed { second: None, nanosecond: None, timestamp: None, offset: None } } - /// Tries to set the `year` field from given value. + /// Tries to set the [`year`](#structfield.year) field from given value. pub fn set_year(&mut self, value: i64) -> ParseResult<()> { set_if_consistent(&mut self.year, try!(value.to_i32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `year_div_100` field from given value. + /// Tries to set the [`year_div_100`](#structfield.year_div_100) field from given value. pub fn set_year_div_100(&mut self, value: i64) -> ParseResult<()> { if value < 0 { return Err(OUT_OF_RANGE); } set_if_consistent(&mut self.year_div_100, try!(value.to_i32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `year_mod_100` field from given value. + /// Tries to set the [`year_mod_100`](#structfield.year_mod_100) field from given value. pub fn set_year_mod_100(&mut self, value: i64) -> ParseResult<()> { if value < 0 { return Err(OUT_OF_RANGE); } set_if_consistent(&mut self.year_mod_100, try!(value.to_i32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `isoyear` field from given value. + /// Tries to set the [`isoyear`](#structfield.isoyear) field from given value. pub fn set_isoyear(&mut self, value: i64) -> ParseResult<()> { set_if_consistent(&mut self.isoyear, try!(value.to_i32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `isoyear_div_100` field from given value. + /// Tries to set the [`isoyear_div_100`](#structfield.isoyear_div_100) field from given value. pub fn set_isoyear_div_100(&mut self, value: i64) -> ParseResult<()> { if value < 0 { return Err(OUT_OF_RANGE); } set_if_consistent(&mut self.isoyear_div_100, try!(value.to_i32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `isoyear_mod_100` field from given value. + /// Tries to set the [`isoyear_mod_100`](#structfield.isoyear_mod_100) field from given value. pub fn set_isoyear_mod_100(&mut self, value: i64) -> ParseResult<()> { if value < 0 { return Err(OUT_OF_RANGE); } set_if_consistent(&mut self.isoyear_mod_100, try!(value.to_i32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `month` field from given value. + /// Tries to set the [`month`](#structfield.month) field from given value. pub fn set_month(&mut self, value: i64) -> ParseResult<()> { set_if_consistent(&mut self.month, try!(value.to_u32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `week_from_sun` field from given value. + /// Tries to set the [`week_from_sun`](#structfield.week_from_sun) field from given value. pub fn set_week_from_sun(&mut self, value: i64) -> ParseResult<()> { set_if_consistent(&mut self.week_from_sun, try!(value.to_u32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `week_from_mon` field from given value. + /// Tries to set the [`week_from_mon`](#structfield.week_from_mon) field from given value. pub fn set_week_from_mon(&mut self, value: i64) -> ParseResult<()> { set_if_consistent(&mut self.week_from_mon, try!(value.to_u32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `isoweek` field from given value. + /// Tries to set the [`isoweek`](#structfield.isoweek) field from given value. pub fn set_isoweek(&mut self, value: i64) -> ParseResult<()> { set_if_consistent(&mut self.isoweek, try!(value.to_u32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `weekday` field from given value. + /// Tries to set the [`weekday`](#structfield.weekday) field from given value. pub fn set_weekday(&mut self, value: Weekday) -> ParseResult<()> { set_if_consistent(&mut self.weekday, value) } - /// Tries to set the `ordinal` field from given value. + /// Tries to set the [`ordinal`](#structfield.ordinal) field from given value. pub fn set_ordinal(&mut self, value: i64) -> ParseResult<()> { set_if_consistent(&mut self.ordinal, try!(value.to_u32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `day` field from given value. + /// Tries to set the [`day`](#structfield.day) field from given value. pub fn set_day(&mut self, value: i64) -> ParseResult<()> { set_if_consistent(&mut self.day, try!(value.to_u32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `hour_div_12` field from given value. (`false` for AM, `true` for PM) + /// Tries to set the [`hour_div_12`](#structfield.hour_div_12) field from given value. + /// (`false` for AM, `true` for PM) pub fn set_ampm(&mut self, value: bool) -> ParseResult<()> { set_if_consistent(&mut self.hour_div_12, if value {1} else {0}) } - /// Tries to set the `hour_mod_12` field from given hour number in 12-hour clocks. + /// Tries to set the [`hour_mod_12`](#structfield.hour_mod_12) field from + /// given hour number in 12-hour clocks. pub fn set_hour12(&mut self, value: i64) -> ParseResult<()> { if value < 1 || value > 12 { return Err(OUT_OF_RANGE); } set_if_consistent(&mut self.hour_mod_12, value as u32 % 12) } - /// Tries to set both `hour_div_12` and `hour_mod_12` fields from given value. + /// Tries to set both [`hour_div_12`](#structfield.hour_div_12) and + /// [`hour_mod_12`](#structfield.hour_mod_12) fields from given value. pub fn set_hour(&mut self, value: i64) -> ParseResult<()> { let v = try!(value.to_u32().ok_or(OUT_OF_RANGE)); try!(set_if_consistent(&mut self.hour_div_12, v / 12)); @@ -191,27 +223,27 @@ impl Parsed { Ok(()) } - /// Tries to set the `minute` field from given value. + /// Tries to set the [`minute`](#structfield.minute) field from given value. pub fn set_minute(&mut self, value: i64) -> ParseResult<()> { set_if_consistent(&mut self.minute, try!(value.to_u32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `second` field from given value. + /// Tries to set the [`second`](#structfield.second) field from given value. pub fn set_second(&mut self, value: i64) -> ParseResult<()> { set_if_consistent(&mut self.second, try!(value.to_u32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `nanosecond` field from given value. + /// Tries to set the [`nanosecond`](#structfield.nanosecond) field from given value. pub fn set_nanosecond(&mut self, value: i64) -> ParseResult<()> { set_if_consistent(&mut self.nanosecond, try!(value.to_u32().ok_or(OUT_OF_RANGE))) } - /// Tries to set the `timestamp` field from given value. + /// Tries to set the [`timestamp`](#structfield.timestamp) field from given value. pub fn set_timestamp(&mut self, value: i64) -> ParseResult<()> { set_if_consistent(&mut self.timestamp, value) } - /// Tries to set the `offset` field from given value. + /// Tries to set the [`offset`](#structfield.offset) field from given value. pub fn set_offset(&mut self, value: i64) -> ParseResult<()> { set_if_consistent(&mut self.offset, try!(value.to_i32().ok_or(OUT_OF_RANGE))) } @@ -445,11 +477,11 @@ impl Parsed { } /// Returns a parsed naive date and time out of given fields, - /// except for the `offset` field (assumed to have a given value). + /// except for the [`offset`](#structfield.offset) field (assumed to have a given value). /// This is required for parsing a local time or other known-timezone inputs. /// /// This method is able to determine the combined date and time - /// from date and time fields or a single `timestamp` field. + /// from date and time fields or a single [`timestamp`](#structfield.timestamp) field. /// Either way those fields have to be consistent to each other. pub fn to_naive_datetime_with_offset(&self, offset: i32) -> ParseResult { let date = self.to_naive_date(); @@ -529,7 +561,8 @@ impl Parsed { /// Returns a parsed timezone-aware date and time out of given fields. /// /// This method is able to determine the combined date and time - /// from date and time fields or a single `timestamp` field, plus a time zone offset. + /// from date and time fields or a single [`timestamp`](#structfield.timestamp) field, + /// plus a time zone offset. /// Either way those fields have to be consistent to each other. pub fn to_datetime(&self) -> ParseResult> { let offset = try!(self.offset.ok_or(NOT_ENOUGH)); @@ -546,9 +579,11 @@ impl Parsed { /// with an additional `TimeZone` used to interpret and validate the local date. /// /// This method is able to determine the combined date and time - /// from date and time fields or a single `timestamp` field, plus a time zone offset. + /// from date and time fields or a single [`timestamp`](#structfield.timestamp) field, + /// plus a time zone offset. /// Either way those fields have to be consistent to each other. - /// If parsed fields include an UTC offset, it also has to be consistent to `offset`. + /// If parsed fields include an UTC offset, it also has to be consistent to + /// [`offset`](#structfield.offset). pub fn to_datetime_with_timezone(&self, tz: &Tz) -> ParseResult> { // if we have `timestamp` specified, guess an offset from that. let mut guessed_offset = 0; diff --git a/src/lib.rs b/src/lib.rs index 11785e1..1af9005 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -361,7 +361,8 @@ pub mod offset; pub mod naive { //! Date and time types which do not concern about the timezones. //! - //! They are primarily building blocks for other types (e.g. `TimeZone`), + //! They are primarily building blocks for other types + //! (e.g. [`TimeZone`](../offset/trait.TimeZone.html)), //! but can be also used for the simpler date and time handling. pub mod date; pub mod time; diff --git a/src/naive/date.rs b/src/naive/date.rs index 30a2b62..95eeb9c 100644 --- a/src/naive/date.rs +++ b/src/naive/date.rs @@ -1184,10 +1184,13 @@ impl Datelike for NaiveDate { /// /// assert_eq!(NaiveDate::from_ymd(2015, 1, 1).with_ordinal(60), /// Some(NaiveDate::from_ymd(2015, 3, 1))); - /// assert_eq!(NaiveDate::from_ymd(2016, 1, 1).with_ordinal(60), - /// Some(NaiveDate::from_ymd(2016, 2, 29))); /// assert_eq!(NaiveDate::from_ymd(2015, 1, 1).with_ordinal(366), /// None); // 2015 had only 365 days + /// + /// assert_eq!(NaiveDate::from_ymd(2016, 1, 1).with_ordinal(60), + /// Some(NaiveDate::from_ymd(2016, 2, 29))); + /// assert_eq!(NaiveDate::from_ymd(2016, 1, 1).with_ordinal(366), + /// Some(NaiveDate::from_ymd(2016, 12, 31))); /// ~~~~ #[inline] fn with_ordinal(&self, ordinal: u32) -> Option { @@ -1205,10 +1208,13 @@ impl Datelike for NaiveDate { /// /// assert_eq!(NaiveDate::from_ymd(2015, 1, 1).with_ordinal0(59), /// Some(NaiveDate::from_ymd(2015, 3, 1))); - /// assert_eq!(NaiveDate::from_ymd(2016, 1, 1).with_ordinal0(59), - /// Some(NaiveDate::from_ymd(2016, 2, 29))); /// assert_eq!(NaiveDate::from_ymd(2015, 1, 1).with_ordinal0(365), /// None); // 2015 had only 365 days + /// + /// assert_eq!(NaiveDate::from_ymd(2016, 1, 1).with_ordinal0(59), + /// Some(NaiveDate::from_ymd(2016, 2, 29))); + /// assert_eq!(NaiveDate::from_ymd(2016, 1, 1).with_ordinal0(365), + /// Some(NaiveDate::from_ymd(2016, 12, 31))); /// ~~~~ #[inline] fn with_ordinal0(&self, ordinal0: u32) -> Option { diff --git a/src/naive/datetime.rs b/src/naive/datetime.rs index c6a7585..05f52c3 100644 --- a/src/naive/datetime.rs +++ b/src/naive/datetime.rs @@ -2,9 +2,7 @@ // Copyright (c) 2014-2015, Kang Seonghoon. // See README.md and LICENSE.txt for details. -/*! - * ISO 8601 date and time without timezone. - */ +//! ISO 8601 date and time without timezone. use std::{str, fmt, hash}; use std::ops::{Add, Sub}; @@ -35,7 +33,7 @@ impl NaiveDateTime { } /// Makes a new `NaiveDateTime` from the number of non-leap seconds - /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp") + /// since the midnight UTC on January 1, 1970 (aka "UNIX timestamp") /// and the number of nanoseconds since the last whole non-leap second. /// /// Panics on the out-of-range number of seconds and/or invalid nanosecond. @@ -46,7 +44,7 @@ impl NaiveDateTime { } /// Makes a new `NaiveDateTime` from the number of non-leap seconds - /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp") + /// since the midnight UTC on January 1, 1970 (aka "UNIX timestamp") /// and the number of nanoseconds since the last whole non-leap second. /// /// Returns `None` on the out-of-range number of seconds and/or invalid nanosecond. @@ -62,13 +60,13 @@ impl NaiveDateTime { } } - /// *Deprecated:* Same to `NaiveDateTime::from_timestamp`. + /// *Deprecated:* Same to [`NaiveDateTime::from_timestamp`](#method.from_timestamp). #[inline] pub fn from_num_seconds_from_unix_epoch(secs: i64, nsecs: u32) -> NaiveDateTime { NaiveDateTime::from_timestamp(secs, nsecs) } - /// *Deprecated:* Same to `NaiveDateTime::from_timestamp_opt`. + /// *Deprecated:* Same to [`NaiveDateTime::from_timestamp_opt`](#method.from_timestamp_opt). #[inline] pub fn from_num_seconds_from_unix_epoch_opt(secs: i64, nsecs: u32) -> Option { NaiveDateTime::from_timestamp_opt(secs, nsecs) @@ -95,9 +93,10 @@ impl NaiveDateTime { self.time } - /// Returns the number of non-leap seconds since January 1, 1970 0:00:00 UTC - /// (aka "UNIX timestamp"). + /// Returns the number of non-leap seconds since the midnight on January 1, 1970. + /// /// Note that this does *not* account for the timezone! + /// The true "UNIX timestamp" would count seconds since the midnight *UTC* on the epoch. #[inline] pub fn timestamp(&self) -> i64 { let ndays = self.date.num_days_from_ce() as i64; @@ -105,37 +104,34 @@ impl NaiveDateTime { (ndays - 719163) * 86400 + nseconds } - /// Returns the number of milliseconds since the last second boundary + /// Returns the number of milliseconds since the last whole non-leap second. /// - /// warning: in event of a leap second, this may exceed 999 - /// - /// note: this is not the number of milliseconds since January 1, 1970 0:00:00 UTC + /// The return value ranges from 0 to 999, + /// or for [leap seconds](../time/index.html#leap-second-handling), to 1,999. #[inline] pub fn timestamp_subsec_millis(&self) -> u32 { self.timestamp_subsec_nanos() / 1_000_000 } - /// Returns the number of microseconds since the last second boundary + /// Returns the number of microseconds since the last whole non-leap second. /// - /// warning: in event of a leap second, this may exceed 999_999 - /// - /// note: this is not the number of microseconds since January 1, 1970 0:00:00 UTC + /// The return value ranges from 0 to 999,999, + /// or for [leap seconds](../time/index.html#leap-second-handling), to 1,999,999. #[inline] pub fn timestamp_subsec_micros(&self) -> u32 { self.timestamp_subsec_nanos() / 1_000 } - /// Returns the number of nanoseconds since the last second boundary + /// Returns the number of nanoseconds since the last whole non-leap second. /// - /// warning: in event of a leap second, this may exceed 999_999_999 - /// - /// note: this is not the number of nanoseconds since January 1, 1970 0:00:00 UTC + /// The return value ranges from 0 to 999,999,999, + /// or for [leap seconds](../time/index.html#leap-second-handling), to 1,999,999,999. #[inline] pub fn timestamp_subsec_nanos(&self) -> u32 { self.time.nanosecond() } - /// *Deprecated:* Same to `NaiveDateTime::timestamp`. + /// *Deprecated:* Same to [`NaiveDateTime::timestamp`](#method.timestamp). #[inline] pub fn num_seconds_from_unix_epoch(&self) -> i64 { self.timestamp() @@ -202,46 +198,317 @@ impl NaiveDateTime { } impl Datelike for NaiveDateTime { - #[inline] fn year(&self) -> i32 { self.date.year() } - #[inline] fn month(&self) -> u32 { self.date.month() } - #[inline] fn month0(&self) -> u32 { self.date.month0() } - #[inline] fn day(&self) -> u32 { self.date.day() } - #[inline] fn day0(&self) -> u32 { self.date.day0() } - #[inline] fn ordinal(&self) -> u32 { self.date.ordinal() } - #[inline] fn ordinal0(&self) -> u32 { self.date.ordinal0() } - #[inline] fn weekday(&self) -> Weekday { self.date.weekday() } - #[inline] fn isoweekdate(&self) -> (i32, u32, Weekday) { self.date.isoweekdate() } + /// Returns the year number in the [calendar date](./index.html#calendar-date). + /// + /// See also the [`NaiveDate::year`](../date/struct.NaiveDate.html#method.year) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 25).and_hms(12, 34, 56); + /// assert_eq!(dt.year(), 2015); + /// ~~~~ + #[inline] + fn year(&self) -> i32 { + self.date.year() + } + /// Returns the month number starting from 1. + /// + /// The return value ranges from 1 to 12. + /// + /// See also the [`NaiveDate::month`](../date/struct.NaiveDate.html#method.month) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 25).and_hms(12, 34, 56); + /// assert_eq!(dt.month(), 9); + /// ~~~~ + #[inline] + fn month(&self) -> u32 { + self.date.month() + } + + /// Returns the month number starting from 0. + /// + /// The return value ranges from 0 to 11. + /// + /// See also the [`NaiveDate::month0`](../date/struct.NaiveDate.html#method.month0) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 25).and_hms(12, 34, 56); + /// assert_eq!(dt.month0(), 8); + /// ~~~~ + #[inline] + fn month0(&self) -> u32 { + self.date.month0() + } + + /// Returns the day of month starting from 1. + /// + /// The return value ranges from 1 to 31. (The last day of month differs by months.) + /// + /// See also the [`NaiveDate::day`](../date/struct.NaiveDate.html#method.day) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 25).and_hms(12, 34, 56); + /// assert_eq!(dt.day(), 25); + /// ~~~~ + #[inline] + fn day(&self) -> u32 { + self.date.day() + } + + /// Returns the day of month starting from 0. + /// + /// The return value ranges from 0 to 30. (The last day of month differs by months.) + /// + /// See also the [`NaiveDate::day0`](../date/struct.NaiveDate.html#method.day0) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 25).and_hms(12, 34, 56); + /// assert_eq!(dt.day0(), 24); + /// ~~~~ + #[inline] + fn day0(&self) -> u32 { + self.date.day0() + } + + /// Returns the day of year starting from 1. + /// + /// The return value ranges from 1 to 366. (The last day of year differs by years.) + /// + /// See also the [`NaiveDate::ordinal`](../date/struct.NaiveDate.html#method.ordinal) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 25).and_hms(12, 34, 56); + /// assert_eq!(dt.ordinal(), 268); + /// ~~~~ + #[inline] + fn ordinal(&self) -> u32 { + self.date.ordinal() + } + + /// Returns the day of year starting from 0. + /// + /// The return value ranges from 0 to 365. (The last day of year differs by years.) + /// + /// See also the [`NaiveDate::ordinal0`](../date/struct.NaiveDate.html#method.ordinal0) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 25).and_hms(12, 34, 56); + /// assert_eq!(dt.ordinal0(), 267); + /// ~~~~ + #[inline] + fn ordinal0(&self) -> u32 { + self.date.ordinal0() + } + + /// Returns the day of week. + /// + /// See also the [`NaiveDate::weekday`](../date/struct.NaiveDate.html#method.weekday) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike, Weekday}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 25).and_hms(12, 34, 56); + /// assert_eq!(dt.weekday(), Weekday::Fri); + /// ~~~~ + #[inline] + fn weekday(&self) -> Weekday { + self.date.weekday() + } + + #[inline] + fn isoweekdate(&self) -> (i32, u32, Weekday) { + self.date.isoweekdate() + } + + /// Makes a new `NaiveDateTime` with the year number changed. + /// + /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// + /// See also the + /// [`NaiveDate::with_year`](../date/struct.NaiveDate.html#method.with_year) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 25).and_hms(12, 34, 56); + /// assert_eq!(dt.with_year(2016), Some(NaiveDate::from_ymd(2016, 9, 25).and_hms(12, 34, 56))); + /// assert_eq!(dt.with_year(-308), Some(NaiveDate::from_ymd(-308, 9, 25).and_hms(12, 34, 56))); + /// ~~~~ #[inline] fn with_year(&self, year: i32) -> Option { self.date.with_year(year).map(|d| NaiveDateTime { date: d, ..*self }) } + /// Makes a new `NaiveDateTime` with the month number (starting from 1) changed. + /// + /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// + /// See also the + /// [`NaiveDate::with_month`](../date/struct.NaiveDate.html#method.with_month) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 30).and_hms(12, 34, 56); + /// assert_eq!(dt.with_month(10), Some(NaiveDate::from_ymd(2015, 10, 30).and_hms(12, 34, 56))); + /// assert_eq!(dt.with_month(13), None); // no month 13 + /// assert_eq!(dt.with_month(2), None); // no February 30 + /// ~~~~ #[inline] fn with_month(&self, month: u32) -> Option { self.date.with_month(month).map(|d| NaiveDateTime { date: d, ..*self }) } + /// Makes a new `NaiveDateTime` with the month number (starting from 0) changed. + /// + /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// + /// See also the + /// [`NaiveDate::with_month0`](../date/struct.NaiveDate.html#method.with_month0) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 30).and_hms(12, 34, 56); + /// assert_eq!(dt.with_month0(9), Some(NaiveDate::from_ymd(2015, 10, 30).and_hms(12, 34, 56))); + /// assert_eq!(dt.with_month0(12), None); // no month 13 + /// assert_eq!(dt.with_month0(1), None); // no February 30 + /// ~~~~ #[inline] fn with_month0(&self, month0: u32) -> Option { self.date.with_month0(month0).map(|d| NaiveDateTime { date: d, ..*self }) } + /// Makes a new `NaiveDateTime` with the day of month (starting from 1) changed. + /// + /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// + /// See also the + /// [`NaiveDate::with_day`](../date/struct.NaiveDate.html#method.with_day) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 8).and_hms(12, 34, 56); + /// assert_eq!(dt.with_day(30), Some(NaiveDate::from_ymd(2015, 9, 30).and_hms(12, 34, 56))); + /// assert_eq!(dt.with_day(31), None); // no September 31 + /// ~~~~ #[inline] fn with_day(&self, day: u32) -> Option { self.date.with_day(day).map(|d| NaiveDateTime { date: d, ..*self }) } + /// Makes a new `NaiveDateTime` with the day of month (starting from 0) changed. + /// + /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// + /// See also the + /// [`NaiveDate::with_day0`](../date/struct.NaiveDate.html#method.with_day0) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 8).and_hms(12, 34, 56); + /// assert_eq!(dt.with_day0(29), Some(NaiveDate::from_ymd(2015, 9, 30).and_hms(12, 34, 56))); + /// assert_eq!(dt.with_day0(30), None); // no September 31 + /// ~~~~ #[inline] fn with_day0(&self, day0: u32) -> Option { self.date.with_day0(day0).map(|d| NaiveDateTime { date: d, ..*self }) } + /// Makes a new `NaiveDateTime` with the day of year (starting from 1) changed. + /// + /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// + /// See also the + /// [`NaiveDate::with_ordinal`](../date/struct.NaiveDate.html#method.with_ordinal) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 8).and_hms(12, 34, 56); + /// assert_eq!(dt.with_ordinal(60), + /// Some(NaiveDate::from_ymd(2015, 3, 1).and_hms(12, 34, 56))); + /// assert_eq!(dt.with_ordinal(366), None); // 2015 had only 365 days + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2016, 9, 8).and_hms(12, 34, 56); + /// assert_eq!(dt.with_ordinal(60), + /// Some(NaiveDate::from_ymd(2016, 2, 29).and_hms(12, 34, 56))); + /// assert_eq!(dt.with_ordinal(366), + /// Some(NaiveDate::from_ymd(2016, 12, 31).and_hms(12, 34, 56))); + /// ~~~~ #[inline] fn with_ordinal(&self, ordinal: u32) -> Option { self.date.with_ordinal(ordinal).map(|d| NaiveDateTime { date: d, ..*self }) } + /// Makes a new `NaiveDateTime` with the day of year (starting from 0) changed. + /// + /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// + /// See also the + /// [`NaiveDate::with_ordinal0`](../date/struct.NaiveDate.html#method.with_ordinal0) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Datelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 8).and_hms(12, 34, 56); + /// assert_eq!(dt.with_ordinal0(59), + /// Some(NaiveDate::from_ymd(2015, 3, 1).and_hms(12, 34, 56))); + /// assert_eq!(dt.with_ordinal0(365), None); // 2015 had only 365 days + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2016, 9, 8).and_hms(12, 34, 56); + /// assert_eq!(dt.with_ordinal0(59), + /// Some(NaiveDate::from_ymd(2016, 2, 29).and_hms(12, 34, 56))); + /// assert_eq!(dt.with_ordinal0(365), + /// Some(NaiveDate::from_ymd(2016, 12, 31).and_hms(12, 34, 56))); + /// ~~~~ #[inline] fn with_ordinal0(&self, ordinal0: u32) -> Option { self.date.with_ordinal0(ordinal0).map(|d| NaiveDateTime { date: d, ..*self }) @@ -249,32 +516,177 @@ impl Datelike for NaiveDateTime { } impl Timelike for NaiveDateTime { - #[inline] fn hour(&self) -> u32 { self.time.hour() } - #[inline] fn minute(&self) -> u32 { self.time.minute() } - #[inline] fn second(&self) -> u32 { self.time.second() } - #[inline] fn nanosecond(&self) -> u32 { self.time.nanosecond() } + /// Returns the hour number from 0 to 23. + /// + /// See also the [`NaiveTime::hour`](../time/struct.NaiveTime.html#method.hour) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Timelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 8).and_hms_milli(12, 34, 56, 789); + /// assert_eq!(dt.hour(), 12); + /// ~~~~ + #[inline] + fn hour(&self) -> u32 { + self.time.hour() + } + /// Returns the minute number from 0 to 59. + /// + /// See also the [`NaiveTime::minute`](../time/struct.NaiveTime.html#method.minute) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Timelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 8).and_hms_milli(12, 34, 56, 789); + /// assert_eq!(dt.minute(), 34); + /// ~~~~ + #[inline] + fn minute(&self) -> u32 { + self.time.minute() + } + + /// Returns the second number from 0 to 59. + /// + /// See also the [`NaiveTime::second`](../time/struct.NaiveTime.html#method.second) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Timelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 8).and_hms_milli(12, 34, 56, 789); + /// assert_eq!(dt.second(), 56); + /// ~~~~ + #[inline] + fn second(&self) -> u32 { + self.time.second() + } + + /// Returns the number of nanoseconds since the whole non-leap second. + /// The range from 1,000,000,000 to 1,999,999,999 represents + /// the [leap second](./naive/time/index.html#leap-second-handling). + /// + /// See also the + /// [`NaiveTime::nanosecond`](../time/struct.NaiveTime.html#method.nanosecond) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Timelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 8).and_hms_milli(12, 34, 56, 789); + /// assert_eq!(dt.nanosecond(), 789_000_000); + /// ~~~~ + #[inline] + fn nanosecond(&self) -> u32 { + self.time.nanosecond() + } + + /// Makes a new `NaiveDateTime` with the hour number changed. + /// + /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// + /// See also the + /// [`NaiveTime::with_hour`](../time/struct.NaiveTime.html#method.with_hour) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Timelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 8).and_hms_milli(12, 34, 56, 789); + /// assert_eq!(dt.with_hour(7), + /// Some(NaiveDate::from_ymd(2015, 9, 8).and_hms_milli(7, 34, 56, 789))); + /// assert_eq!(dt.with_hour(24), None); + /// ~~~~ #[inline] fn with_hour(&self, hour: u32) -> Option { self.time.with_hour(hour).map(|t| NaiveDateTime { time: t, ..*self }) } + /// Makes a new `NaiveDateTime` with the minute number changed. + /// + /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// + /// See also the + /// [`NaiveTime::with_minute`](../time/struct.NaiveTime.html#method.with_minute) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Timelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 8).and_hms_milli(12, 34, 56, 789); + /// assert_eq!(dt.with_minute(45), + /// Some(NaiveDate::from_ymd(2015, 9, 8).and_hms_milli(12, 45, 56, 789))); + /// assert_eq!(dt.with_minute(60), None); + /// ~~~~ #[inline] fn with_minute(&self, min: u32) -> Option { self.time.with_minute(min).map(|t| NaiveDateTime { time: t, ..*self }) } + /// Makes a new `NaiveDateTime` with the second number changed. + /// + /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// As with the [`second`](#method.second) method, + /// the input range is restricted to 0 through 59. + /// + /// See also the + /// [`NaiveTime::with_second`](../time/struct.NaiveTime.html#method.with_second) method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Timelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 8).and_hms_milli(12, 34, 56, 789); + /// assert_eq!(dt.with_second(17), + /// Some(NaiveDate::from_ymd(2015, 9, 8).and_hms_milli(12, 34, 17, 789))); + /// assert_eq!(dt.with_second(60), None); + /// ~~~~ #[inline] fn with_second(&self, sec: u32) -> Option { self.time.with_second(sec).map(|t| NaiveDateTime { time: t, ..*self }) } + /// Makes a new `NaiveDateTime` with nanoseconds since the whole non-leap second changed. + /// + /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// As with the [`nanosecond`](#method.nanosecond) method, + /// the input range can exceed 1,000,000,000 for leap seconds. + /// + /// See also the + /// [`NaiveTime::with_nanosecond`](../time/struct.NaiveTime.html#method.with_nanosecond) + /// method. + /// + /// # Example + /// + /// ~~~~ + /// use chrono::{NaiveDate, NaiveDateTime, Timelike}; + /// + /// let dt: NaiveDateTime = NaiveDate::from_ymd(2015, 9, 8).and_hms_milli(12, 34, 56, 789); + /// assert_eq!(dt.with_nanosecond(333_333_333), + /// Some(NaiveDate::from_ymd(2015, 9, 8).and_hms_nano(12, 34, 56, 333_333_333))); + /// assert_eq!(dt.with_nanosecond(1_333_333_333), // leap second + /// Some(NaiveDate::from_ymd(2015, 9, 8).and_hms_nano(12, 34, 56, 1_333_333_333))); + /// assert_eq!(dt.with_nanosecond(2_000_000_000), None); + /// ~~~~ #[inline] fn with_nanosecond(&self, nano: u32) -> Option { self.time.with_nanosecond(nano).map(|t| NaiveDateTime { time: t, ..*self }) } } +/// `NaiveDateTime` can be used as a key to the hash maps (in principle). +/// +/// Practically this also takes account of fractional seconds, so it is not recommended. +/// (For the obvious reason this also distinguishes leap seconds from non-leap seconds.) impl hash::Hash for NaiveDateTime { fn hash(&self, state: &mut H) { self.date.hash(state); diff --git a/src/naive/time.rs b/src/naive/time.rs index 0c534cd..f198daf 100644 --- a/src/naive/time.rs +++ b/src/naive/time.rs @@ -560,7 +560,7 @@ impl Timelike for NaiveTime { /// Makes a new `NaiveTime` with the second number changed. /// /// Returns `None` when the resulting `NaiveTime` would be invalid. - /// As with the [`second`](#tymethod.second) method, + /// As with the [`second`](#method.second) method, /// the input range is restricted to 0 through 59. /// /// # Example @@ -582,7 +582,7 @@ impl Timelike for NaiveTime { /// Makes a new `NaiveTime` with nanoseconds since the whole non-leap second changed. /// /// Returns `None` when the resulting `NaiveTime` would be invalid. - /// As with the [`nanosecond`](#tymethod.nanosecond) method, + /// As with the [`nanosecond`](#method.nanosecond) method, /// the input range can exceed 1,000,000,000 for leap seconds. /// /// # Example