Struct Time

pub struct Time { /* private fields */ }

Implementation of Ruby Time, a timezone-aware datetime, based on tz-rs and tzdb.

Time is represented as:

• a 64-bit signed integer of seconds since January 1, 1970 UTC (a Unix timestamp).
• an unsigned 32-bit integer of nanoseconds since the timestamp.
• An offset from UTC. See Offset for the types of supported offsets.

This data structure allows representing roughly 584 billion years. Unlike MRI, there is no promotion to Bignum or Rational. The maximum granularity of a Time object is nanoseconds.

Examples

// Create a Time to the current system clock with local offset
let time = Time::now()?;
assert!(!time.is_utc());
println!("{}", time.is_sunday());

let time = Time::now()?;
let one_hour_ago: Time = time.checked_sub_u64(60 * 60)?;
assert_eq!(time.to_int() - 3600, one_hour_ago.to_int());
assert_eq!(time.nanoseconds(), one_hour_ago.nanoseconds());

Implementations

impl Time

pub fn local( year: i32, month: u8, month_day: u8, hour: u8, minute: u8, second: u8, nanoseconds: u32, ) -> Result<Self>

Returns a Time based on the provided values in the local timezone.

Can be used to implement Ruby Time#local, Time#mktime.

Errors

Can produce a TimeError, generally when provided values are out of range.

pub fn utc( year: i32, month: u8, month_day: u8, hour: u8, minute: u8, second: u8, nanoseconds: u32, ) -> Result<Self>

Returns a Time based on the provided values in UTC.

Can be used to implement Ruby Time#utc, Time#gm.

Errors

Can produce a TimeError, generally when provided values are out of range.

impl Time

pub fn strftime(&self, format: &[u8]) -> Result<Vec<u8>, Error>

Formats time according to the directives in the given format string.

Can be used to implement Time#strftime. The resulting byte string will have the same encoding as the format byte slice.

Examples

let now = Time::utc(2022, 05, 26, 13, 16, 22, 276)?;
assert_eq!(
    now.strftime("Today is %c 🎉".as_bytes())?,
    "Today is Thu May 26 13:16:22 2022 🎉".as_bytes(),
);

Errors

Can return strftime::Error if formatting fails. See strftime::bytes::strftime for more details.

pub fn to_array(self) -> ToA

Serialize a Time into its components as a ToA.

ToA stores a Time as a ten-element struct of time components: [sec, min, hour, day, month, year, wday, yday, isdst, zone].

The ordering of the properties is important for the Ruby Time#to_a API.

Can be used to implement Time#to_a.

Examples

let now = Time::now()?;
let to_array = now.to_array();
assert_eq!(to_array.sec, now.second());
assert_eq!(to_array.wday, now.day_of_week());

impl Time

pub fn round(&self, ndigits: u32) -> Self

Rounds sub seconds to a given precision in decimal digits (0 digits by default). It returns a new Time object. ndigits should be zero or a positive integer.

Can be used to implement Time#round.

Examples

let now = Time::local(2010, 3, 30, 5, 43, 25, 123456789)?;
let rounded = now.round(5);
assert_eq!(now.utc_offset(), rounded.utc_offset());
assert_eq!(123460000, rounded.nanoseconds());

impl Time

pub fn checked_add(self, duration: Duration) -> Result<Self, TimeError>

Addition — Adds some duration to time and returns that value as a new Time object.

Errors

If this function attempts to overflow the the number of seconds as an i64 then a TimeError will be returned.

pub fn checked_add_i64(&self, seconds: i64) -> Result<Self, TimeError>

Addition — Adds some i64 to time and returns that value as a new Time object.

Errors

If this function attempts to overflow the the number of seconds as an i64 then a TimeError will be returned.

pub fn checked_add_u64(&self, seconds: u64) -> Result<Self, TimeError>

Addition — Adds some u64 to time and returns that value as a new Time object.

Errors

If this function attempts to overflow the the number of seconds as an i64 then a TimeError will be returned.

