Struct hifitime::datetime::Datetime

pub struct Datetime { /* fields omitted */ }

Datetime supports date time has used by most humans. All time zones are defined with respect to UTC. Moreover, Datetime inherently supports the past leap seconds, as reported by the IETF and NIST at here. NOTE: leap seconds cannot be predicted! This module will be updated as soon as possible after a new leap second has been announced. WARNING: The historical oddities with calendars are not yet supported.

Methods

impl Datetime

pub fn new(
    year: i32,
    month: u8,
    day: u8,
    hour: u8,
    minute: u8,
    second: u8,
    nanos: u32
) -> Result<Datetime, Errors>

Creates a new UTC-offsetted datetime, with support for all the leap seconds with respect to TAI. NOTE: UTC leap seconds may be confusing because several dates have the same number of seconds since TAI epoch. WARNING: Does not support automatic carry and will return an error if so. WARNING: Although PartialOrd is implemented for Utc, the ambiguity of leap seconds as explained elsewhere in this documentation may lead to odd results (cf. examples below).

Examples

use hifitime::datetime::{Datetime, TimeSystem};
use hifitime::instant::{Duration, Era, Instant};
use hifitime::julian::ModifiedJulian;

let epoch = Datetime::new(1900, 01, 01, 0, 0, 0, 0).expect("epoch failed");
assert_eq!(
    epoch.into_instant(),
    Instant::new(0, 0, Era::Present),
    "Incorrect Epoch computed"
);

assert_eq!(
    Datetime::new(1971, 12, 31, 23, 59, 59, 0)
        .expect("January 1972 leap second failed")
        .into_instant(),
    Instant::new(2272060799, 0, Era::Present),
    "Incorrect January 1972 pre-leap second number computed"
);
assert_eq!(
    Datetime::new(1971, 12, 31, 23, 59, 59, 0)
        .expect("January 1972 1 second before leap second failed")
        .into_instant(),
    Datetime::new(1971, 12, 31, 23, 59, 60, 0)
        .expect("January 1972 1 second before leap second failed")
        .into_instant(),
    "Incorrect January 1972 leap second number computed"
);

// Example of odd behavior when comparing/ordering dates using Utc or `into_instant`
// Utc order claims (correctly) that the 60th second is _after_ the 59th. But the instant
// is actually different because the 60th second is where we've inserted the leap second.
assert!(
    Datetime::new(1971, 12, 31, 23, 59, 59, 0).expect(
        "January 1972 1 second before leap second failed",
    ) <
        Datetime::new(1971, 12, 31, 23, 59, 60, 0).expect(
            "January 1972 1 second before leap second failed",
        ),
    "60th second should have a different instant than 59th second"
);
assert!(
    Datetime::new(1971, 12, 31, 23, 59, 59, 0)
        .expect("January 1972 1 second before leap second failed")
        .into_instant() ==
        Datetime::new(1971, 12, 31, 23, 59, 60, 0)
            .expect("January 1972 1 second before leap second failed")
            .into_instant(),
    "60th second should have a different instant than 59th second"
);
// Hence one second after the leap second, we get the following behavior (note the change
// from equality to less when comparing via instant).
assert!(
    Datetime::new(1971, 12, 31, 23, 59, 60, 0).expect(
        "January 1972 1 second before leap second failed",
    ) <
        Datetime::new(1972, 01, 01, 00, 00, 00, 0).expect(
            "January 1972 1 second before leap second failed",
        ),
    "60th second should have a different instant than 59th second"
);
assert!(
    Datetime::new(1971, 12, 31, 23, 59, 60, 0)
        .expect("January 1972 1 second before leap second failed")
        .into_instant() <
        Datetime::new(1972, 01, 01, 00, 00, 00, 0)
            .expect("January 1972 1 second before leap second failed")
            .into_instant(),
    "60th second should have a different instant than 59th second"
);

let santa = Datetime::new(2017, 12, 25, 01, 02, 14, 0).expect("Xmas failed");

