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

More cross links and detailed examples for docs. 

Also fixed some broken links (hard to catch from source files).
This commit is contained in:
Kang Seonghoon 2016-08-01 03:23:46 +09:00
parent 932e29aa94
commit 4475ee5a48
5 changed files with 539 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
src/format/parsed.rs
View File

@ -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<i32>,
/// 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<i32>,
/// Year modulo 100. Implies that the year is >= 1 BCE when set.
pub year_mod_100: Option<i32>,
/// Year in the ISO week date. This can be negative unlike `isoyear_{div,mod}_100` fields.
pub isoyear: Option<i32>,
/// 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<i32>,
/// 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<i32>,
/// 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<i32>,
/// Month (1--12).
pub month: Option<u32>,
/// 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<u32>,
/// 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<u32>,
/// 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<u32>,
/// Day of the week.
pub weekday: Option<Weekday>,
/// Day of the year (1--365 or 1--366 depending on the year).
pub ordinal: Option<u32>,
/// Day of the month (1--28, 1--29, 1--30 or 1--31 depending on the month).
pub day: Option<u32>,
/// Hour number divided by 12 (0--1). 0 indicates AM and 1 indicates PM.
pub hour_div_12: Option<u32>,
/// Hour number modulo 12 (0--11).
pub hour_mod_12: Option<u32>,
/// Minute number (0--59).
pub minute: Option<u32>,
/// Second number (0--60, accounting for leap seconds).
pub second: Option<u32>,
/// The number of nanoseconds since the whole second (0--999,999,999).
pub nanosecond: Option<u32>,
/// 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<i64>,
/// Offset from the local time to UTC, in seconds.
pub offset: Option<i32>,
}
@ -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<NaiveDateTime> {
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<DateTime<FixedOffset>> {
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<Tz: TimeZone>(&self, tz: &Tz) -> ParseResult<DateTime<Tz>> {
// if we have `timestamp` specified, guess an offset from that.
let mut guessed_offset = 0;

3
src/lib.rs
View File

@ -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;

14
src/naive/date.rs
View File

@ -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<NaiveDate> {
@ -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<NaiveDate> {

482
src/naive/datetime.rs
View File

@ -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> {
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<NaiveDateTime> {
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<NaiveDateTime> {
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<NaiveDateTime> {
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<NaiveDateTime> {
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<NaiveDateTime> {
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<NaiveDateTime> {
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<NaiveDateTime> {
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<NaiveDateTime> {
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<NaiveDateTime> {
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<NaiveDateTime> {
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<NaiveDateTime> {
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<H: hash::Hasher>(&self, state: &mut H) {
self.date.hash(state);

4
src/naive/time.rs
View File

@ -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