pub fn checked_add_f64(&self, seconds: f64) -> Result<Self, TimeError>

Addition — Adds some f64 fraction seconds to time and returns that value as a new Time object.

Errors

If this function attempts to overflow the the number of seconds as an i64 then a TimeError will be returned.

impl Time

pub fn checked_sub(self, duration: Duration) -> Result<Self, TimeError>

Subtraction — Subtracts the given duration from time and returns that value as a new Time object.

Errors

If this function attempts to overflow the the number of seconds as an i64 then a TimeError will be returned.

pub fn checked_sub_i64(self, seconds: i64) -> Result<Self, TimeError>

Subtraction — Subtracts the given i64 from time and returns that value as a new Time object.

Errors

If this function attempts to overflow the the number of seconds as an i64 then a TimeError will be returned.

pub fn checked_sub_u64(self, seconds: u64) -> Result<Self, TimeError>

Subtraction — Subtracts the given u64 from time and returns that value as a new Time object.

Errors

If this function attempts to overflow the the number of seconds as an i64 then a TimeError will be returned.

pub fn checked_sub_f64(self, seconds: f64) -> Result<Self, TimeError>

Subtraction — Subtracts the given f64 as fraction seconds from time and returns that value as a new Time object.

Errors

If this function attempts to overflow the the number of seconds as an i64 then a TimeError will be returned.

impl Time

pub fn nanoseconds(&self) -> u32

Returns the number of nanoseconds for time.

The lowest digits of to_f and nsec are different because IEEE 754 double is not accurate enough to represent the exact number of nanoseconds since the Epoch.

Can be used to implement Time#nsec and Time#tv_nsec.

Examples

let t = Time::utc(2022, 1, 1, 12, 0, 0, 1)?;
let t_float = t.to_float();
let float_nanos = (t_float - t_float.round()) * NANOS_IN_SECOND as f64;
assert_ne!(float_nanos, 1f64);
assert_eq!(t.nanoseconds(), 1);

pub fn microseconds(&self) -> u32

Returns the number of microseconds for time.

Can be used to implement Time#usec and Time#tv_usec.

Examples

let t = Time::utc(2022, 1, 1, 12, 0, 0, 1 * MICROS_IN_NANO)?;
assert_eq!(t.microseconds(), 1);

pub fn second(&self) -> u8

Returns the second of the minute 0..=60 for time.

Seconds range from zero to 60 to allow the system to inject leap seconds.

Can be used to implement Time#sec.

Examples

let now = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
let second_of_minute = now.second();
assert_eq!(second_of_minute, 56);

pub fn minute(&self) -> u8

Returns the minute of the hour 0..=59 for time.

Can be used to implement Time#min.

Examples

let now = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
let minute_of_hour = now.minute();
assert_eq!(minute_of_hour, 34);

pub fn hour(&self) -> u8

Returns the hour of the day 0..=23 for time.

Can be used to implement Time#hour.

Examples

let now = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
let hour_of_day = now.hour();
assert_eq!(hour_of_day, 12);

pub fn day(&self) -> u8

Returns the day of the month 1..=n for time.

Can be used to implement Time#day and Time#mday.

Examples

let now = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
let day_of_month = now.day();
assert_eq!(day_of_month, 8);

pub fn month(&self) -> u8

Returns the month of the year 1..=12 for time.

Can be used to implement Time#mon and Time#month.

Examples

let now = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
let month_of_year = now.month();
assert_eq!(month_of_year, 7);

pub fn year(&self) -> i32

Returns the year for time (including the century).

Can be used to implement Time#year.

Examples

let now = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
assert_eq!(now.year(), 2022);

pub fn time_zone(&self) -> &str

Returns the name of the time zone as a string.

Note: For some offset variants, UTC may return an empty string from this method due to the UTC LocaleTimeType being constructed with None, which is later coerced into an empty string.

Examples

let now_utc = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
assert_eq!("UTC", now_utc.time_zone());

