Struct spinoso_time::Time

pub struct Time { /* fields omitted */ }

Implementation of Ruby Time, a timezone-aware datetime, based on chrono.

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.

Time objects are immutable. Date/time value manipulation always returns a new Time object.

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 - (60 * 60);
assert_eq!(time.to_int() - 3600, one_hour_ago.to_int());
assert_eq!(time.nanosecond(), one_hour_ago.nanosecond());

Implementation notes

Time stores raw timestamps and only converts to chrono DateTime for computation. chrono provides an aware datetime view over the raw timestamp.

Implementations

impl Time

#[must_use]

pub fn new() -> Self

Creates a new Time object for the current time with a local offset.

Examples

use spinoso_time::Time;
let now = Time::new();

#[must_use]

pub fn now() -> Self

Creates a new Time object for the current time with a local offset.

This is same as new.

Examples

use spinoso_time::Time;
let now = Time::now();

#[must_use]

pub fn at(seconds: i64, sub_second_nanos: i64) -> Option<Self>

Creates a new Time object from the seconds and sub_second_nanos since the Unix EPOCH with a local offset.

Examples

use spinoso_time::Time;
let epoch = Time::at(0, 0);
let epoch_plus_1_nano = Time::at(0, 1);

impl Time

#[must_use]

pub fn year(self) -> i32

Returns the year for time (including the century).

Examples

let now = Time::now();
let year = now.year();

#[must_use]

pub fn month(self) -> u32

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

Examples

let now = Time::now();
let minute_of_hour = now.minute();

#[must_use]

pub fn day(self) -> u32

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

Examples

let now = Time::now();
let day_of_month = now.day();

impl Time

#[must_use]

pub fn succ(self) -> Self

Returns a new Time object, one second later than time.

This method should log a deprecation warning if Time::nanosecond is non-zero.

Examples

let now = Time::now();
let next = now.succ();
assert_eq!(now.to_int() + 1, next.to_int());

impl Time

#[must_use]

pub fn year_day(self) -> u32

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

This method returns the date’s ordinal day.

Examples

let now = Time::now();
let ordinal = now.year_day();
assert!(ordinal > 0);
assert!(ordinal <= 366);

impl Time

#[must_use]

pub fn hour(self) -> u32

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

Examples

let now = Time::now();
let hour_of_day = now.hour();

#[must_use]

pub fn minute(self) -> u32

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

Examples

let now = Time::now();
let minute_of_hour = now.minute();

#[must_use]

pub fn second(self) -> u32

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

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

Examples

let now = Time::now();
let second_of_minute = now.second();
if second_of_minute >= 60 {
    // `now` is during a leap second
}

#[must_use]

pub const fn microsecond(self) -> u32

Returns the number of microseconds for time.

