Struct Time

Source

pub struct Time { /* private fields */ }

Expand description

ISO 8601 time without timezone. Allows for the nanosecond precision and optional leap second representation.

§Leap Second Handling

Since 1960s, the manmade atomic clock has been so accurate that it is much more accurate than Earth’s own motion. It became desirable to define the civil time in terms of the atomic clock, but that risks the desynchronization of the civil time from Earth. To account for this, the designers of the Coordinated Universal Time (UTC) made that the UTC should be kept within 0.9 seconds of the observed Earth-bound time. When the mean solar day is longer than the ideal (86,400 seconds), the error slowly accumulates and it is necessary to add a leap second to slow the UTC down a bit. (We may also remove a second to speed the UTC up a bit, but it never happened.) The leap second, if any, follows 23:59:59 of June 30 or December 31 in the UTC.

Fast forward to the 21st century, we have seen 26 leap seconds from January 1972 to December 2015. Yes, 26 seconds. Probably you can read this paragraph within 26 seconds. But those 26 seconds, and possibly more in the future, are never predictable, and whether to add a leap second or not is known only before 6 months. Internet-based clocks (via NTP) do account for known leap seconds, but the system API normally doesn’t (and often can’t, with no network connection) and there is no reliable way to retrieve leap second information.

Chrono does not try to accurately implement leap seconds; it is impossible. Rather, it allows for leap seconds but behaves as if there are no other leap seconds. Various operations will ignore any possible leap second(s) except when any of the operands were actually leap seconds.

If you cannot tolerate this behavior, you must use a separate TimeZone for the International Atomic Time (TAI). TAI is like UTC but has no leap seconds, and thus slightly differs from UTC. Chrono does not yet provide such implementation, but it is planned.

§Representing Leap Seconds

The leap second is indicated via fractional seconds more than 1 second. This makes possible to treat a leap second as the prior non-leap second if you don’t care about sub-second accuracy. You should use the proper formatting to get the raw leap second.

All methods accepting fractional seconds will accept such values.

use chrono::{NaiveDate, NaiveTime};

let t = NaiveTime::from_hms_milli_opt(8, 59, 59, 1_000).unwrap();

let dt1 = NaiveDate::from_ymd_opt(2015, 7, 1)
    .unwrap()
    .and_hms_micro_opt(8, 59, 59, 1_000_000)
    .unwrap();

let dt2 = NaiveDate::from_ymd_opt(2015, 6, 30)
    .unwrap()
    .and_hms_nano_opt(23, 59, 59, 1_000_000_000)
    .unwrap()
    .and_utc();

Note that the leap second can happen anytime given an appropriate time zone; 2015-07-01 01:23:60 would be a proper leap second if UTC+01:24 had existed. Practically speaking, though, by the time of the first leap second on 1972-06-30, every time zone offset around the world has standardized to the 5-minute alignment.

§Date And Time Arithmetics

As a concrete example, let’s assume that 03:00:60 and 04:00:60 are leap seconds. In reality, of course, leap seconds are separated by at least 6 months. We will also use some intuitive concise notations for the explanation.

Time + TimeDelta (short for NaiveTime::overflowing_add_signed):

03:00:00 + 1s = 03:00:01.
03:00:59 + 60s = 03:01:59.
03:00:59 + 61s = 03:02:00.
03:00:59 + 1s = 03:01:00.
03:00:60 + 1s = 03:01:00. Note that the sum is identical to the previous.
03:00:60 + 60s = 03:01:59.
03:00:60 + 61s = 03:02:00.
03:00:60.1 + 0.8s = 03:00:60.9.

Time - TimeDelta (short for NaiveTime::overflowing_sub_signed):

03:00:00 - 1s = 02:59:59.
03:01:00 - 1s = 03:00:59.
03:01:00 - 60s = 03:00:00.
03:00:60 - 60s = 03:00:00. Note that the result is identical to the previous.
03:00:60.7 - 0.4s = 03:00:60.3.
03:00:60.7 - 0.9s = 03:00:59.8.

Time - Time (short for NaiveTime::signed_duration_since):