pub fn is_utc(&self) -> bool

Returns true if the time zone is UTC.

Can be used to implement Time#utc? and Time#gmt?.

Examples

let now_utc = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
assert!(now_utc.is_utc());

pub fn utc_offset(&self) -> i32

Returns the offset in seconds between the timezone of time and UTC.

Can be used to implement Time#utc_offset and Time#gmt_offset.

Examples

let now = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
assert_eq!(now.utc_offset(), 0);

pub fn is_dst(&self) -> bool

Returns true if time occurs during Daylight Saving Time in its time zone.

Can be used to implement Time#dst? and Time#isdst.

Examples

use tzdb::time_zone::{europe::AMSTERDAM, pacific::AUCKLAND};
let now_ams = Time::new(2022, 5, 18, 16, 0, 0, 0, Offset::from(AMSTERDAM))?;
assert!(now_ams.is_dst());
let now_auckland = Time::new(2022, 5, 18, 16, 0, 0, 0, Offset::from(AUCKLAND))?;
assert!(!now_auckland.is_dst());

pub fn day_of_week(&self) -> u8

Returns an integer representing the day of the week, 0..=6, with Sunday == 0.

Can be used to implement Time#wday.

Examples

let now = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
assert_eq!(now.day_of_week(), 5);

pub fn is_sunday(&self) -> bool

Returns true if time represents Sunday.

Can be used to implement Time#sunday?.

Examples

use spinoso_time::tzrs::Time;
let now = Time::utc(1970, 1, 4, 0, 0, 0, 0)?;
assert!(now.is_sunday());

pub fn is_monday(&self) -> bool

Returns true if time represents Monday.

Can be used to implement Time#monday?.

Examples

use spinoso_time::tzrs::Time;
let now = Time::utc(1970, 1, 5, 0, 0, 0, 0)?;
assert!(now.is_monday());

pub fn is_tuesday(&self) -> bool

Returns true if time represents Tuesday.

Can be used to implement Time#tuesday?.

Examples

use spinoso_time::tzrs::Time;
let now = Time::utc(1970, 1, 6, 0, 0, 0, 0)?;
assert!(now.is_tuesday());

pub fn is_wednesday(&self) -> bool

Returns true if time represents Wednesday.

Can be used to implement Time#wednesday?.

Examples

use spinoso_time::tzrs::Time;
let now = Time::utc(1970, 1, 7, 0, 0, 0, 0)?;
assert!(now.is_wednesday());

pub fn is_thursday(&self) -> bool

Returns true if time represents Thursday.

Can be used to implement Time#thursday?.

Examples

use spinoso_time::tzrs::Time;
let now = Time::utc(1970, 1, 1, 0, 0, 0, 0)?;
assert!(now.is_thursday());

pub fn is_friday(&self) -> bool

Returns true if time represents Friday.

Can be used to implement Time#friday?.

Examples

let now = Time::utc(1970, 1, 2, 0, 0, 0, 0)?;
assert!(now.is_friday());

pub fn is_saturday(&self) -> bool

Returns true if time represents Saturday.

Can be used to implement Time#saturday?.

Examples

use spinoso_time::tzrs::Time;
let now = Time::utc(1970, 1, 3, 0, 0, 0, 0)?;
assert!(now.is_saturday());

pub fn day_of_year(&self) -> u16

Returns an integer representing the day of the year, 1..=366.

Can be used to implement Time#yday.

Examples

let now = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
assert_eq!(now.day_of_year(), 189);

impl Time

pub fn to_offset(&self, offset: Offset) -> Result<Self>

Returns a new Time object representing time based on the provided offset.

Can be used to implement Time#getlocal with a string/number parameter.

Examples

use tzdb::time_zone::europe::AMSTERDAM;
let ams_offset = Offset::from(AMSTERDAM);
let now_utc = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
let now_ams = now_utc.to_offset(ams_offset)?;
assert!(!now_ams.is_utc());

Errors

