class Time
include Comparable[Time]
A point in time, to the nanosecond, with the UTC offset it is shown in. Immutable.
A time is either in UTC (Time.utc, #utc, a parsed Z) or carries a
fixed offset: Time.now, Time.at, Time.local and #getlocal take
the local time zone's offset for that instant (from the TZ environment
variable or the system), Time.parse and Time.iso8601 the offset
written in the text. The offset is fixed when the time is made: #+
and #- keep it, even across a daylight-saving change. Two times are
equal when they are the same instant, whatever their offsets.
The range is that of a 64-bit count of nanoseconds since 1970: from
1677-09-21 00:12:44 UTC to 2262-04-11 23:47:16 UTC. Time.at,
Time.utc, Time.local, Time.iso8601 and #+ raise RangeError
outside it.
t = Time.utc(2024, 3, 5, 14, 7, 9)
t # => 2024-03-05 14:07:09 UTC
t.iso8601 # => "2024-03-05T14:07:09Z"
(t + 1.day).day # => 6
t == Time.iso8601("2024-03-05T23:07:09+09:00") # => true
<prelude>:1718
Class methods
def self.now -> Time
The current time, in the local time zone.
<prelude>:1723
def self.at(seconds: Int) -> Time
The time seconds after 1970-01-01 00:00:00 UTC, in the local time
zone.
A negative seconds is before 1970. Time.at(0).utc is the epoch in
UTC.
Raises
RangeError when the time is out of range.
<prelude>:1733
def self.at(seconds: Float) -> Time
The time seconds after 1970-01-01 00:00:00 UTC, in the local time
zone.
A negative seconds is before 1970. Time.at(0).utc is the epoch in
UTC.
Raises
RangeError when the time is out of range.
<prelude>:1735
def self.utc(year: Int, month: Int = …, day: Int = …, hour: Int = …, min: Int = …, sec: Int = …) -> Time
The time of the given date and time of day in UTC.
Raises
ArgumentError when a part is out of range (month 13, February 30,
hour 24, second 60); RangeError for a time outside the range Time
can hold (before 1677-09-21 00:12:44 or after 2262-04-11 23:47:16
UTC).
Time.utc(2024) # => 2024-01-01 00:00:00 UTC
Time.utc(2262, 4, 11) # => 2262-04-11 00:00:00 UTC
Time.utc(2024, 2, 30) # raises ArgumentError
Time.utc(3000) # raises RangeError
<prelude>:1751
def self.local(year: Int, month: Int = …, day: Int = …, hour: Int = …, min: Int = …, sec: Int = …) -> Time
The time of the given date and time of day in the local time zone.
A time that occurs twice (when clocks go back) is the earlier one.
Raises
ArgumentError when a part is out of range (month 13, hour 24), or
the time does not occur locally (skipped when clocks go forward);
RangeError for a time outside the range Time can hold, as in
Time.utc.
<prelude>:1762
def self.parse(text: String) -> Time
The time written in text.
The forms are RFC 3339 (2024-03-05T14:07:09+09:00),
YYYY-MM-DD HH:MM[:SS[.fraction]] followed by an offset (+09:00,
+0900) or Z, or without one in the local time zone, or a date
alone (YYYY-MM-DD, midnight local time). A T may separate the date
and the time; whitespace at the ends is ignored. A time ending in Z
is in UTC, one with an offset keeps that offset.
#to_s's and #inspect's own forms are read too: the offset may
follow the time after a space (2024-03-05 14:07:09 +0900), and
UTC stands for Z (2024-03-05 14:07:09 UTC), so #to_s reads
back as the same time.
Raises
ArgumentError when text is in none of these forms, RangeError
when it is a time outside the range a Time holds.
Time.parse("2024-03-05 14:07:09Z") # => 2024-03-05 14:07:09 UTC
Time.parse("2024-03-05T14:07:09+09:00").utc_offset # => 32400
Time.parse("2024-03-05 14:07:09 UTC") # => 2024-03-05 14:07:09 UTC
t = Time.utc(2024, 3, 5, 14, 7, 9)
Time.parse(t.to_s) == t # => true
Time.parse("yesterday") # raises ArgumentError
<prelude>:1790
def self.iso8601(text: String) -> Time
The time written in text in RFC 3339 form.
That is the profile of ISO 8601 that #iso8601 writes: a date, a
time, an optional fraction and an offset or Z (in UTC).
Raises
ArgumentError for any other form, a date alone included;
RangeError for a time outside the range Time can hold.
Time.iso8601("2024-03-05T14:07:09Z") # => 2024-03-05 14:07:09 UTC
Time.iso8601("3000-01-01T00:00:00Z") # raises RangeError
<prelude>:1805
def self.monotonic -> Duration
The time elapsed since the program started, from a clock that never goes back.
Subtract two readings to time something: unlike .now, it does not
jump when the system clock is set.
<prelude>:1811
Methods
def year -> Int
The year, in the time's own offset (as are the other parts).
<prelude>:1814
def month -> Int
The month, 1 to 12.
<prelude>:1816
def day -> Int
The day of the month, 1 to 31.
<prelude>:1818
def hour -> Int
The hour, 0 to 23.
<prelude>:1820
def min -> Int
The minute, 0 to 59.
<prelude>:1822
def sec -> Int
The second, 0 to 59.
<prelude>:1824
def usec -> Int
The microseconds within the second, 0 to 999999.
<prelude>:1826
def nsec -> Int
The nanoseconds within the second, 0 to 999999999.
<prelude>:1828
def wday -> Int
The day of the week, 0 (Sunday) to 6 (Saturday).
<prelude>:1830
def yday -> Int
The day of the year, 1 to 366.
<prelude>:1832
def sunday? -> Bool
Whether the day is a Sunday.
<prelude>:1834
def monday? -> Bool
Whether the day is a Monday.
<prelude>:1836
def tuesday? -> Bool
Whether the day is a Tuesday.
<prelude>:1838
def wednesday? -> Bool
Whether the day is a Wednesday.
<prelude>:1840
def thursday? -> Bool
Whether the day is a Thursday.
<prelude>:1842
def friday? -> Bool
Whether the day is a Friday.
<prelude>:1844
def saturday? -> Bool
Whether the day is a Saturday.
<prelude>:1846
def to_i -> Int
The whole seconds since 1970-01-01 00:00:00 UTC, rounded down.
<prelude>:1848
def to_f -> Float
The seconds since 1970-01-01 00:00:00 UTC, with the fraction.
<prelude>:1850
def +(duration: Duration) -> Time
The time duration later, in the same offset.
Raises
RangeError when the result is out of range.
<prelude>:1856
def -(duration: Duration) -> Time
The time duration earlier, in the same offset.
Raises
RangeError when the result is out of range.
<prelude>:1862
def -(other: Time) -> Duration
The time from other to this time (negative when other is later).
Raises
RangeError when the difference does not fit a Duration (about 292
years either way).
Time.utc(2024, 1, 2) - Time.utc(2024, 1, 1) == 1.day # => true
Time.utc(2262) - Time.utc(1678) # raises RangeError
<prelude>:1874
def <=>(other: Time) -> Int
Compares the instants, whatever the offsets: -1, 0 or 1.
<prelude>:1876
def ==(other: Object) -> Bool
Whether other is a Time at the same instant (the offsets may
differ).
<prelude>:1879
def hash -> Int
A hash of the instant, consistent with #==.
<prelude>:1881
def utc -> Time
The same instant in UTC.
<prelude>:1883
def getlocal -> Time
The same instant in the local time zone.
<prelude>:1885
def localtime -> Time
The same instant in the local time zone (Ruby changes the receiver;
this returns a new time, as #getlocal does).
<prelude>:1888
def utc? -> Bool
Whether the time is in UTC. A local time whose offset is zero is not.
<prelude>:1890
def utc_offset -> Int
The offset from UTC in seconds, east positive (0 in UTC).
<prelude>:1892
def zone -> String
"UTC" for a time in UTC; otherwise the offset as "+09:00" (not a
zone's abbreviation such as JST).
<prelude>:1895
def strftime(format: String) -> String
The time formatted by format, with the directives of C's strftime
(%Y-%m-%d %H:%M:%S, %a, %j, %z, ...) and Ruby's %L
(milliseconds), %N (nanoseconds; %3N, %6N for fewer digits) and
%Z ("UTC" in UTC, the offset otherwise).
Raises
ArgumentError for an unknown directive.
Time.utc(2024, 3, 5, 14, 7, 9).strftime("%Y/%m/%d %a %H:%M %Z")
# => "2024/03/05 Tue 14:07 UTC"
<prelude>:1909
def iso8601 -> String
The time in ISO 8601 (RFC 3339) form: 2024-03-05T14:07:09Z in UTC,
2024-03-05T14:07:09+09:00 otherwise.
<prelude>:1912
def iso8601(fraction_digits: Int) -> String
The same, with fraction_digits digits of the second's fraction
(clamped to 0 to 9): 2024-03-05T14:07:09.000Z.
<prelude>:1915
def to_s -> String
The time as 2024-03-05 14:07:09 +0900, or ... UTC in UTC.
<prelude>:1917
def inspect -> String
As #to_s, with the fraction of the second when it is not zero:
2024-03-05 14:07:09.5 UTC.
<prelude>:1920