assert_eq!(
    santa.into_instant() + Duration::new(3600, 0),
    Datetime::new(2017, 12, 25, 02, 02, 14, 0)
        .expect("Xmas failed")
        .into_instant(),
    "Could not add one hour to Christmas"
);
assert_eq!(format!("{}", santa), "2017-12-25T01:02:14+00:00");
assert_eq!(
    ModifiedJulian::from_instant(santa.into_instant()).days,
    58112.043217592596
);
assert_eq!(
    ModifiedJulian::from_instant(santa.into_instant()).julian_days(),
    2458112.5432175924
);

pub fn with_offset(
    year: i32,
    month: u8,
    day: u8,
    hour: u8,
    minute: u8,
    second: u8,
    nanos: u32,
    offset: Offset
) -> Result<Datetime, Errors>

Creates a new Datetime with the specified UTC time offset. Works like Datetime::new in every way but it sets the UTC time offset to the one provided.

Examples

use hifitime::datetime::{Datetime, FixedOffset, TimeSystem};

let santa_ktz = Datetime::with_offset(
    2017,
    12,
    25,
    00,
    00,
    00,
    00,
    FixedOffset::west_with_hours(10),
).expect("Santa failed");
assert_eq!(format!("{}", santa_ktz), "2017-12-25T00:00:00+10:00");
let santa_wtz = Datetime::with_offset(
    2017,
    12,
    25,
    00,
    00,
    00,
    00,
    FixedOffset::east_with_hours(10),
).expect("Santa failed");
assert_eq!(format!("{}", santa_wtz), "2017-12-25T00:00:00-10:00");
assert!(
    santa_wtz < santa_ktz,
    "PartialOrd with different timezones failed"
);
assert!(
    santa_wtz.into_instant() < santa_ktz.into_instant(),
    "PartialOrd with different timezones failed via Instant"
);
assert_eq!(
    format!("{}", santa_wtz.to_utc()),
    "2017-12-24T14:00:00+00:00"
);

pub fn year(&self) -> &i32

Returns the year of this Datetime date time.

pub fn month(&self) -> &u8

Returns the month of this Datetime date time.

pub fn day(&self) -> &u8

Returns the day of this Datetime date time.

pub fn hour(&self) -> &u8

Returns the hour of this Datetime date time.

pub fn minute(&self) -> &u8

Returns the minute of this Datetime date time.

pub fn second(&self) -> &u8

Returns the second of this Datetime date time.

pub fn nanos(&self) -> &u32

Returns the nanoseconds of this Datetime date time.

pub fn offset(&self) -> &Offset

Returns the offset of this Datetime date time.

pub fn at_midnight(year: i32, month: u8, day: u8) -> Result<Datetime, Errors>

Creates a new UTC date at midnight (i.e. hours = 0, mins = 0, secs = 0, nanos = 0)

Examples

use hifitime::datetime::{Datetime, TimeSystem};
use hifitime::instant::{Era, Instant};

let epoch = Datetime::at_midnight(1900, 01, 01).expect("epoch failed");
assert_eq!(
    epoch.into_instant(),
    Instant::new(0, 0, Era::Present),
    "Incorrect Epoch computed"
);

assert_eq!(
    Datetime::at_midnight(1972, 01, 01)
        .expect("Post January 1972 leap second failed")
        .into_instant(),
    Instant::new(2272060800, 0, Era::Present),
    "Incorrect January 1972 post-leap second number computed at midnight"
);

pub fn at_noon(year: i32, month: u8, day: u8) -> Result<Datetime, Errors>

Creates a new UTC date at noon (i.e. hours = 12, mins = 0, secs = 0, nanos = 0)

Examples

use hifitime::datetime::{Datetime, TimeSystem};
use hifitime::instant::{Era, Instant};

let epoch = Datetime::at_noon(1900, 01, 01).expect("epoch failed");
assert_eq!(
    epoch.into_instant(),
    Instant::new(43200, 0, Era::Present),
    "Incorrect Epoch computed"
);

assert_eq!(
    Datetime::at_noon(1972, 01, 01)
        .expect("Post January 1972 leap second failed")
        .into_instant(),
    Instant::new(2272104000, 0, Era::Present),
    "Incorrect January 1972 post-leap second number computed at noon"
);

