struct Time
Overview
Time
represents a date-time instant in
incremental time
observed in a specific time zone.
The calendaric calculations are based on the rules of the proleptic Gregorian calendar as specified in ISO 8601. Leap seconds are ignored.
Internally, the time is stored as an Int64
representing seconds from epoch
(0001-01-01 00:00:00.0 UTC
) and an Int32
representing
nanosecond-of-second with value range 0..999_999_999
.
The supported date range is 0001-01-01 00:00:00.0
to
9999-12-31 23:59:59.999_999_999
in any local time zone.
Telling the Time
There are several methods to retrieve a Time
instance representing the
current time:
Time.utc_now # returns the current time in UTC
Time.now Time::Location.load("Europe/Berlin") # returns the current time in time zone Europe/Berlin
Time.now # returns the current time in current time zone
It is generally recommended to keep instances in UTC and only apply a local time zone when formatting for user display, unless the domain logic requires having a specific time zone (for example for calendaric operations).
Creating a Specific Instant
Time
instances representing a specific instant can be created by
.utc
or .new
with the date-time specified as individual arguments:
time = Time.utc(2016, 2, 15, 10, 20, 30)
time.to_s # => 2016-02-15 10:20:30 UTC
time = Time.new(2016, 2, 15, 10, 20, 30, location: Time::Location.load("Europe/Berlin"))
time.to_s # => 2016-02-15 10:20:30 +01:00 Europe/Berlin
The time-of-day can be omitted and defaults to midnight (start of day):
time = Time.utc(2016, 2, 15)
time.to_s # => 2016-02-15 00:00:00 UTC
Retrieving Time Information
Each Time
instance allows querying calendar data:
time = Time.utc(2016, 2, 15, 10, 20, 30)
time.year # => 2016
time.month # => 2
time.day # => 15
time.hour # => 10
time.minute # => 20
time.second # => 30
time.millisecond # => 0
time.nanosecond # => 0
time.day_of_week # => Monday
time.day_of_year # => 46
time.monday? # => true
time.time_of_day # => 15:10:30
Time Zones
Each time is attached to a specific time zone, represented by a Location
(see #location
).
#zone
returns the time zone observed in this location at the current time
(i.e. the instant represented by this Time
).
#offset
returns the offset of the current zone in seconds.
time = Time.new(2018, 3, 8, 22, 5, 13, location: Time::Location.load("Europe/Berlin"))
time # => 2018-03-08 22:05:13 +01:00 Europe/Berlin
time.location # => #<Time::Location Europe/Berlin>
time.zone # => #<Time::Location::Zone CET +01:00 (3600s) STD>
time.offset # => 3600
Using .utc
, the location is Time::Location::UTC
:
time = Time.utc(2018, 3, 8, 22, 5, 13)
time # => 2016-02-15 10:20:30 UTC
time.location # => #<Time::Location UTC>
time.zone # => #<Time::Location::Zone UTC +00:00 (0s) STD>
time.offset # => 0
A Time
instance can be transformed to a different time zone while retaining
the same instant using #in
:
time_de = Time.new(2018, 3, 8, 22, 5, 13, location: Time::Location.load("Europe/Berlin"))
time_ar = time_de.in Time::Location.load("America/Buenos_Aires")
time_de # => 2018-03-08 22:05:13 +01:00 Europe/Berlin
time_ar # => 2018-03-08 18:05:13 -03:00 America/Buenos_Aires
Both Time
instances show a different local date-time, but they represent
the same date-time in the instant time-line, therefore they are considered
equal:
time_de.to_utc # => 2018-03-08 21:05:13 UTC
time_ar.to_utc # => 2018-03-08 21:05:13 UTC
time_de == time_ar # => true
There are also two special methods for converting to UTC and local time zone:
time.to_utc # equals time.in(Location::UTC)
time.to_local # equals time.in(Location.local)
Formatting and Parsing Time
To make date-time instances exchangeable between different computer systems or readable to humans, they are usually converted to and from a string representation.
The method #to_s
formats the date-time according to a specified pattern.
time = Time.utc(2015, 10, 12, 10, 30, 0)
time.to_s("%Y-%m-%d %H:%M:%S %:z") # => "2015-10-12 10:30:00 +00:00"
Similarly, Time.parse
is used to construct a Time
instance from date-time
information in a string, according to a specified pattern:
Time.parse("2015-10-12 10:30:00 +00:00", "%Y-%m-%d %H:%M:%S %z")
See Time::Format
for all directives.
Calculations
Time.utc(2015, 10, 10) - 5.days # => 2015-10-05 00:00:00 +00:00
span = Time.utc(2015, 10, 10) - Time.utc(2015, 9, 10)
span.days # => 30
span.total_hours # => 720
span.total_minutes # => 43200
Measuring Time
The typical time representation provided by the operating system is based on a "wall clock" which is subject to changes for clock synchronization. This can result in discontinuous jumps in the time-line making it not suitable for accurately measuring elapsed time.
Instances of Time
are focused on telling time – using a "wall clock".
When Time.now
is called multiple times, the difference between the
returned instances is not guranteed to equal to the time elapsed between
making the calls; even the order of the returned Time
instances might
not reflect invocation order.
t1 = Time.utc_now
# operation that takes 1 minute
t2 = Time.utc_now
t2 - t1 # => ?
The resulting Time::Span
could be anything, even negative, if the
computer's wall clock has changed between both calls.
As an alternative, the operating system also provides a monotonic clock. It's time-line has no specfied starting point but is strictly linearly increasing.
This monotonic clock should always be used for measuring elapsed time.
A reading from this clock can be taken using .monotonic
:
t1 = Time.monotonic
# operation that takes 1 minute
t2 = Time.monotonic
t2 - t1 # => 1.minute (approximately)
The execution time of a block can be measured using .measure
:
elapsed_time = Time.measure do
# operation that takes 20 milliseconds
end
elapsed_time # => 20.milliseconds (approximately)
Included Modules
Defined in:
time.crjson/to_json.cr
yaml/to_yaml.cr
Constructors
-
.epoch(seconds : Int) : Time
Creates a new
Time
instance that corresponds to the number of seconds elapsed since the Unix epoch (1970-01-01 00:00:00 UTC
). -
.epoch_ms(milliseconds : Int) : Time
Creates a new
Time
instance that corresponds to the number of milliseconds elapsed since the Unix epoch (1970-01-01 00:00:00 UTC
). -
.new(year : Int32, month : Int32, day : Int32, hour : Int32 = 0, minute : Int32 = 0, second : Int32 = 0, *, nanosecond : Int32 = 0, location : Location = Location.local) : Time
Creates a new
Time
instance representing the given local date-time in location (defaults to local time zone). - .new(ctx : YAML::ParseContext, node : YAML::Nodes::Node)
-
.new(location : Location = Location.local) : Time
Creates a new
Time
instance representing the current time from the system clock observed in location (defaults to local time zone). - .new(pull : JSON::PullParser)
-
.new(*, seconds : Int64, nanoseconds : Int32, location : Location)
Creates a new
Time
instance that corresponds to the number of seconds and nanoseconds elapsed from epoch (0001-01-01 00:00:00.0 UTC
) observed in location. -
.now(location : Location = Location.local) : Time
Creates a new
Time
instance representing the current time from the system clock observed in location (defaults to local time zone). -
.parse(time : String, pattern : String, location : Location? = nil) : Time
Parses a
Time
from time string using the given pattern. -
.utc(year : Int32, month : Int32, day : Int32, hour : Int32 = 0, minute : Int32 = 0, second : Int32 = 0, *, nanosecond : Int32 = 0) : Time
Creates a new
Time
instance representing the given date-time in UTC. -
.utc(*, seconds : Int64, nanoseconds : Int32) : Time
Creates a new
Time
instance that corresponds to the number of seconds and nanoseconds elapsed from epoch (0001-01-01 00:00:00.0 UTC
) in UTC. -
.utc_now : Time
Creates a new
Time
instance representing the current time from the system clock in UTC.
Class Method Summary
-
.days_in_month(year : Int, month : Int) : Int32
Returns the number of days in month (value range:
1..12
) taking account of the year. -
.days_in_year(year : Int) : Int32
Returns the number of days in year.
-
.leap_year?(year : Int) : Bool
Returns
true
if year is a leap year in the proleptic Gregorian calendar. -
.measure(&block) : Time::Span
Measures the execution time of block.
-
.monotonic : Time::Span
Returns a reading from the monotonic clock to measure elapsed time.
-
.parse_iso8601(time : String)
Parse datetime format specified by ISO 8601.
-
.parse_rfc2822(time : String)
Parse time format specified by RFC 2822.
- .parse_rfc3339(time : String)
Instance Method Summary
-
#+(span : Time::Span) : Time
Returns a copy of this
Time
with span added. -
#+(span : Time::MonthSpan) : Time
Returns a copy of this
Time
with span added. -
#-(other : Time) : Time::Span
Returns a
Time::Span
amounting to the duration between other andself
. -
#-(span : Time::Span) : Time
Returns a copy of this
Time
with span subtracted. -
#-(span : Time::MonthSpan) : Time
Returns a copy of this
Time
with span subtracted. -
#<=>(other : Time) : Int32
Compares this
Time
with other. -
#==(other : Time) : Bool
Compares this
Time
with other for equality. -
#add_span(seconds : Int, nanoseconds : Int) : Time
Returns a copy of this
Time
with the number of seconds and nanoseconds added. -
#at_beginning_of_day : Time
Returns a copy of this
Time
representing the beginning of the day. -
#at_beginning_of_hour : Time
Returns a copy of this
Time
representing the beginning of the hour. -
#at_beginning_of_minute : Time
Returns a copy of this
Time
representing the beginning of the minute. -
#at_beginning_of_month : Time
Returns a copy of this
Time
representing the beginning of the month. -
#at_beginning_of_quarter : Time
Returns a copy of this
Time
representing the beginning of the quarter. -
#at_beginning_of_second : Time
Returns a copy of this
Time
representing the beginning of the seconds. -
#at_beginning_of_semester : Time
Returns a copy of this
Time
representing the beginning of the semester. -
#at_beginning_of_week : Time
Returns a copy of this
Time
representing the beginning of the week. -
#at_beginning_of_year : Time
Returns a copy of this
Time
representing the beginning of the year. -
#at_end_of_day : Time
Returns a copy of this
Time
representing the end of the day. -
#at_end_of_hour : Time
Returns a copy of this
Time
representing the end of the hour. -
#at_end_of_minute
Returns a copy of this
Time
representing the end of the minute. -
#at_end_of_month : Time
Returns a copy of this
Time
representing the end of the month. -
#at_end_of_quarter : Time
Returns a copy of this
Time
representing the end of the quarter. -
#at_end_of_second
Returns a copy of this
Time
representing the end of the second. -
#at_end_of_semester : Time
Returns a copy of this
Time
representing the end of the semester. -
#at_end_of_week : Time
Returns a copy of this
Time
representing the end of the week. -
#at_end_of_year : Time
Returns a copy of this
Time
representing the end of the year. -
#at_midday : Time
Returns a copy of this
Time
representing midday (12:00
) of the same day. - #clone : Time
-
#date : Time
Returns a copy of
self
with time-of-day components (hour, minute, second, nanoseconds) set to zero. -
#day : Int32
Returns the day of the month (
1..31
). -
#day_of_week : Time::DayOfWeek
Returns the day of the week (
Sunday..Saturday
). -
#day_of_year : Int32
Returns the day of the year.
-
#epoch : Int64
Returns the number of seconds since the Unix epoch (
1970-01-01 00:00:00 UTC
). -
#epoch_f : Float64
Returns the number of seconds since the Unix epoch (
1970-01-01 00:00:00 UTC
) asFloat64
with nanosecond precision. -
#epoch_ms : Int64
Returns the number of milliseconds since the Unix epoch (
1970-01-01 00:00:00 UTC
). -
#friday? : Bool
Returns
true
if the day of week is Friday. - #hash(hasher)
-
#hour : Int32
Returns the hour of the day (
0..23
). -
#in(location : Location) : Time
Returns a copy of this
Time
representing the same instant observed in location. -
#inspect(io : IO, with_nanoseconds = true)
Prints this
Time
to io. -
#local? : Bool
Returns
true
if#location
equals to the local time zone (Time::Location.local
). - #location : Location
-
#millisecond : Int32
Returns the millisecond of the second (
0..999
). -
#minute : Int32
Returns the minute of the hour (
0..59
). -
#monday? : Bool
Returns
true
if the day of week is Monday. -
#month : Int32
Returns the month of the year (
1..12
). -
#nanosecond : Int32
Returns the nanosecond of the second (
0..999_999_999
). -
#offset : Int32
Returns the offset from UTC (in seconds) in effect in
#location
at this instant. -
#saturday? : Bool
Returns
true
if the day of week is Saturday. -
#second : Int32
Returns the second of the minute (
0..59
). -
#sunday? : Bool
Returns
true
if the day of week is Sunday. -
#thursday? : Bool
Returns
true
if the day of week is Thursday. -
#time_of_day : Time::Span
Returns the duration between this
Time
and midnight of the same day. - #to_json(json : JSON::Builder)
-
#to_local : Time
Returns a copy of this
Time
representing the same instant in the local time zone (Time::Location.local
). -
#to_rfc2822
Format this time using the format specified by RFC 2822.
-
#to_rfc2822(io : IO)
Format this time using the format specified by RFC 2822 into the given io.
- #to_rfc3339
- #to_rfc3339(io : IO)
-
#to_s(format : String) : String
Formats this
Time
according to the pattern in format. -
#to_s(io : IO)
Prints this
Time
to io. -
#to_s(format : String, io : IO) : Nil
Formats this
Time
according to the pattern in format to the given io. -
#to_utc : Time
Returns a copy of this
Time
representing the same instant in UTC (Time::Location::UTC
). - #to_yaml(yaml : YAML::Nodes::Builder)
-
#tuesday? : Bool
Returns
true
if the day of week is Tuesday. -
#utc? : Bool
Returns
true
if#location
equals toLocation::UTC
. -
#wednesday? : Bool
Returns
true
if the day of week is Wednesday. -
#year : Int32
Returns the year of the proleptic Georgian Calendar (
0..9999
). -
#zone : Time::Location::Zone
Returns the time zone in effect in
#location
at this instant.
Instance methods inherited from module Comparable(Time)
<(other : T)
<,
<=(other : T)
<=,
<=>(other : T)
<=>,
==(other : T)
==,
>(other : T)
>,
>=(other : T)
>=
Instance methods inherited from struct Struct
==(other) : Bool
==,
hash(hasher)
hash,
inspect(io : IO) : Nil
inspect,
pretty_print(pp) : Nil
pretty_print,
to_s(io)
to_s
Instance methods inherited from struct Value
==(other : JSON::Any)==(other : YAML::Any)
==(other) ==, dup dup
Instance methods inherited from class Object
!=(other)
!=,
!~(other)
!~,
==(other)
==,
===(other : JSON::Any)===(other : YAML::Any)
===(other) ===, =~(other) =~, class class, dup dup, hash(hasher)
hash hash, inspect(io : IO)
inspect inspect, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&block) tap, to_json(io : IO)
to_json to_json, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ") to_pretty_json, to_s
to_s(io : IO) to_s, to_yaml(io : IO)
to_yaml to_yaml, try(&block) try, unsafe_as(type : T.class) forall T unsafe_as
Constructor methods inherited from class Object
from_json(string_or_io, root : String) : selffrom_json(string_or_io) : self from_json, from_yaml(string_or_io : String | IO) : self from_yaml
Constructor Detail
Creates a new Time
instance that corresponds to the number of
seconds elapsed since the Unix epoch (1970-01-01 00:00:00 UTC
).
The time zone is always UTC.
Time.epoch(981173106) # => 2001-02-03 04:05:06 UTC
Creates a new Time
instance that corresponds to the number of
milliseconds elapsed since the Unix epoch (1970-01-01 00:00:00 UTC
).
The time zone is always UTC.
time = Time.epoch_ms(981173106789) # => 2001-02-03 04:05:06.789 UTC
time.millisecond # => 789
Creates a new Time
instance representing the given local date-time in
location (defaults to local time zone).
time = Time.new(2016, 2, 15, 10, 20, 30, location: Time::Location.load("Europe/Berlin"))
time.to_s # => 2016-02-15 10:20:30 +01:00 Europe/Berlin
Valid value ranges for the individual fields:
#year
:1..9999
#month
:1..12
#day
:1
-28
/29
/30
/31
(depending on month and year)#hour
:0..23
#minute
:0..59
#second
:0..59
#nanosecond
:0..999_999_999
The time-of-day can be omitted and defaults to midnight (start of day):
time = Time.new(2016, 2, 15)
time.to_s # => 2016-02-15 00:00:00 +00:00 Local
The local date-time representation is resolved to a single instant based on the offset observed in the location at this time.
This process can sometimes be ambiguous, mostly due skipping or repeating
times at time zone transitions. For example, in America/New_York
the
date-time 2011-03-13 02:15:00
never occured, there is a gap between time
zones. In return, 2011-11-06 01:15:00
occured twice because of overlapping
time zones.
In such cases, the choice of time zone, and therefore the time, is not well-defined. This method returns a time that is correct in one of the two zones involved in the transition, but it does not guarantee which.
Creates a new Time
instance representing the current time from the
system clock observed in location (defaults to local time zone).
Reads a string from JSON parser as a time formated according to RFC 3339 or other variations of ISO 8601.
The JSON format itself does not specify a time data type, this method just assumes that a string holding a ISO 8601 time format can be # interpreted as a time value.
See #to_json
for reference.
Creates a new Time
instance that corresponds to the number of seconds
and nanoseconds elapsed from epoch (0001-01-01 00:00:00.0 UTC
)
observed in location.
Valid range for seconds is 0..315_537_897_599
.
For nanoseconds it is 0..999_999_999
.
Creates a new Time
instance representing the current time from the
system clock observed in location (defaults to local time zone).
Parses a Time
from time string using the given pattern.
See Time::Format
for details.
Time.parse("2016-04-05", "%F") # => 2016-04-05 00:00:00 +01:00
Creates a new Time
instance representing the given date-time in UTC.
time = Time.utc(2016, 2, 15, 10, 20, 30)
time.to_s # => 2016-02-15 10:20:30 UTC
Valid value ranges for the individual fields:
#year
:1..9999
#month
:1..12
#day
:1
-28
/29
/30
/31
(depending on month and year)#hour
:0..23
#minute
:0..59
#second
:0..59
#nanosecond
:0..999_999_999
The time-of-day can be omitted and defaults to midnight (start of day):
time = Time.utc(2016, 2, 15)
time.to_s # => 2016-02-15 00:00:00 UTC
Since UTC does not have any time zone transitions, each date-time is unambiguously resolved.
Creates a new Time
instance that corresponds to the number of seconds
and nanoseconds elapsed from epoch (0001-01-01 00:00:00.0 UTC
)
in UTC.
Valid range for seconds is 0..315_537_897_599
.
For nanoseconds it is 0..999_999_999
.
Creates a new Time
instance representing the current time from the
system clock in UTC.
Class Method Detail
Returns the number of days in month (value range: 1..12
) taking account
of the year.
The returned value is either 28
, 29
, 30
or 31
depending on the
month and whether year is leap.
Time.days_in_month(2016, 2) # => 29
Time.days_in_month(1990, 4) # => 30
Returns the number of days in year.
A normal year has 365
days, a leap year 366
days.
Time.days_in_year(1990) # => 365
Time.days_in_year(2004) # => 366
Returns true
if year is a leap year in the proleptic Gregorian
calendar.
Measures the execution time of block.
The measurement relies on the monotonic clock and is not
affected by fluctuations of the system clock (see #monotonic
).
elapsed_time = Time.measure do
# operation that takes 20 milliseconds
end
elapsed_time # => 20.milliseconds (approximately)
Returns a reading from the monotonic clock to measure elapsed time.
Values from the monotonic clock and wall clock are not comparable.
This method does not return a Time
instance but a Time::Span
amounting
to the number of nanoseconds elapsed since the unspecified starting point
of the monotonic clock.
The returned values are strictly linearly increasing.
This clock should be independent from discontinuous jumps in the system time, such as leap seconds, time zone adjustments or manual changes to the computer's clock.
Subtracting two results from this method equals to the time elapsed between both readings:
start = Time.monotonic
# operation that takes 20 milliseconds
elapsed = Time.monotonic - start # => 20.milliseconds (approximately)
# operation that takes 50 milliseconds
elapsed_total = Time.monotonic - start # => 70.milliseconds (approximately)
The execution time of a block can be measured using .measure
.
Parse datetime format specified by ISO 8601.
This is similar to .parse_rfc3339
but RFC 3339 defines a more strict format.
In ISO 8601 for examples, field delimiters (#-
, :
) are optional.
Use #to_rfc3339
to format a Time
according to .
Instance Method Detail
Returns a copy of this Time
with span added.
It adds the number of months with overflow increasing the year. If the resulting day-of-month would be invalid, it is adjusted to the last valid day of the moneth.
For example, adding 1.month
to 2007-03-31
would result in the invalid
date 2007-04-31
which will be adjusted to 2007-04-30
.
This operates on the local time-line, such that the local date-time represenations of month and year are increased by the specified amount.
If the resulting date-time is ambiguous due to time zone transitions, a correct time will be returned, but it does not guarantee which.
Returns a Time::Span
amounting to the duration between other and self
.
The time span is negative if self
is before other.
The duration amounts to the actual time elapsed between both instances, on the instant time-line. The difference between local date-time representations may equal to a different duration, depending on time zone transitions.
Returns a copy of this Time
with span subtracted.
It adds the number of months with overflow decreasing the year. If the resulting day-of-month would be invalid, it is adjusted to the last valid day of the moneth.
For example, subtracting 1.month
from 2007-05-31
would result in the invalid
date 2007-04-31
which will be adjusted to 2007-04-30
.
This operates on the local time-line, such that the local date-time represenations of month and year are decreased by the specified amount.
If the resulting date-time is ambiguous due to time zone transitions, a correct time will be returned, but it does not guarantee which.
Compares this Time
with other.
The comparison is based on the instant time-line, even if the local date-time representation (wall clock) would compare differently.
To ensure the comparison is also true for local wall clock, both date-times need to be transforemd to the same time zone.
Compares this Time
with other for equality.
Two instances are considered equal if they represent the same date-time in the instant time-line, even if they show a different local date-time.
time_de = Time.new(2018, 3, 8, 22, 5, 13, location: Time::Location.load("Europe/Berlin"))
time_ar = Time.new(2018, 3, 8, 18, 5, 13, location: Time::Location.load("America/Buenos_Aires"))
time_de == time_ar # => true
# both times represent the same instant:
time_de.to_utc # => 2018-03-08 21:05:13 UTC
time_ar.to_utc # => 2018-03-08 21:05:13 UTC
Returns a copy of this Time
with the number of seconds and
nanoseconds added.
Positive values result in a later time, negative values in an earlier time.
This operates on the instant time-line, such that adding the eqivalent of one hour will always be a duration of one hour later. The local date-time representation may change by a different amount, depending on time zone transitions.
Overflow in nanoseconds will be transferred to seconds.
There is no explicit limit on the input values but the addition must result
in a valid time between 0001-01-01 00:00:00.0
and
9999-12-31 23:59:59.999_999_999
. Otherwise ArgumentError
is raised.
Returns a copy of this Time
representing the beginning of the day.
Returns a copy of this Time
representing the beginning of the hour.
Returns a copy of this Time
representing the beginning of the minute.
Returns a copy of this Time
representing the beginning of the month.
Returns a copy of this Time
representing the beginning of the quarter.
Returns a copy of this Time
representing the beginning of the seconds.
This essentially scaps off nanoseconds
.
Returns a copy of this Time
representing the beginning of the semester.
Returns a copy of this Time
representing the beginning of the week.
TODO Ensure correctness in local time-line.
Returns a copy of this Time
representing the beginning of the year.
Returns a copy of this Time
representing the end of the day.
Returns a copy of this Time
representing the end of the hour.
Returns a copy of this Time
representing the end of the month.
Returns a copy of this Time
representing the end of the quarter.
Returns a copy of this Time
representing the end of the semester.
Returns a copy of this Time
representing the end of the week.
TODO Ensure correctness in local time-line.
Returns a copy of this Time
representing the end of the year.
Returns a copy of this Time
representing midday (12:00
) of the same day.
Returns a copy of self
with time-of-day components (hour, minute, second,
nanoseconds) set to zero.
This equals #at_beginning_of_day
or
Time.new(year, month, day, 0, 0, 0, nanoseconds: 0, location: location)
.
Returns the day of the year.
The value range is 1..365
in normal yars and 1..366
in leap years.
Returns the number of seconds since the Unix epoch
(1970-01-01 00:00:00 UTC
).
time = Time.utc(2016, 1, 12, 3, 4, 5)
time.epoch # => 1452567845
Returns the number of seconds since the Unix epoch
(1970-01-01 00:00:00 UTC
) as Float64
with nanosecond precision.
time = Time.utc(2016, 1, 12, 3, 4, 5, nanosecond: 678_000_000)
time.epoch_f # => 1452567845.678
Returns the number of milliseconds since the Unix epoch
(1970-01-01 00:00:00 UTC
).
time = Time.utc(2016, 1, 12, 3, 4, 5, nanosecond: 678_000_000)
time.epoch_ms # => 1452567845678
Returns true
if the day of week is Friday.
See #day_of_week
for details.
Returns a copy of this Time
representing the same instant observed in
location.
This method changes the time zone and retains the instant, which will usually result in a different representation of local date-time (unless both locations have the same offset).
Ambiguous time zone transitions such as gaps and overlaps have no effect on the result because it retains the same instant.
time_de = Time.new(2018, 3, 8, 22, 5, 13, location: Time::Location.load("Europe/Berlin"))
time_ar = time_de.in Time::Location.load("America/Buenos_Aires")
time_de # => 2018-03-08 22:05:13 +01:00 Europe/Berlin
time_ar # => 2018-03-08 18:05:13 -03:00 America/Buenos_Aires
Prints this Time
to io.
The local date-time is formatted as date string YYYY-MM-DD HH:mm:ss.nnnnnnnnn +ZZ:ZZ:ZZ
.
Nanoseconds are omitted if with_nanoseconds is false
.
When the location is UTC
, the offset is omitted. Offset seconds are omitted if 0
.
The name of the location is appended unless it is a fixed zone offset.
Returns true
if #location
equals to the local time zone
(Time::Location.local
).
Since the system's settings may change during a programm's runtime, the result may not be identical between different invocations.
Returns true
if the day of week is Monday.
See #day_of_week
for details.
Returns the offset from UTC (in seconds) in effect in #location
at
this instant.
Returns true
if the day of week is Saturday.
See #day_of_week
for details.
Returns true
if the day of week is Sunday.
See #day_of_week
for details.
Returns true
if the day of week is Thursday.
See #day_of_week
for details.
Returns the duration between this Time
and midnight of the same day.
This is equivalent to creating a Time::Span
from the time-of-day fields:
time.time_of_day == Time::Span.new(time.hour, time.minute, time.second, time.nanosecond)
``
Emits a string formated according to RFC 3339 (ISO 8601 profile).
The JSON format itself does not specify a time data type, this method just assumes that a string holding a RFC 3339 time format will be interpreted as a time value.
See #from_json
for reference.
Returns a copy of this Time
representing the same instant in the local
time zone (Time::Location.local
).
See #in
for details.
Format this time using the format specified by RFC 2822.
Time.new(2016, 2, 15).to_rfc2822 # => "Mon, 15 Feb 2016 00:00:00 -0400"
Format this time using the format specified by RFC 2822 into the given io.
Format this time using the format specified by RFC 3339 (ISO 8601 profile).
Time.new(2016, 2, 15).to_rfc3339 # => "2016-02-15T00:00:00+00:00"
ISO 8601 allows some freedom over the syntax and RFC 3339 exercises that freedom to rigidly define a fixed format intended for use in internet protocols and standards.
Formats this Time
according to the pattern in format.
See Time::Format
for details.
time = Time.new(2016, 4, 5)
time.to_s("%F") # => "2016-04-05"
Prints this Time
to io.
The local date-time is formatted as date string YYYY-MM-DD HH:mm:ss +ZZ:ZZ:ZZ
.
Nanoseconds are always omitted.
When the location is UTC
, the offset is replaced with the string UTC
.
Offset seconds are omitted if 0
.
Formats this Time
according to the pattern in format to the given io.
See Time::Format
for details.
Returns a copy of this Time
representing the same instant in UTC
(Time::Location::UTC
).
See #in
for details.
Returns true
if the day of week is Tuesday.
See #day_of_week
for details.
Returns true
if the day of week is Wednesday.
See #day_of_week
for details.