Struct chrono::naive::time::NaiveTime

pub struct NaiveTime {
    // some fields omitted
}

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

Leap second WHAT?

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 time arithmetics will ignore any possible leap second(s) except when the operand were actually a leap second. The leap second is indicated via fractional seconds more than 1 second, so values like NaiveTime::from_hms_milli(23, 56, 4, 1_005) are allowed; that value would mean 5ms after the beginning of a leap second following 23:56:04. Parsing and formatting will correctly handle times that look like leap seconds, and you can then conveniently ignore leap seconds if you are not prepared for them.

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 0.2 does not provide such implementation, but it is planned for 0.3.

Methods

impl NaiveTime

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

Makes a new NaiveTime from hour, minute and second.

No leap second is allowed here; use NaiveTime::from_hms_* methods with a subsecond parameter instead.

Panics on invalid hour, minute and/or second.

Example

use chrono::{NaiveTime, Timelike};

let t = NaiveTime::from_hms(23, 56, 4);
assert_eq!(t.hour(), 23);
assert_eq!(t.minute(), 56);
assert_eq!(t.second(), 4);
assert_eq!(t.nanosecond(), 0);

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

Makes a new NaiveTime from hour, minute and second.

No leap second is allowed here; use NaiveTime::from_hms_*_opt methods with a subsecond parameter instead.

Returns None on invalid hour, minute and/or second.

Example

use chrono::NaiveTime;

let hms = |h,m,s| NaiveTime::from_hms_opt(h, m, s);
assert!(hms(0, 0, 0).is_some());
assert!(hms(23, 59, 59).is_some());
assert!(hms(24, 0, 0).is_none());
assert!(hms(23, 60, 0).is_none());
assert!(hms(23, 59, 60).is_none());

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

Makes a new NaiveTime from hour, minute, second and millisecond.

The millisecond part can exceed 1,000 in order to represent the leap second.

Panics on invalid hour, minute, second and/or millisecond.

Example

use chrono::{NaiveTime, Timelike};

let t = NaiveTime::from_hms_milli(23, 56, 4, 12);
assert_eq!(t.hour(), 23);
assert_eq!(t.minute(), 56);
assert_eq!(t.second(), 4);
assert_eq!(t.nanosecond(), 12_000_000);

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

Makes a new NaiveTime from hour, minute, second and millisecond.

The millisecond part can exceed 1,000 in order to represent the leap second.

Returns None on invalid hour, minute, second and/or millisecond.

Example

use chrono::NaiveTime;

let hmsm = |h,m,s,milli| NaiveTime::from_hms_milli_opt(h, m, s, milli);
assert!(hmsm(0, 0, 0, 0).is_some());
assert!(hmsm(23, 59, 59, 999).is_some());
assert!(hmsm(23, 59, 59, 1_999).is_some()); // a leap second following 23:59:59
assert!(hmsm(24, 0, 0, 0).is_none());
assert!(hmsm(23, 60, 0, 0).is_none());
assert!(hmsm(23, 59, 60, 0).is_none());
assert!(hmsm(23, 59, 59, 2_000).is_none());

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

Makes a new NaiveTime from hour, minute, second and microsecond.

The microsecond part can exceed 1,000,000 in order to represent the leap second.

Panics on invalid hour, minute, second and/or microsecond.

Example

use chrono::{NaiveTime, Timelike};

let t = NaiveTime::from_hms_micro(23, 56, 4, 12_345);
assert_eq!(t.hour(), 23);
assert_eq!(t.minute(), 56);
assert_eq!(t.second(), 4);
assert_eq!(t.nanosecond(), 12_345_000);

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

Makes a new NaiveTime from hour, minute, second and microsecond.

The microsecond part can exceed 1,000,000 in order to represent the leap second.

Returns None on invalid hour, minute, second and/or microsecond.

Example

use chrono::NaiveTime;

let hmsu = |h,m,s,micro| NaiveTime::from_hms_micro_opt(h, m, s, micro);
assert!(hmsu(0, 0, 0, 0).is_some());
assert!(hmsu(23, 59, 59, 999_999).is_some());
assert!(hmsu(23, 59, 59, 1_999_999).is_some()); // a leap second following 23:59:59
assert!(hmsu(24, 0, 0, 0).is_none());
assert!(hmsu(23, 60, 0, 0).is_none());
assert!(hmsu(23, 59, 60, 0).is_none());
assert!(hmsu(23, 59, 59, 2_000_000).is_none());

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