pub fn to_utc(self) -> Datetime

pub fn to_offset(self, offset: Offset) -> Datetime

Trait Implementations

impl Copy for Datetime

impl Clone for Datetime

fn clone(&self) -> Datetime

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Datetime

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl PartialEq for Datetime

fn eq(&self, __arg_0: &Datetime) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, __arg_0: &Datetime) -> bool

This method tests for !=.

impl PartialOrd for Datetime

fn partial_cmp(&self, __arg_0: &Datetime) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, __arg_0: &Datetime) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, __arg_0: &Datetime) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, __arg_0: &Datetime) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, __arg_0: &Datetime) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl TimeSystem for Datetime

fn from_instant(instant: Instant) -> Datetime

from_instant converts an Instant to a Datetime with an offset of Utc (i.e zero).

fn into_instant(self) -> Instant

into_instant returns an Instant from the Datetime while correcting for the offset.

impl Display for Datetime

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl LowerHex for Datetime

fn fmt(&self, f: &mut Formatter) -> Result

Formats as human readable with date and time separated by a space and no offset.

Example

use std::str::FromStr;
use hifitime::datetime::{Datetime, FixedOffset};

let dt =
    Datetime::with_offset(2017, 1, 14, 0, 31, 55, 0, FixedOffset::east_with_hours(5)).unwrap();
assert_eq!(format!("{:x}", dt), "2017-01-14 00:31:55");

impl UpperHex for Datetime

fn fmt(&self, f: &mut Formatter) -> Result

Formats as ISO8601 but without the offset.

Example

use std::str::FromStr;
use hifitime::datetime::{Datetime, FixedOffset};

let dt =
    Datetime::with_offset(2017, 1, 14, 0, 31, 55, 0, FixedOffset::east_with_hours(5)).unwrap();
assert_eq!(format!("{:X}", dt), "2017-01-14T00:31:55");

impl Add<Duration> for Datetime

type Output = Datetime

The resulting type after applying the + operator.

fn add(self, delta: Duration) -> Datetime

Adds a given std::time::Duration to a Datetime.

Examples

use hifitime::datetime::Datetime;
use std::time::Duration;
let santa = Datetime::at_midnight(2017, 12, 25).unwrap();
let santa_1h = Datetime::at_midnight(2017, 12, 25).unwrap() + Duration::new(3600, 0);
assert_eq!(santa.hour() + &1, *santa_1h.hour());

impl Sub<Duration> for Datetime

type Output = Datetime

The resulting type after applying the - operator.

fn sub(self, delta: Duration) -> Datetime

Adds a given std::time::Duration to a Datetime.

Examples

use hifitime::datetime::Datetime;
use std::time::Duration;
let santa = Datetime::at_midnight(2017, 12, 25).unwrap();
let santa_1h = Datetime::at_midnight(2017, 12, 25).unwrap() - Duration::new(3600, 0);
assert_eq!(santa.day() - &1, *santa_1h.day()); // Day underflow
assert_eq!(santa_1h.hour(), &23);

impl FromStr for Datetime

type Err = Errors

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Converts an ISO8601 Datetime representation with offset to a Datetime object with correct offset. The T which separates the date from the time can be replaced with a single whitespace character (\W). The offset is also optional, cf. the examples below.

Examples

use std::str::FromStr;
use hifitime::datetime::{Datetime, Offset};
use hifitime::instant::Era;
let offset = Offset::new(3600 * 2 + 60 * 15, 0, Era::Past);
let dt = Datetime::with_offset(2017, 1, 14, 0, 31, 55, 0, offset).unwrap();
assert_eq!(
    dt,
    Datetime::from_str("2017-01-14T00:31:55-02:15").unwrap()
);
assert_eq!(
    dt,
    Datetime::from_str("2017-01-14 00:31:55-02:15").unwrap()
);
let dt = Datetime::new(2017, 1, 14, 0, 31, 55, 0).unwrap();
assert_eq!(
    dt,
    Datetime::from_str("2017-01-14T00:31:55").unwrap()
);
assert_eq!(
    dt,
    Datetime::from_str("2017-01-14 00:31:55").unwrap()
);