Can produce a TimeError, might come as a result of an offset causing the unix_time to exceed i64::MAX.

pub fn to_utc(&self) -> Result<Self>

Returns a new time in UTC.

Can be used to implement Time#getutc and Time#getgm.

Examples

let now_local = Time::now()?;
let now_utc = now_local.to_utc()?;
assert_eq!(now_utc.utc_offset(), 0);
assert!(now_utc.is_utc());

Errors

Can produce a TimeError, might come as a result of an offset causing the unix_time to exceed i64::MAX.

pub fn to_local(&self) -> Result<Self>

Returns a new Time object representing time in local time (using the local time zone in effect for this process).

Can be used to implement Time#getlocal.

Examples

let now_utc = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
let now_local = Time::local(2022, 7, 8, 12, 34, 56, 0)?;
assert_eq!(now_utc.to_local()?.utc_offset(), now_local.utc_offset());

Errors

Can produce a TimeError, might come as a result of an offset causing the unix_time to exceed i64::MAX.

impl Time

pub fn set_offset(&mut self, offset: Offset) -> Result<()>

Converts time to the provided time zone, modifying the receiver.

Examples

let mut now = Time::utc(2022, 6, 8, 12, 0, 0, 0)?;
let gmt_plus_one = Offset::try_from(3600)?;
now.set_offset(gmt_plus_one);
assert_eq!(13, now.hour());

Errors

Can produce a TimeError, might come as a result of an offset causing the unix_time to exceed i64::MAX.

pub fn set_local(&mut self) -> Result<()>

Converts time to local time (using the local time zone in effective at the creation time of time), modifying the receiver.

Can be used to implement Time#localtime without a parameter.

Examples

let mut now = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
let now_utc_unix = now.to_int();
now.set_local();
assert!(!now.is_utc());
let now_local_unix = now.to_int();
assert_eq!(now_utc_unix, now_local_unix);

Errors

Can produce a TimeError, might come as a result of an offset causing the unix_time to exceed i64::MAX.

pub fn set_utc(&mut self) -> Result<()>

Converts time to UTC (GMT), modifying the receiver.

Can be used to implement Time#utc and Time#gmtime.

Examples

let mut now = Time::local(2022, 7, 8, 12, 34, 56, 0)?;
let now_local_unix = now.to_int();
now.set_utc();
assert!(now.is_utc());
let now_utc_unix = now.to_int();
assert_eq!(now_local_unix, now_utc_unix);

Errors

Can produce a TimeError, might come as a result of an offset causing the unix_time to exceed i64::MAX.

pub fn set_offset_from_utc(&mut self, offset: Offset) -> Result<()>

Converts time to the GMT time zone with the provided offset.

Can be used to implement Time#localtime with an offset parameter.

Examples

let mut now = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
assert!(now.is_utc());
let offset = Offset::try_from(3600)?;
now.set_offset_from_utc(offset);
assert!(!now.is_utc());
assert_eq!(now.utc_offset(), 3600);

Errors

Can produce a TimeError, might come as a result of an offset causing the unix_time to exceed i64::MAX.

impl Time

pub fn new( year: i32, month: u8, day: u8, hour: u8, minute: u8, second: u8, nanoseconds: u32, offset: Offset, ) -> Result<Self>

Returns a new Time from the given values in the provided offset.

Can be used to implement the Ruby method Time#new (using a Timezone Object).

Note: During DST transitions, a specific time can be ambiguous. This method will always pick the latest date.

Examples

let offset = Offset::try_from("+1200")?;
let t = Time::new(2022, 9, 25, 1, 30, 0, 0, offset);

Errors

Can produce a TimeError, generally when provided values are out of range.

pub fn now() -> Result<Self>

Returns a Time with the current time in the System Timezone.

Can be used to implement the Ruby method Time#now.

Examples

let now = Time::now()?;

Errors

Can produce a TimeError, however these should never been seen in regular usage.

pub fn with_timespec_and_offset( seconds: i64, nanoseconds: u32, offset: Offset, ) -> Result<Self>