04:00:00 - 03:00:00 = 3600s.
03:01:00 - 03:00:00 = 60s.
03:00:60 - 03:00:00 = 60s. Note that the difference is identical to the previous.
03:00:60.6 - 03:00:59.4 = 1.2s.
03:01:00 - 03:00:59.8 = 0.2s.
03:01:00 - 03:00:60.5 = 0.5s. Note that the difference is larger than the previous, even though the leap second clearly follows the previous whole second.
04:00:60.9 - 03:00:60.1 = (04:00:60.9 - 04:00:00) + (04:00:00 - 03:01:00) + (03:01:00 - 03:00:60.1) = 60.9s + 3540s + 0.9s = 3601.8s.

In general,

Time + TimeDelta unconditionally equals to TimeDelta + Time.
Time - TimeDelta unconditionally equals to Time + (-TimeDelta).
Time1 - Time2 unconditionally equals to -(Time2 - Time1).
Associativity does not generally hold, because (Time + TimeDelta1) - TimeDelta2 no longer equals to Time + (TimeDelta1 - TimeDelta2) for two positive durations.
- As a special case, (Time + TimeDelta) - TimeDelta also does not equal to Time.
- If you can assume that all durations have the same sign, however, then the associativity holds: (Time + TimeDelta1) + TimeDelta2 equals to Time + (TimeDelta1 + TimeDelta2) for two positive durations.

§Reading And Writing Leap Seconds

The “typical” leap seconds on the minute boundary are correctly handled both in the formatting and parsing. The leap second in the human-readable representation will be represented as the second part being 60, as required by ISO 8601.

use chrono::NaiveDate;

let dt = NaiveDate::from_ymd_opt(2015, 6, 30)
    .unwrap()
    .and_hms_milli_opt(23, 59, 59, 1_000)
    .unwrap()
    .and_utc();
assert_eq!(format!("{:?}", dt), "2015-06-30T23:59:60Z");

There are hypothetical leap seconds not on the minute boundary nevertheless supported by Chrono. They are allowed for the sake of completeness and consistency; there were several “exotic” time zone offsets with fractional minutes prior to UTC after all. For such cases the human-readable representation is ambiguous and would be read back to the next non-leap second.

A NaiveTime with a leap second that is not on a minute boundary can only be created from a DateTime with fractional minutes as offset, or using Timelike::with_nanosecond().

use chrono::{FixedOffset, NaiveDate, TimeZone};

let paramaribo_pre1945 = FixedOffset::east_opt(-13236).unwrap(); // -03:40:36
let leap_sec_2015 =
    NaiveDate::from_ymd_opt(2015, 6, 30).unwrap().and_hms_milli_opt(23, 59, 59, 1_000).unwrap();
let dt1 = paramaribo_pre1945.from_utc_datetime(&leap_sec_2015);
assert_eq!(format!("{:?}", dt1), "2015-06-30T20:19:24-03:40:36");
assert_eq!(format!("{:?}", dt1.time()), "20:19:24");

let next_sec = NaiveDate::from_ymd_opt(2015, 7, 1).unwrap().and_hms_opt(0, 0, 0).unwrap();
let dt2 = paramaribo_pre1945.from_utc_datetime(&next_sec);
assert_eq!(format!("{:?}", dt2), "2015-06-30T20:19:24-03:40:36");
assert_eq!(format!("{:?}", dt2.time()), "20:19:24");

assert!(dt1.time() != dt2.time());
assert!(dt1.time().to_string() == dt2.time().to_string());

Since Chrono alone cannot determine any existence of leap seconds, there is absolutely no guarantee that the leap second read has actually happened.

Struct TimeCopy item path

§Leap Second Handling

§Representing Leap Seconds

§Date And Time Arithmetics

§Reading And Writing Leap Seconds

Implementations§

impl NaiveTime

pub const MIN: NaiveTime = _

pub const fn from_hms(hour: u32, min: u32, sec: u32) -> NaiveTime

§Panics

pub const fn from_hms_opt(hour: u32, min: u32, sec: u32) -> Option<NaiveTime>

§Errors

§Example

pub const fn from_hms_milli( hour: u32, min: u32, sec: u32, milli: u32, ) -> NaiveTime

§Panics

pub const fn from_hms_milli_opt( hour: u32, min: u32, sec: u32, milli: u32, ) -> Option<NaiveTime>

§Errors

§Example

pub const fn from_hms_micro( hour: u32, min: u32, sec: u32, micro: u32, ) -> NaiveTime

§Panics

pub const fn from_hms_micro_opt( hour: u32, min: u32, sec: u32, micro: u32, ) -> Option<NaiveTime>

