pub struct Time { /* private fields */ }
Expand description
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§
Source§impl Time
impl Time
Sourcepub fn local(
year: i32,
month: u8,
month_day: u8,
hour: u8,
minute: u8,
second: u8,
nanoseconds: u32,
) -> Result<Self>
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.
Source§impl Time
impl Time
Sourcepub fn strftime(&self, format: &[u8]) -> Result<Vec<u8>, Error>
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.
Sourcepub fn to_array(self) -> ToA
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());
Source§impl Time
impl Time
Sourcepub fn round(&self, ndigits: u32) -> Self
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());
Source§impl Time
impl Time
Sourcepub fn checked_add(self, duration: Duration) -> Result<Self, TimeError>
pub fn checked_add(self, duration: Duration) -> Result<Self, TimeError>
Sourcepub fn checked_add_i64(&self, seconds: i64) -> Result<Self, TimeError>
pub fn checked_add_i64(&self, seconds: i64) -> Result<Self, TimeError>
Sourcepub fn checked_add_u64(&self, seconds: u64) -> Result<Self, TimeError>
pub fn checked_add_u64(&self, seconds: u64) -> Result<Self, TimeError>
Source§impl Time
impl Time
Sourcepub fn checked_sub(self, duration: Duration) -> Result<Self, TimeError>
pub fn checked_sub(self, duration: Duration) -> Result<Self, TimeError>
Sourcepub fn checked_sub_i64(self, seconds: i64) -> Result<Self, TimeError>
pub fn checked_sub_i64(self, seconds: i64) -> Result<Self, TimeError>
Sourcepub fn checked_sub_u64(self, seconds: u64) -> Result<Self, TimeError>
pub fn checked_sub_u64(self, seconds: u64) -> Result<Self, TimeError>
Sourcepub fn checked_sub_f64(self, seconds: f64) -> Result<Self, TimeError>
pub fn checked_sub_f64(self, seconds: f64) -> Result<Self, TimeError>
Source§impl Time
impl Time
Sourcepub fn nanoseconds(&self) -> u32
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);
Sourcepub fn microseconds(&self) -> u32
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);
Sourcepub fn second(&self) -> u8
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);
Sourcepub fn month(&self) -> u8
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);
Sourcepub fn time_zone(&self) -> &str
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());
Sourcepub fn utc_offset(&self) -> i32
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);
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.
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());
Sourcepub fn day_of_week(&self) -> u8
pub fn day_of_week(&self) -> u8
Sourcepub fn is_sunday(&self) -> bool
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());
Sourcepub fn is_monday(&self) -> bool
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());
Sourcepub fn is_tuesday(&self) -> bool
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());
Sourcepub fn is_wednesday(&self) -> bool
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());
Sourcepub fn is_thursday(&self) -> bool
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());
Sourcepub fn is_friday(&self) -> bool
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());
Sourcepub fn is_saturday(&self) -> bool
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());
Sourcepub fn day_of_year(&self) -> u16
pub fn day_of_year(&self) -> u16
Source§impl Time
impl Time
Sourcepub fn to_offset(&self, offset: Offset) -> Result<Self>
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
.
Sourcepub fn to_utc(&self) -> Result<Self>
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
.
Sourcepub fn to_local(&self) -> Result<Self>
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
.
Source§impl Time
impl Time
Sourcepub fn set_offset(&mut self, offset: Offset) -> Result<()>
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
.
Sourcepub fn set_local(&mut self) -> Result<()>
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
.
Sourcepub fn set_utc(&mut self) -> Result<()>
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
.
Sourcepub fn set_offset_from_utc(&mut self, offset: Offset) -> Result<()>
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
.
Source§impl Time
impl Time
Sourcepub fn new(
year: i32,
month: u8,
day: u8,
hour: u8,
minute: u8,
second: u8,
nanoseconds: u32,
offset: Offset,
) -> Result<Self>
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.
Sourcepub fn with_timespec_and_offset(
seconds: i64,
nanoseconds: u32,
offset: Offset,
) -> Result<Self>
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.
Source§impl Time
impl Time
Sourcepub fn to_int(&self) -> i64
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);
Sourcepub fn subsec_fractional(&self) -> (u32, u32)
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§
Source§impl Ord for Time
impl Ord for Time
Source§impl PartialOrd for Time
impl PartialOrd for Time
Source§impl Time for Time
impl Time for Time
Source§fn nanoseconds(&self) -> u32
fn nanoseconds(&self) -> u32
0..=999_999_999
for time.Source§fn day_of_week(&self) -> u8
fn day_of_week(&self) -> u8
0..=6
, with
Sunday == 0
.Source§fn day_of_year(&self) -> u16
fn day_of_year(&self) -> u16
1..=366
.Source§fn utc_offset(&self) -> i32
fn utc_offset(&self) -> i32
Source§impl TryFrom<ToA> for Time
impl TryFrom<ToA> for Time
Source§fn try_from(to_a: ToA) -> Result<Self>
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.
impl Copy for Time
impl Eq for Time
Auto Trait Implementations§
impl Freeze for Time
impl RefUnwindSafe for Time
impl Send for Time
impl Sync for Time
impl Unpin for Time
impl UnwindSafe for Time
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)