Returns a Time in the given timezone with the number of seconds and nanoseconds since the Epoch in the specified timezone.

Can be used to implement the Ruby method Time#at.

Examples

let offset = Offset::utc();
let t = Time::with_timespec_and_offset(0, 0, offset)?;
assert_eq!(t.to_int(), 0);

Errors

Can produce a TimeError, however these should not be seen during regular usage.

impl Time

pub fn to_int(&self) -> i64

Returns the number of seconds as a signed integer since the Epoch.

This function can be used to implement the Ruby methods Time#to_i and Time#tv_sec.

Examples

let t = Time::utc(1970, 1, 1, 0, 1, 0, 0)?;
assert_eq!(t.to_int(), 60);

pub fn to_float(&self) -> f64

Returns the number of seconds since the Epoch with fractional nanos included at IEEE 754-2008 accuracy.

This function can be used to implement the Ruby method Time#to_f.

Examples

let now = Time::utc(1970, 1, 1, 0, 1, 0, 1000)?;
assert_eq!(now.to_float(), 60.000001);

pub fn subsec_fractional(&self) -> (u32, u32)

Returns the numerator and denominator for the number of nanoseconds of the Time struct unsimplified.

This can be used directly to implement Time#subsec.

This function can be used in combination with to_int to implement Time#to_r.

Examples

let t = Time::utc(1970, 1, 1, 0, 0, 1, 1000)?;
assert_eq!(t.subsec_fractional(), (1000, 1000000000));

Trait Implementations

impl Clone for Time

fn clone(&self) -> Time

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Time

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

Formats the value using the given formatter.

impl Display for Time

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

Returns a canonical string representation of time.

Display uses the same format as Time#to_s.

Examples

let now = Time::utc(2022, 05, 26, 13, 16, 22, 0)?;
assert_eq!(now.to_string(), "2022-05-26 13:16:22 UTC");

impl From<Time> for ToA

fn from(time: Time) -> Self

Converts to this type from the input type.

impl Hash for Time

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

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Time

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Time

fn eq(&self, other: &Time) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Time

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

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

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

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

impl Time for Time

fn year(&self) -> i32

Returns the year for time (including the century).

fn month(&self) -> u8

Returns the month of the year in 1..=12 for time.

fn day(&self) -> u8

Returns the day of the month in 1..=31 for time.

fn hour(&self) -> u8

Returns the hour of the day in 0..=23 for time.

fn minute(&self) -> u8

Returns the minute of the hour in 0..=59 for time.

fn second(&self) -> u8

Returns the second of the minute in 0..=60 for time.

fn nanoseconds(&self) -> u32

Returns the number of nanoseconds in 0..=999_999_999 for time.

fn day_of_week(&self) -> u8

Returns an integer representing the day of the week in 0..=6, with Sunday == 0.

fn day_of_year(&self) -> u16

Returns an integer representing the day of the year in 1..=366.

fn to_int(&self) -> i64

Returns the number of seconds as a signed integer since the Epoch.

fn is_utc(&self) -> bool

Returns true if the time zone is UTC.

fn utc_offset(&self) -> i32

Returns the offset in seconds between the timezone of time and UTC.

fn time_zone(&self) -> &str

Returns the name of the time zone as a string.

impl TryFrom<ToA> for Time

fn try_from(to_a: ToA) -> Result<Self>

Create a new Time object base on a ToA

Note: This converting from a Time object to a ToA and back again is lossy since ToA does not store nanoseconds.

Examples

let now = Time::local(2022, 7, 8, 12, 34, 56, 1000)?;
let to_a = now.to_array();
let from_to_a = Time::try_from(to_a)?;
assert_eq!(now.second(), from_to_a.second());
assert_ne!(now.nanoseconds(), from_to_a.nanoseconds());

Errors

Can produce a TimeError, generally when provided values are out of range.

type Error = TimeError

The type returned in the event of a conversion error.

impl Copy for Time

impl Eq for Time