§Errors

§Example

pub const fn from_hms_nano( hour: u32, min: u32, sec: u32, nano: u32, ) -> NaiveTime

§Panics

pub const fn from_hms_nano_opt( hour: u32, min: u32, sec: u32, nano: u32, ) -> Option<NaiveTime>

§Errors

§Example

pub const fn from_num_seconds_from_midnight(secs: u32, nano: u32) -> NaiveTime

§Panics

pub const fn from_num_seconds_from_midnight_opt( secs: u32, nano: u32, ) -> Option<NaiveTime>

§Errors

§Example

pub fn parse_from_str(s: &str, fmt: &str) -> Result<NaiveTime, ParseError>

§Example

pub fn parse_and_remainder<'a>( s: &'a str, fmt: &str, ) -> Result<(NaiveTime, &'a str), ParseError>

§Example

pub const fn overflowing_add_signed(&self, rhs: TimeDelta) -> (NaiveTime, i64)

§Example

pub const fn overflowing_sub_signed(&self, rhs: TimeDelta) -> (NaiveTime, i64)

§Example

pub const fn signed_duration_since(self, rhs: NaiveTime) -> TimeDelta

§Example

pub fn format_with_items<'a, I, B>(&self, items: I) -> DelayedFormat<I>where I: Iterator<Item = B> + Clone, B: Borrow<Item<'a>>,

§Example

pub fn format<'a>(&self, fmt: &'a str) -> DelayedFormat<StrftimeItems<'a>>

§Example

Trait Implementations§

impl Add<Duration> for NaiveTime

type Output = NaiveTime

fn add(self, rhs: Duration) -> NaiveTime

impl Add<FixedOffset> for NaiveTime

type Output = NaiveTime

fn add(self, rhs: FixedOffset) -> NaiveTime

impl Add<TimeDelta> for NaiveTime

§Example

type Output = NaiveTime

fn add(self, rhs: TimeDelta) -> NaiveTime

impl AddAssign<Duration> for NaiveTime

fn add_assign(&mut self, rhs: Duration)

impl AddAssign<TimeDelta> for NaiveTime

fn add_assign(&mut self, rhs: TimeDelta)

impl Clone for NaiveTime

fn clone(&self) -> NaiveTime

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

impl Debug for NaiveTime

§Example

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

impl<'r> Decode<'r, MySql> for NaiveTime

§Errors

fn decode( value: MySqlValueRef<'r>, ) -> Result<NaiveTime, Box<dyn Error + Sync + Send>>

impl<'r> Decode<'r, Postgres> for NaiveTime

fn decode( value: PgValueRef<'r>, ) -> Result<NaiveTime, Box<dyn Error + Sync + Send>>

impl<'r> Decode<'r, Sqlite> for NaiveTime

fn decode( value: SqliteValueRef<'r>, ) -> Result<NaiveTime, Box<dyn Error + Sync + Send>>

impl Default for NaiveTime

§Example

fn default() -> NaiveTime

impl<'de> Deserialize<'de> for NaiveTime

fn deserialize<D>( deserializer: D, ) -> Result<NaiveTime, <D as Deserializer<'de>>::Error>where D: Deserializer<'de>,

Struct Time

pub fn format_with_items<'a, I, B>(&self, items: I) -> DelayedFormat<I>
where I: Iterator<Item = B> + Clone, B: Borrow<Item<'a>>,

fn deserialize<D>( deserializer: D, ) -> Result<NaiveTime, <D as Deserializer<'de>>::Error>
where D: Deserializer<'de>,

fn encode( self, buf: &mut <DB as Database>::ArgumentBuffer<'q>, ) -> Result<IsNull, Box<dyn Error + Sync + Send>>
where Self: Sized,

fn encode( self, buf: &mut <DB as Database>::ArgumentBuffer<'q>, ) -> Result<IsNull, Box<dyn Error + Sync + Send>>
where Self: Sized,

fn encode( self, buf: &mut <DB as Database>::ArgumentBuffer<'q>, ) -> Result<IsNull, Box<dyn Error + Sync + Send>>
where Self: Sized,

fn hash<H>(&self, state: &mut H)
where __H: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

fn max(self, other: Self) -> Self
where Self: Sized,

fn min(self, other: Self) -> Self
where Self: Sized,

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized,

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>
where S: Serializer,