Struct chrono::naive::time::NaiveTime
[−]
[src]
pub struct NaiveTime {
// some fields omitted
}ISO 8601 time without timezone. Allows for the nanosecond precision and optional leap second representation.
Chrono has a notable policy on the leap second handling, designed to be maximally useful for typical users.
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 Timelike for NaiveTime
fn hour(&self) -> u32
Returns the hour number from 0 to 23.
Example
use chrono::{NaiveTime, Timelike}; assert_eq!(NaiveTime::from_hms(0, 0, 0).hour(), 0); assert_eq!(NaiveTime::from_hms_nano(23, 56, 4, 12_345_678).hour(), 23);
fn minute(&self) -> u32
Returns the minute number from 0 to 59.
Example
use chrono::{NaiveTime, Timelike}; assert_eq!(NaiveTime::from_hms(0, 0, 0).minute(), 0); assert_eq!(NaiveTime::from_hms_nano(23, 56, 4, 12_345_678).minute(), 56);
fn second(&self) -> u32
Returns the second number from 0 to 59.
Example
use chrono::{NaiveTime, Timelike}; assert_eq!(NaiveTime::from_hms(0, 0, 0).second(), 0); assert_eq!(NaiveTime::from_hms_nano(23, 56, 4, 12_345_678).second(), 4);
This method never returns 60 even when it is a leap second. (Why?) Use the proper formatting method to get a human-readable representation.
let leap = NaiveTime::from_hms_milli(23, 59, 59, 1_000); assert_eq!(leap.second(), 59); assert_eq!(leap.format("%H:%M:%S").to_string(), "23:59:60");
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.
Example
use chrono::{NaiveTime, Timelike}; assert_eq!(NaiveTime::from_hms(0, 0, 0).nanosecond(), 0); assert_eq!(NaiveTime::from_hms_nano(23, 56, 4, 12_345_678).nanosecond(), 12_345_678);
Leap seconds may have seemingly out-of-range return values.
You can reduce the range with time.nanosecond() % 1_000_000_000, or
use the proper formatting method to get a human-readable representation.
let leap = NaiveTime::from_hms_milli(23, 59, 59, 1_000); assert_eq!(leap.nanosecond(), 1_000_000_000); assert_eq!(leap.format("%H:%M:%S%.9f").to_string(), "23:59:60.000000000");
fn with_hour(&self, hour: u32) -> Option<NaiveTime>
Makes a new NaiveTime with the hour number changed.
Returns None when the resulting NaiveTime would be invalid.
Example
use chrono::{NaiveTime, Timelike}; let dt = NaiveTime::from_hms_nano(23, 56, 4, 12_345_678); assert_eq!(dt.with_hour(7), Some(NaiveTime::from_hms_nano(7, 56, 4, 12_345_678))); assert_eq!(dt.with_hour(24), None);
fn with_minute(&self, min: u32) -> Option<NaiveTime>
Makes a new NaiveTime with the minute number changed.
Returns None when the resulting NaiveTime would be invalid.
Example
use chrono::{NaiveTime, Timelike}; let dt = NaiveTime::from_hms_nano(23, 56, 4, 12_345_678); assert_eq!(dt.with_minute(45), Some(NaiveTime::from_hms_nano(23, 45, 4, 12_345_678))); assert_eq!(dt.with_minute(60), None);
fn with_second(&self, sec: u32) -> Option<NaiveTime>
Makes a new NaiveTime with the second number changed.
Returns None when the resulting NaiveTime would be invalid.
As with the second method,
the input range is restricted to 0 through 59.
Example
use chrono::{NaiveTime, Timelike}; let dt = NaiveTime::from_hms_nano(23, 56, 4, 12_345_678); assert_eq!(dt.with_second(17), Some(NaiveTime::from_hms_nano(23, 56, 17, 12_345_678))); assert_eq!(dt.with_second(60), None);
fn with_nanosecond(&self, nano: u32) -> Option<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 method,
the input range can exceed 1,000,000,000 for leap seconds.
Example
use chrono::{NaiveTime, Timelike}; let dt = NaiveTime::from_hms_nano(23, 56, 4, 12_345_678); assert_eq!(dt.with_nanosecond(333_333_333), Some(NaiveTime::from_hms_nano(23, 56, 4, 333_333_333))); assert_eq!(dt.with_nanosecond(2_000_000_000), None);
Leap seconds can theoretically follow any whole second. The following would be a proper leap second at the time zone offset of UTC-00:03:57 (there are several historical examples comparable to this "non-sense" offset), and therefore is allowed.
assert_eq!(dt.with_nanosecond(1_333_333_333), Some(NaiveTime::from_hms_nano(23, 56, 4, 1_333_333_333)));
fn num_seconds_from_midnight(&self) -> u32
Returns the number of non-leap seconds past the last midnight.
Example
use chrono::{NaiveTime, Timelike}; assert_eq!(NaiveTime::from_hms(1, 2, 3).num_seconds_from_midnight(), 3723); assert_eq!(NaiveTime::from_hms_nano(23, 56, 4, 12_345_678).num_seconds_from_midnight(), 86164); assert_eq!(NaiveTime::from_hms_milli(23, 59, 59, 1_000).num_seconds_from_midnight(), 86399);
fn hour12(&self) -> (bool, u32)
impl Hash for NaiveTime
NaiveTime 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.)