Makes a new NaiveTime from hour, minute, second and nanosecond.

The nanosecond part can exceed 1,000,000,000 in order to represent the leap second.

Panics on invalid hour, minute, second and/or nanosecond.

Example

use chrono::{NaiveTime, Timelike};

let t = NaiveTime::from_hms_nano(23, 56, 4, 12_345_678);
assert_eq!(t.hour(), 23);
assert_eq!(t.minute(), 56);
assert_eq!(t.second(), 4);
assert_eq!(t.nanosecond(), 12_345_678);

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

Makes a new NaiveTime from hour, minute, second and nanosecond.

The nanosecond part can exceed 1,000,000,000 in order to represent the leap second.

Returns None on invalid hour, minute, second and/or nanosecond.

Example

use chrono::NaiveTime;

let hmsn = |h,m,s,nano| NaiveTime::from_hms_nano_opt(h, m, s, nano);
assert!(hmsn(0, 0, 0, 0).is_some());
assert!(hmsn(23, 59, 59, 999_999_999).is_some());
assert!(hmsn(23, 59, 59, 1_999_999_999).is_some()); // a leap second following 23:59:59
assert!(hmsn(24, 0, 0, 0).is_none());
assert!(hmsn(23, 60, 0, 0).is_none());
assert!(hmsn(23, 59, 60, 0).is_none());
assert!(hmsn(23, 59, 59, 2_000_000_000).is_none());

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

Makes a new NaiveTime from the number of seconds since midnight and nanosecond.

The nanosecond part can exceed 1,000,000,000 in order to represent the leap second.

Panics on invalid number of seconds and/or nanosecond.

Example

use chrono::{NaiveTime, Timelike};

let t = NaiveTime::from_num_seconds_from_midnight(86164, 12_345_678);
assert_eq!(t.hour(), 23);
assert_eq!(t.minute(), 56);
assert_eq!(t.second(), 4);
assert_eq!(t.nanosecond(), 12_345_678);

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

Makes a new NaiveTime from the number of seconds since midnight and nanosecond.

The nanosecond part can exceed 1,000,000,000 in order to represent the leap second.

Returns None on invalid number of seconds and/or nanosecond.

Example

use chrono::NaiveTime;

let secs = |secs,nano| NaiveTime::from_num_seconds_from_midnight_opt(secs, nano);
assert!(secs(0, 0).is_some());
assert!(secs(86399, 999_999_999).is_some());
assert!(secs(86399, 1_999_999_999).is_some()); // a leap second following 23:59:59
assert!(secs(86400, 0).is_none());
assert!(secs(86399, 2_000_000_000).is_none());

fn parse_from_str(s: &str, fmt: &str) -> ParseResult<NaiveTime>

Parses a string with the specified format string and returns a new NaiveTime. See the format::strftime module on the supported escape sequences.

Example

use chrono::NaiveTime;

assert_eq!(NaiveTime::parse_from_str("23:56:04", "%H:%M:%S"),
           Ok(NaiveTime::from_hms(23, 56, 4)));
assert_eq!(NaiveTime::parse_from_str("pm012345.6789", "%p%I%M%S%.f"),
           Ok(NaiveTime::from_hms_micro(13, 23, 45, 678_900)));

Date and offset is ignored for the purpose of parsing.

assert_eq!(NaiveTime::parse_from_str("2014-5-17T12:34:56+09:30", "%Y-%m-%dT%H:%M:%S%z"),
           Ok(NaiveTime::from_hms(12, 34, 56)));

Leap seconds are correctly handled by treating any time of the form hh:mm:60 as a leap second. (This equally applies to the formatting, so the round trip is possible.)

assert_eq!(NaiveTime::parse_from_str("08:59:60.123", "%H:%M:%S%.f"),
           Ok(NaiveTime::from_hms_milli(8, 59, 59, 1_123)));

Missing seconds are assumed to be zero, but out-of-bound times or insufficient fields are errors otherwise.

assert_eq!(NaiveTime::parse_from_str("7:15", "%H:%M"),
           Ok(NaiveTime::from_hms(7, 15, 0)));