This method returns microseconds since the last second (including leap seconds. The range of this value is always from 0 to 999,999.

Examples

let now = Time::now();
let usec_since_last_second = now.second();
if usec_since_last_second >= 1_000_000 {
    // `now` is during a leap second
}

#[must_use]

pub fn nanosecond(self) -> u32

Returns the number of nanoseconds for time.

This method returns nanoseconds since the last second (including leap seconds. The range of this value is always from 0 to 999,999,999.

Examples

let now = Time::now();
let nsec_since_last_second = now.nanosecond();

Implementation notes

The IEEE 754 double is not accurate enough to represent the exact number of nanoseconds since the Unix Epoch. nanosecond is more accurate than to_float.

#[must_use]

pub const fn subsec(self) -> (u32, u32)

Returns the fraction for time.

The return value can be a rational number. This result is more accurate than to_float because IEEE 754 double precision is not sufficient to losslessly encode nanosecond fractions of seconds.

Examples

let time = Time::now();
let (sub_second_units, units_per_second) = time.subsec();

Implementation notes

Time has a maximum granularity of nanoseconds, so in practice this method always returns nanoseconds, but the returned tuple accomodates returning any fractional part, such as millis or micros.

impl Time

#[must_use]

pub fn is_dst(self) -> bool

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

Implementation notes

This function is not implemented and always returns false.

#[must_use]

pub fn is_utc(self) -> bool

Returns true if time represents a time in UTC (GMT).

Examples

let local_time = Time::now();
assert!(!local_time.is_utc());
let utc_time = local_time.to_utc();
assert!(utc_time.is_utc());

#[must_use]

pub const fn to_local(self) -> Self

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

Examples

let local_time = Time::now();
assert!(!local_time.is_utc());

let local_time2 = local_time.to_local();
assert!(!local_time2.is_utc());

let utc_time = local_time.to_utc();
assert!(utc_time.is_utc());

#[must_use]

pub const fn to_utc(self) -> Self

Returns a new Time object representing time in UTC.

Examples

let local_time = Time::now();
assert!(!local_time.is_utc());

let utc_time = local_time.to_utc();
assert!(utc_time.is_utc());

let utc_time2 = utc_time.to_utc();
assert!(utc_time2.is_utc());

#[must_use]

pub fn timezone(self) -> Option<&'static str>

Returns the name of the time zone used for time.

impl Time

#[must_use]

pub fn weekday(self) -> u32

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

Examples

let now = Time::now();
match now {
    time if time.is_sunday() => assert_eq!(time.weekday(), 0),
    time if time.is_monday() => assert_eq!(time.weekday(), 1),
    time if time.is_tuesday() => assert_eq!(time.weekday(), 2),
    time if time.is_wednesday() => assert_eq!(time.weekday(), 3),
    time if time.is_thursday() => assert_eq!(time.weekday(), 4),
    time if time.is_friday() => assert_eq!(time.weekday(), 5),
    time if time.is_saturday() => assert_eq!(time.weekday(), 6),
    _ => {}
}

#[must_use]

pub fn is_sunday(self) -> bool

Returns true if time represents Sunday.

Examples

let now = Time::now();
if now.is_sunday() {
    // go grocery shopping
    assert_eq!(now.weekday(), 0);
}

#[must_use]

pub fn is_monday(self) -> bool

Returns true if time represents Monday.

Examples

let now = Time::now();
if now.is_monday() {
    // go to work
    assert_eq!(now.weekday(), 1);
}

#[must_use]

pub fn is_tuesday(self) -> bool

Returns true if time represents Tuesday.

Examples

let now = Time::now();
if now.is_tuesday() {
    // go to the gym
    assert_eq!(now.weekday(), 2);
}

#[must_use]

pub fn is_wednesday(self) -> bool

Returns true if time represents Wednesday.

Examples

let now = Time::now();
if now.is_wednesday() {
    // hump day!
    assert_eq!(now.weekday(), 3);
}

#[must_use]

pub fn is_thursday(self) -> bool

Returns true if time represents Thursday.

Examples

let now = Time::now();
if now.is_thursday() {
    // Chinese food delivery for dinner
    assert_eq!(now.weekday(), 4);
}

#[must_use]

pub fn is_friday(self) -> bool

Returns true if time represents Friday.

Examples

let now = Time::now();
if now.is_friday() {
    // TGIF
    // Friday, Friday, gotta get down
    assert_eq!(now.weekday(), 5);
}

#[must_use]

pub fn is_saturday(self) -> bool

Returns true if time represents Saturday.

Examples

let now = Time::now();
if now.is_saturday() {
    // hike at the lake
    assert_eq!(now.weekday(), 6);
}

impl Time

#[must_use]

pub fn to_float(&self) -> f64

Returns the value of time as a floating point number of seconds since the Unix Epoch.

Examples

let now = Time::now();
let now_f = now.to_float();
let now_i = now.to_int();
assert!(now_i as f64 <= now_f);

Implementation notes

The IEEE 754 double is not accurate enough to represent the exact number of subsecond nanoseconds in the Time.

#[must_use]

pub const fn to_int(self) -> i64

Returns the value of time as an integer number of seconds since the Unix Epoch.

Examples

let now = Time::now();
let now_f = now.to_float();
let now_i = now.to_int();
assert!(now_i as f64 <= now_f);

#[must_use]

pub fn to_a(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 API, and is accessible with the ToA::to_tuple method.

Examples

let now = Time::now();
let to_a = now.to_a();
assert_eq!(to_a.sec, now.second());
assert_eq!(to_a.wday, now.weekday());

Trait Implementations

impl Add<Duration> for Time

type Output = Self

The resulting type after applying the + operator.

fn add(self, duration: Duration) -> Self::Output

Performs the + operation.

impl Add<Duration> for Time

type Output = Self

The resulting type after applying the + operator.

fn add(self, duration: Duration) -> Self::Output

Performs the + operation.

impl Add<f32> for Time

type Output = Self

The resulting type after applying the + operator.

fn add(self, seconds: f32) -> Self::Output

Performs the + operation.

impl Add<f64> for Time

type Output = Self

The resulting type after applying the + operator.

fn add(self, seconds: f64) -> Self::Output

Performs the + operation.

impl Add<i16> for Time

type Output = Self

The resulting type after applying the + operator.

fn add(self, seconds: i16) -> Self::Output

Performs the + operation.

impl Add<i32> for Time

type Output = Self

The resulting type after applying the + operator.

fn add(self, seconds: i32) -> Self::Output

Performs the + operation.

impl Add<i64> for Time

type Output = Self

The resulting type after applying the + operator.

fn add(self, seconds: i64) -> Self::Output

Performs the + operation.

impl Add<i8> for Time

type Output = Self

The resulting type after applying the + operator.

fn add(self, seconds: i8) -> Self::Output

Performs the + operation.

impl Add<u16> for Time

type Output = Self

The resulting type after applying the + operator.

fn add(self, seconds: u16) -> Self::Output

Performs the + operation.

impl Add<u32> for Time

type Output = Self

The resulting type after applying the + operator.

fn add(self, seconds: u32) -> Self::Output

Performs the + operation.

impl Add<u64> for Time

type Output = Self

The resulting type after applying the + operator.

fn add(self, seconds: u64) -> Self::Output

Performs the + operation.

impl Add<u8> for Time

type Output = Self

The resulting type after applying the + operator.

fn add(self, seconds: u8) -> Self::Output

Performs the + operation.

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 Default for Time

fn default() -> Self

The zero-argument Time#new constructor creates a local time set to the current system time.

impl From<DateTime<FixedOffset>> for Time

fn from(time: DateTime<FixedOffset>) -> Self

Performs the conversion.

impl From<DateTime<Local>> for Time

fn from(time: DateTime<Local>) -> Self

Performs the conversion.

impl From<DateTime<Tz>> for Time

fn from(time: DateTime<Tz>) -> Self

Performs the conversion.

impl From<DateTime<Utc>> for Time

fn from(time: DateTime<Utc>) -> Self

Performs the conversion.

impl From<Time> for ToA

fn from(time: Time) -> Self

Performs the conversion.

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, 

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.

#[must_use]

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

Compares and returns the maximum of two values.

#[must_use]

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

Compares and returns the minimum of two values.

#[must_use]

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

Restrict a value to a certain interval.

impl PartialEq<Time> for Time

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

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

#[must_use]

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

This method tests for !=.

impl PartialOrd<Time> for Time

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

impl Sub<Duration> for Time

type Output = Self

The resulting type after applying the - operator.

fn sub(self, duration: Duration) -> Self::Output

Performs the - operation.

impl Sub<Duration> for Time

type Output = Self

The resulting type after applying the - operator.

fn sub(self, duration: Duration) -> Self::Output

Performs the - operation.

impl Sub<Time> for Time

type Output = Self

The resulting type after applying the - operator.

fn sub(self, other: Time) -> Self::Output

Performs the - operation.

impl Sub<f32> for Time

type Output = Self

The resulting type after applying the - operator.

fn sub(self, seconds: f32) -> Self::Output

Performs the - operation.

impl Sub<f64> for Time

type Output = Self

The resulting type after applying the - operator.

fn sub(self, seconds: f64) -> Self::Output

Performs the - operation.

impl Sub<i16> for Time

type Output = Self

The resulting type after applying the - operator.

fn sub(self, seconds: i16) -> Self::Output

Performs the - operation.

impl Sub<i32> for Time

type Output = Self

The resulting type after applying the - operator.

fn sub(self, seconds: i32) -> Self::Output

Performs the - operation.

impl Sub<i64> for Time

type Output = Self

The resulting type after applying the - operator.

fn sub(self, seconds: i64) -> Self::Output

Performs the - operation.

impl Sub<i8> for Time

type Output = Self

The resulting type after applying the - operator.

fn sub(self, seconds: i8) -> Self::Output

Performs the - operation.

impl Sub<u16> for Time

type Output = Self

The resulting type after applying the - operator.

fn sub(self, seconds: u16) -> Self::Output

Performs the - operation.

impl Sub<u32> for Time

type Output = Self

The resulting type after applying the - operator.

fn sub(self, seconds: u32) -> Self::Output

Performs the - operation.

impl Sub<u64> for Time

type Output = Self

The resulting type after applying the - operator.

fn sub(self, seconds: u64) -> Self::Output

Performs the - operation.

impl Sub<u8> for Time

type Output = Self

The resulting type after applying the - operator.

fn sub(self, seconds: u8) -> Self::Output

Performs the - operation.

impl TryFrom<ToA> for Time

type Error = ComponentOutOfRangeError

The type returned in the event of a conversion error.

fn try_from(time: ToA) -> Result<Self, Self::Error>

Performs the conversion.

impl Copy for Time

impl Eq for Time