does Dateish
For handling points in civil time, a DateTime
object stores year, month, day, hour, minute (all Int
), second (potentially fractional) and a time zone.
It provides methods for calculating with date (for the Gregorian calendar) and time.
DateTime
methods are immutable; if you are tempted to modify one, create a modified copy instead.
Time zones are handled as Int
s in seconds offset from UTC, not by time zone name.
my = DateTime.new(year => 2015,month => 11,day => 21,hour => 16,minute => 1,);say ; # OUTPUT: «2015-11-21T16:01:00Z»say .later(days => 20); # OUTPUT: «2015-12-11T16:01:00Z»say .truncated-to('hour'); # OUTPUT: «2015-11-21T16:00:00Z»say .in-timezone(-8 * 3600); # OUTPUT: «2015-11-21T08:01:00-0800»my = DateTime.now(formatter => );say ; # 12:45 (or something like that)
Since version 6.d, using synthetic codepoints such as 7̈ will result in an error.
Methods§
method new§
multi method new(Int :!, Int : = 1, Int : = 1,Int : = 0, Int : = 0, : = 0,Int : = 0, :)multi method new(Date :!,Int : = 0, Int : = 0, : = 0,Int : = 0, :)multi method new(Int() , Int() , Int() ,Int() , Int , ,Int() : = 0, :)multi method new(Instant , :=0, :)multi method new(Numeric , :=0, :)multi method new(Str , :=0, :)
Creates a new DateTime
object. One option for creating a new DateTime object is from the components (year, month, day, hour, ...) separately. Another is to pass a Date
object for the date component, and specify the time component-wise. Yet another is to obtain the time from an Instant
, and only supply the time zone and formatter. Or instead of an Instant you can supply a Numeric
as a UNIX timestamp.
You can also supply a Str
formatted in ISO 8601 timestamp notation or as a full RFC 3339 date and time. Strings should be formatted as yyyy-mm-ddThh:mm:ssZ
or yyyy-mm-ddThh:mm:ss+0100
. We are somewhat less restrictive than the ISO 8601 standard, as we allow Unicode digits and mixing of condensed and extended time formats.
An invalid input string throws an exception of type X::Temporal::InvalidFormat
. If you supply a string that includes a time zone and supply the timezone
named argument, an exception of type X::DateTime::TimezoneClash
is thrown.
my = DateTime.new(year => 2015,month => 1,day => 1,hour => 1,minute => 1,second => 1,timezone => 1);= DateTime.new(date => Date.new('2015-12-24'),hour => 1,minute => 1,second => 1,timezone => 1);= DateTime.new(2015, 1, 1, # First January of 20151, 1, 1); # Hour, minute, second with default time zone= DateTime.new(now); # Instant.# from a Unix timestampsay = DateTime.new(1470853583.3); # OUTPUT: «2016-08-10T18:26:23.300000Z»= DateTime.new("2015-01-01T03:17:30+0500") # Formatted string
Since Rakudo release 2022.03, the day
parameter can be a Callable
, with *
returning the last day in the month, and *-n
returning the last but n
.
Since Rakudo release 2022.07, it is also possible to just specify a "YYYY-MM-DD" string to indicate midnight on the given date.
say DateTime.new("2023-03-04"); # OUTPUT: «2023-03-04T00:00:00Z»
method now§
method now(: = , : --> DateTime)
Creates a new DateTime
object from the current system time. A custom formatter and timezone can be provided. The :$timezone
is the offset in seconds from GMT and defaults to the value of $*TZ
variable.
say DateTime.now; # OUTPUT: «2018-01-08T13:05:32.703292-06:00»
Note that one may use the methods shown below chained to the .now
to easily express current values, e.g.,
say DateTime.now.year; # OUTPUT: «2018»
method clone§
method clone(DateTime: :, :, :, :, :, :, :, :)
Creates a new DateTime
object based on the invocant, but with the given arguments overriding the values from the invocant.
say DateTime.new('2015-12-24T12:23:00Z').clone(hour => 0);# OUTPUT: «2015-12-24T00:23:00Z»
Note that this can lead to invalid dates in some circumstances:
say DateTime.new("2012-02-29T12:34:56Z").clone(year => 2015);CATCH ;# OUTPUT: «X::OutOfRange: Day out of range. Is: 29, should be in 1..28»
method hh-mm-ss§
method hh-mm-ss(DateTime: --> Str)
Returns the time represented by the object as a string in 24-hour HH:MM:SS format:
say DateTime.new("2052-02-29T22:34:56Z").hh-mm-ss;# OUTPUT: «22:34:56»
method hour§
method hour(DateTime: --> Int)
Returns the hour component.
say DateTime.new('2012-02-29T12:34:56Z').hour; # OUTPUT: «12»
method minute§
method minute(DateTime: --> Int)
Returns the minute component.
say DateTime.new('2012-02-29T12:34:56Z').minute; # OUTPUT: «34»
method second§
method second(DateTime:)
Returns the second component, including potentially fractional seconds.
say DateTime.new('2012-02-29T12:34:56Z').second; # OUTPUT: «56»say DateTime.new('2012-02-29T12:34:56.789Z').second; # OUTPUT: «56.789»say DateTime.new('2012-02-29T12:34:56,789Z').second; # comma also ok
method whole-second§
method whole-second(DateTime:)
Returns the second component, rounded down to an Int
.
say DateTime.new('2012-02-29T12:34:56.789Z').whole-second; # OUTPUT: «56»
method timezone§
method timezone(DateTime: --> Int)
Returns the time zone in seconds as an offset from UTC.
say DateTime.new('2015-12-24T12:23:00+0200').timezone; # OUTPUT: «7200»
method offset§
method offset(DateTime: --> Int)
Returns the time zone in seconds as an offset from UTC. This is an alias for method timezone.
say DateTime.new('2015-12-24T12:23:00+0200').offset; # OUTPUT: «7200»
method offset-in-minutes§
method offset-in-minutes(DateTime: --> Real)
Returns the time zone in minutes as an offset from UTC.
say DateTime.new('2015-12-24T12:23:00+0200').offset-in-minutes; # OUTPUT: «120»
method offset-in-hours§
method offset-in-hours(DateTime: --> Real)
Returns the time zone in hours as an offset from UTC.
say DateTime.new('2015-12-24T12:23:00+0200').offset-in-hours; # OUTPUT: «2»
method Str§
method Str(DateTime: --> Str)
Returns a string representation of the invocant, as done by the formatter. If no formatter was specified, an ISO 8601 timestamp will be returned.
say DateTime.new('2015-12-24T12:23:00+0200').Str;# OUTPUT: «2015-12-24T12:23:00+02:00»
method Instant§
method Instant(DateTime: --> Instant)
Returns an Instant
object based on the invocant.
say DateTime.new('2015-12-24T12:23:00+0200').Instant; # OUTPUT: «Instant:1450952616»
method Real§
multi method Real(DateTime: --> Instant)
Converts the invocant to Instant
. The same value can be obtained with the Instant
method.
Available as of release 2023.02 of the Rakudo compiler.
method Numeric§
multi method Numeric(DateTime: --> Instant)
Available as of the 2021.09 release of the Rakudo compiler.
Converts the invocant to Instant
. The same value can be obtained with the Instant
method. This allows DateTime
objects to be used directly in arithmetic operations.
method day-fraction§
method day-fraction(DateTime: --> Real)
Returns the instant's time as a fraction of a 24-hour day.
say DateTime.new('2021-12-24T12:23:00.43Z').day-fraction; # OUTPUT: «0.5159772»
Notice the day-fraction
value is the same as the fractional part of the modified-julian-date
for the same instant.
Available as of the 2021.04 Rakudo compiler release.
method julian-date§
method julian-date(DateTime: --> Real)
Returns the Julian date (JD) for the UTC date and time.
say DateTime.new('2021-12-24T12:23:00.43Z').julian-date; # OUTPUT: «2459573.0159772»
The julian-date
starts at zero at the epoch of noon UTC on November 24, 4714 B.C. on the proleptic Gregorian calendar (the calendar in use in much of the world and in international commerce and travel). The JD is used in astronomy to define times of celestial objects transiting the Earth's Prime Meridian. For any instant, it is the sum of the number of whole days and the fraction of a day from that epoch to that instant.
Available as of the 2021.04 Rakudo compiler release.
method modified-julian-date§
method modified-julian-date(DateTime: --> Real)
Returns the Modified Julian Date (MJD) for the UTC date and time.
say DateTime.new('2021-12-24T12:23:00.43Z').modified-julian-date; # OUTPUT: «59572.5159772»
Notice the fractional part of the modified-julian-date
is same value as the day-fraction
for the same instant. Likewise, the integral part of the MJD is the same value as the daycount
for the same instant since they reference the same epoch (November 17, 1858). The MJD is obtained by subtracting the constant 2_400_000.5
from the Julian Date and is used to simplify transformations between civil and astronomical time systems.
Available as of the 2021.04 Rakudo compiler release.
method posix§
method posix(Bool: = False --> Int)
Returns the date and time as a POSIX/UNIX timestamp (integral seconds since the POSIX epoch, 1970-01-01T00:00:00Z).
If $ignore-timezone
is True
, the DateTime
object will be treated as if the time zone offset is zero.
method posix(Bool: = False, : --> Num)
As of release 2022.06 of the Rakudo compiler, it is also possible to specify a :real
named argument. If specified with a true value, a Num
will be returned, allowing for sub-second accuracy of the number of seconds since the POSIX epoch.
say DateTime.new('2015-12-24T12:23:00Z').posix; # OUTPUT: «1450959780»say DateTime.new('2022-06-21T12:23:00.5Z').posix; # OUTPUT: «1655814180»say DateTime.new('2022-06-21T12:23:00.5Z').posix(:real); # OUTPUT: «1655814180.5»
method truncated-to§
method truncated-to(DateTime: Cool )
Returns a copy of the invocant, with everything smaller than the specified unit truncated to the smallest possible value.
my = DateTime.new("2012-02-29T12:34:56.946314Z");say .truncated-to('second'); # OUTPUT: «2012-02-29T12:34:56Z»say .truncated-to('minute'); # OUTPUT: «2012-02-29T12:34:00Z»say .truncated-to('hour'); # OUTPUT: «2012-02-29T12:00:00Z»say .truncated-to('day'); # OUTPUT: «2012-02-29T00:00:00Z»say .truncated-to('month'); # OUTPUT: «2012-02-01T00:00:00Z»say .truncated-to('year'); # OUTPUT: «2012-01-01T00:00:00Z»
DateTimes with fractional seconds can be truncated to whole seconds with .truncated-to('second')
.
method Date§
multi method Date(DateTime --> Date)multi method Date(DateTime --> Date)
Converts the invocant to Date
.
say DateTime.new("2012-02-29T12:34:56.946314Z").Date; # OUTPUT: «2012-02-29»say DateTime.Date; # OUTPUT: «(Date)»
method DateTime§
method DateTime(--> DateTime)
Returns the invocant.
say DateTime.new("2012-02-29T12:34:56.946314Z").DateTime;# OUTPUT: «2012-02-29T12:34:56.946314Z»say DateTime.DateTime;# OUTPUT: «(DateTime)»
method utc§
method utc(DateTime: --> DateTime)
Returns a DateTime object for the same time, but in time zone UTC.
say DateTime.new('2015-12-24T12:23:00+0200').utc;# OUTPUT: «2015-12-24T10:23:00Z»
method in-timezone§
method in-timezone(DateTime: Int(Cool) = 0 --> DateTime)
Returns a DateTime object for the same time, but in the specified $timezone
, which is the offset in seconds from GMT.
say DateTime.new('2015-12-24T12:23:00Z').in-timezone(3600 + 1800); # OUTPUT: «2015-12-24T13:53:00+0130»
Per RFC 7164, leap seconds do not respect local time and always occur at the end of the UTC day:
say DateTime.new: '2017-01-01T00:59:60+01:00'# OUTPUT: «2017-01-01T00:59:60+01:00»
method local§
method local(DateTime: --> DateTime)
Returns a DateTime object for the same time, but in the local time zone ($*TZ
).
my = -3600;say DateTime.new('2015-12-24T12:23:00+0200').local; # OUTPUT: «2015-12-24T09:23:00-0100»
sub infix:<->§
multi infix:<-> (DateTime, Duration --> DateTime)multi infix:<-> (DateTime, DateTime --> Duration)
Takes a DateTime
to subtract from and either a Duration
or another DateTime
object. Returns a new DateTime
object or the Duration
between the two dates, respectively. When subtracting Duration
, time zone of the original DateTime
is preserved in the returned DateTime
object.
say raku DateTime.new(:2016year) - DateTime.new(:2015year):;# OUTPUT: «Duration.new(31536001.0)»say DateTime.new(:2016year, :3600timezone) - Duration.new(31536001.0);# OUTPUT: «2015-01-01T00:00:00+01:00»
sub infix:<+>§
multi infix:<+> (DateTime, Duration --> DateTime)multi infix:<+> (Duration, DateTime --> DateTime)
Takes a DateTime
and increases it by the given Duration
, preserving the time zone.
say DateTime.new(:2015year) + Duration.new(31536001.0);# OUTPUT: «2016-01-01T00:00:00Z»say Duration.new(42) + DateTime.new(:2015year, :3600timezone);# OUTPUT: «2015-01-01T00:00:42+01:00»
sub infix:<cmp>§
multi infix:<cmp>(DateTime \a, DateTime \b --> Order)
Compares the equivalent instant, returns the Order.