assert!(NaiveTime::parse_from_str("04m33s", "%Mm%Ss").is_err());
assert!(NaiveTime::parse_from_str("12", "%H").is_err());
assert!(NaiveTime::parse_from_str("17:60", "%H:%M").is_err());
assert!(NaiveTime::parse_from_str("24:00:00", "%H:%M:%S").is_err());

All parsed fields should be consistent to each other, otherwise it's an error. Here %H is for 24-hour clocks, unlike %I, and thus can be independently determined without AM/PM.

assert!(NaiveTime::parse_from_str("13:07 AM", "%H:%M %p").is_err());

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

Formats the time with the specified formatting items. Otherwise it is same to the ordinary format method.

The Iterator of items should be Cloneable, since the resulting DelayedFormat value may be formatted multiple times.

Example

use chrono::NaiveTime;
use chrono::format::strftime::StrftimeItems;

let fmt = StrftimeItems::new("%H:%M:%S");
let t = NaiveTime::from_hms(23, 56, 4);
assert_eq!(t.format_with_items(fmt.clone()).to_string(), "23:56:04");
assert_eq!(t.format("%H:%M:%S").to_string(), "23:56:04");

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

Formats the time with the specified format string. See the format::strftime module on the supported escape sequences.

This returns a DelayedFormat, which gets converted to a string only when actual formatting happens. You may use the to_string method to get a String, or just feed it into print! and other formatting macros. (In this way it avoids the redundant memory allocation.)

A wrong format string does not issue an error immediately. Rather, converting or formatting the DelayedFormat fails. You are recommended to immediately use DelayedFormat for this reason.

Example

use chrono::NaiveTime;

let t = NaiveTime::from_hms_nano(23, 56, 4, 12_345_678);
assert_eq!(t.format("%H:%M:%S").to_string(), "23:56:04");
assert_eq!(t.format("%H:%M:%S%.6f").to_string(), "23:56:04.012345");
assert_eq!(t.format("%-I:%M %p").to_string(), "11:56 PM");

Trait Implementations

impl Clone for NaiveTime

fn clone(&self) -> NaiveTime

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Copy for NaiveTime

impl Ord for NaiveTime

fn cmp(&self, __arg_0: &NaiveTime) -> Ordering

This method returns an Ordering between self and other.

impl PartialOrd for NaiveTime

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

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

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

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

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

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

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

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

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

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

impl Eq for NaiveTime

impl PartialEq for NaiveTime

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

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

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

This method tests for !=.

impl Timelike for NaiveTime

fn hour(&self) -> u32

Returns the hour number from 0 to 23.

fn minute(&self) -> u32

Returns the minute number from 0 to 59.

fn second(&self) -> u32

Returns the second number from 0 to 59.

fn nanosecond(&self) -> u32

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.

fn with_hour(&self, hour: u32) -> Option<NaiveTime>

Makes a new value with the hour number changed.

fn with_minute(&self, min: u32) -> Option<NaiveTime>

Makes a new value with the minute number changed.

fn with_second(&self, sec: u32) -> Option<NaiveTime>

Makes a new value with the second number changed.

fn with_nanosecond(&self, nano: u32) -> Option<NaiveTime>

Makes a new value with nanoseconds since the whole non-leap second changed.

fn num_seconds_from_midnight(&self) -> u32

Returns the number of non-leap seconds past the last midnight.

fn hour12(&self) -> (bool, u32)

Returns the hour number from 1 to 12 with a boolean flag, which is false for AM and true for PM.

impl Hash for NaiveTime

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

Feeds this value into the state given, updating the hasher as necessary.

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

Feeds a slice of this type into the state provided.

impl Add<Duration> for NaiveTime

type Output = NaiveTime

The resulting type after applying the + operator

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

The method for the + operator

impl Sub<NaiveTime> for NaiveTime

type Output = Duration

The resulting type after applying the - operator

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

The method for the - operator

impl Sub<Duration> for NaiveTime

type Output = NaiveTime

The resulting type after applying the - operator

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

The method for the - operator

impl Debug for NaiveTime

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

Formats the value using the given formatter.

impl Display for NaiveTime

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

Formats the value using the given formatter.

impl FromStr for NaiveTime

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> ParseResult<NaiveTime>

Parses a string s to return a value of this type.