pub struct Time { /* private fields */ }
Expand description
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
sourceimpl Time
impl Time
sourceimpl Time
impl Time
sourceimpl Time
impl Time
sourcepub fn succ(self) -> Time
pub fn succ(self) -> Time
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());
sourcepub fn difference(self, other: Time) -> f64
pub fn difference(self, other: Time) -> f64
Returns the difference between two Time
objects as an f64
of seconds.
sourceimpl Time
impl Time
sourcepub fn hour(self) -> u32
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();
sourcepub fn minute(self) -> u32
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();
sourcepub fn second(self) -> u32
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
}
sourcepub const fn microsecond(self) -> u32
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
}
sourcepub fn nanosecond(self) -> u32
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
.
sourcepub const fn subsec(self) -> (u32, u32)
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 accommodates returning any fractional part, such as millis or micros.
sourceimpl Time
impl Time
sourcepub fn is_dst(self) -> bool
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
.
sourcepub fn is_utc(self) -> bool
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());
sourcepub const fn to_local(self) -> Time
pub const fn to_local(self) -> Time
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());
sourceimpl Time
impl Time
sourcepub fn weekday(self) -> u32
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),
_ => {}
}
sourcepub fn is_sunday(self) -> bool
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);
}
sourcepub fn is_monday(self) -> bool
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);
}
sourcepub fn is_tuesday(self) -> bool
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);
}
sourcepub fn is_wednesday(self) -> bool
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);
}
sourcepub fn is_thursday(self) -> bool
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);
}
sourcepub fn is_friday(self) -> bool
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);
}
sourcepub fn is_saturday(self) -> bool
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);
}
sourceimpl Time
impl Time
sourcepub fn to_float(self) -> f64
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
.
sourcepub const fn to_int(self) -> i64
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);
sourcepub fn to_a(self) -> ToA
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
sourceimpl From<DateTime<FixedOffset>> for Time
impl From<DateTime<FixedOffset>> for Time
sourcefn from(time: DateTime<FixedOffset>) -> Time
fn from(time: DateTime<FixedOffset>) -> Time
Converts to this type from the input type.
sourceimpl Ord for Time
impl Ord for Time
sourceimpl PartialOrd<Time> for Time
impl PartialOrd<Time> for Time
sourcefn partial_cmp(&self, other: &Time) -> Option<Ordering>
fn partial_cmp(&self, other: &Time) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
1.0.0 · sourcefn lt(&self, other: &Rhs) -> bool
fn lt(&self, other: &Rhs) -> bool
This method tests less than (for self
and other
) and is used by the <
operator. Read more
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
impl Copy for Time
impl Eq for Time
Auto Trait Implementations
impl RefUnwindSafe for Time
impl Send for Time
impl Sync for Time
impl Unpin for Time
impl UnwindSafe for Time
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more