class DateTime
Calendar date with time
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 and time.
DateTime
methods are immutable; if you are tempted to modify one, create a modified copy instead.
Time zones are handled as Integers 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)
Methods
method new
Defined as:
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(Int , :=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 an Int 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); # OUTPUT: «2016-08-10T18:26:23Z»= DateTime.new("2015-01-01T03:17:30+0500") # Formatted string
method now
Defined as:
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
Defined as:
method clone(:, :, :, :, :, :, :, :)
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
Defined as:
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
Defined as:
method hour(DateTime: --> Int)
Returns the hour component.
say DateTime.new('2012-02-29T12:34:56Z').hour; # OUTPUT: «12»
method minute
Defined as:
method minute(DateTime: --> Int)
Returns the minute component.
say DateTime.new('2012-02-29T12:34:56Z').minute; # OUTPUT: «34»
method second
Defined as:
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
Defined as:
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
Defined as:
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
Defined as:
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
Defined as:
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
Defined as:
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
Defined as:
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
Defined as:
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 posix
Defined as:
method posix(Bool: = False --> Int)
Returns the date and time as a POSIX/UNIX timestamp (seconds since the Epoch, 1st January 1970 UTC).
If $ignore-timezone
is True
, the DateTime
object will be treated as if the time zone offset is zero.
say DateTime.new('2015-12-24T12:23:00Z').posix; # OUTPUT: «1450959780»
method later
Defined as:
method later(DateTime: *)
Returns a DateTime object based on the current one, but with a time delta applied. The time delta can be passed as a named argument where the argument name is the unit.
Unless the given unit is second
or seconds
, the given value will be converted to an Int.
Allowed units are second
, seconds
, minute
, minutes
, hour
, hours
, day
, days
, week
, weeks
, month
, months
, year
, years
. Please note that the plural forms can only be used with the later
and earlier
methods.
The :2nd
form of colonpairs can be used as a compact and self-documenting way of specifying the delta:
say DateTime.new('2015-12-24T12:23:00Z').later(:2years);# OUTPUT: «2017-12-24T12:23:00Z»
Since addition of several different time units is not commutative, only one unit may be passed.
my = DateTime.new(date => Date.new('2015-02-27'));say .later(month => 1).later(:2days); # OUTPUT: «2015-03-29T00:00:00Z»say .later(days => 2).later(:1month); # OUTPUT: «2015-04-01T00:00:00Z»say .later(days => 2).later(:month); # same, as +True === 1
If the resultant time has value 60
for seconds, yet no leap second actually exists for that time, seconds will be set to 59
:
say DateTime.new('2008-12-31T23:59:60Z').later: :1day;# OUTPUT: «2009-01-01T23:59:59Z»
Negative offsets are allowed, though earlier is more idiomatic for that.
method earlier
Defined as:
method earlier(DateTime: *)
Returns a DateTime object based on the current one, but with a time delta towards the past applied. Unless the given unit is second
or seconds
, the given value will be converted to an Int. See method later for usage.
my = DateTime.new(date => Date.new('2015-02-27'));say .earlier(month => 1).earlier(:2days); # OUTPUT: «2015-01-25T00:00:00Z»
If the resultant time has value 60
for seconds, yet no leap second actually exists for that time, seconds will be set to 59
:
say DateTime.new('2008-12-31T23:59:60Z').earlier: :1day;# OUTPUT: «2008-12-30T23:59:59Z»
Negative offsets are allowed, though later is more idiomatic for that.
method truncated-to
Defined as:
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
Defined as:
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
Defined as:
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
Defined as:
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
Defined as:
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
Defined as:
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 sub infix:<-> (DateTime, Duration --> DateTime)multi sub 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 perl 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 sub infix:<+> (DateTime, Duration --> DateTime)multi sub 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:«<=>»
multi sub infix:«<=>»(DateTime \a, DateTime \b --> Order)
Compares the equivalent instant, returns the Order.
say DateTime.now <=> DateTime.now; # OUTPUT: «Less»
sub infix:«cmp»
multi sub infix:«cmp»(DateTime \a, DateTime \b --> Order)
Compares the equivalent instant, returns the Order.
sub infix:«<»
multi sub infix:«<»(DateTime \a, DateTime \b --> Bool)
Compares the equivalent instant, returns a Bool
sub infix:«>»
multi sub infix:«>»(DateTime \a, DateTime \b --> Bool)
Compares the equivalent instant, returns a Bool
sub infix:«<=»
multi sub infix:«<=»(DateTime \a, DateTime \b --> Bool)
Compares the equivalent instant, returns a Bool
sub infix:«>=»
multi sub infix:«>=»(DateTime \a, DateTime \b --> Bool)
Compares the equivalent instant, returns a Bool
sub infix:«==»
multi sub infix:«==»(DateTime \a, DateTime \b --> Bool)
Compares the equivalent instant, returns a Bool
sub infix:«!=»
multi sub infix:«!=»(DateTime \a, DateTime \b --> Bool)
Compares the equivalent instant, returns a Bool
Type Graph
Routines supplied by role Dateish
DateTime does role Dateish, which provides the following routines:
(Dateish) method year
Defined as:
method year(Date: --> Int)
Returns the year of the date.
say Date.new('2015-12-31').year; # OUTPUT: «2015»say DateTime.new(date => Date.new('2015-12-24'), hour => 1).year; # OUTPUT: «2015»
(Dateish) method month
Defined as:
method month(Date: --> Int)
Returns the month of the date (1..12).
say Date.new('2015-12-31').month; # OUTPUT: «12»say DateTime.new(date => Date.new('2015-12-24'), hour => 1).month; # OUTPUT: «12»
(Dateish) method day
Defined as:
method day(Date: --> Int)
Returns the day of the month of the date (1..31).
say Date.new('2015-12-31').day; # OUTPUT: «31»say DateTime.new(date => Date.new('2015-12-24'), hour => 1).day; # OUTPUT: «24»
(Dateish) method formatter
Defined as:
method formatter(Dateish:)
Returns the formatting function which is used for conversion to Str. If none was provided at object construction, a default formatter is used. In that case the method will return a Callable type object.
The formatting function is called by DateTime method Str with the invocant as its only argument.
my = Date.new('2015-12-31'); # (no formatter specified)say .formatter.^name; # OUTPUT: «Callable»my = sub () ;= Date.new('2015-12-31', formatter => );say .formatter.^name; # OUTPUT: «Sub»say ; # OUTPUT: «12/31/2015»
(Dateish) method is-leap-year
Defined as:
method is-leap-year(--> Bool)
Returns True
if the year of the Dateish object is a leap year.
say DateTime.new(:year<2016>).is-leap-year; # OUTPUT: «True»say Date.new("1900-01-01").is-leap-year; # OUTPUT: «False»
(Dateish) method day-of-month
Defined as:
method day-of-month(Date: --> Int)
Returns the day of the month of the date (1..31). Synonymous to the day
method.
say Date.new('2015-12-31').day-of-month; # OUTPUT: «31»say DateTime.new(date => Date.new('2015-12-24'), hour => 1).day-of-month; # OUTPUT: «24»
(Dateish) method day-of-week
Defined as:
method day-of-week(Date: --> Int)
Returns the day of the week, where 1 is Monday, 2 is Tuesday and Sunday is 7.
say Date.new('2015-12-31').day-of-week; # OUTPUT: «4»say DateTime.new(date => Date.new('2015-12-24'), hour => 1).day-of-week; # OUTPUT: «4»
(Dateish) method day-of-year
Defined as:
method day-of-year(Date: --> Int)
Returns the day of the year (1..366).
say Date.new('2015-12-31').day-of-year; # OUTPUT: «365»say DateTime.new(date => Date.new('2015-03-24'), hour => 1).day-of-year; # OUTPUT: «83»
(Dateish) method days-in-month
Defined as:
method days-in-month(Dateish: --> Int)
Returns the number of days in the month represented by the Dateish object:
say Date.new("2016-01-02").days-in-month; # OUTPUT: «31»say DateTime.new(:year<10000>, :month<2>).days-in-month; # OUTPUT: «29»
(Dateish) method week
Defined as:
method week()
Returns a list of two integers: the year, and the week number. This is because at the start or end of a year, the week may actually belong to the other year.
my (, ) = Date.new("2014-12-31").week;say ; # OUTPUT: «2015»say ; # OUTPUT: «1»say Date.new('2015-01-31').week; # OUTPUT: «(2015 5)»
(Dateish) method week-number
Defined as:
method week-number(Date: --> Int)
Returns the week number (1..53) of the date specified by the invocant. The first week of the year is defined by ISO as the one which contains the fourth day of January. Thus, dates early in January often end up in the last week of the prior year, and similarly, the final few days of December may be placed in the first week of the next year.
say Date.new("2014-12-31").week-number; # 1 (first week of 2015)say Date.new("2016-01-02").week-number; # 53 (last week of 2015)
(Dateish) method week-year
Defined as:
method week-year(Date: --> Int)
Returns the week year of the date specified by the invocant. Normally week-year
is equal to Date.year
. Note however that dates early in January often end up in the last week of the prior year, and similarly, the final few days of December may be placed in the first week of the next year.
say Date.new("2015-11-15").week-year; # 2015say Date.new("2014-12-31").week-year; # 2015 (date belongs to the first week of 2015)say Date.new("2016-01-02").week-year; # 2015 (date belongs to the last week of 2015)
(Dateish) method weekday-of-month
Defined as:
method weekday-of-month(Date: --> Int)
Returns a number (1..5) indicating the number of times a particular day-of-week has occurred so far during that month, the day itself included.
say Date.new("2003-06-09").weekday-of-month; # 2 (second Monday of the month)
(Dateish) method yyyy-mm-dd
Defined as:
method yyyy-mm-dd(Date: --> Str)
Returns the date in YYYY-MM-DD
format (ISO 8601)
say Date.new("2015-11-15").yyyy-mm-dd; # OUTPUT: «2015-11-15»say DateTime.new(1470853583).yyyy-mm-dd; # OUTPUT: «2016-08-10»
(Dateish) method daycount
Defined as:
method daycount(Dateish: --> Int)
Returns the number of days from the epoch Nov. 17, 1858 to the day of the invocant. The daycount returned by this method is the MJD, i.e. the Modified Julian Day, which is used routinely by e.g. astronomers, geodesists, scientists and others. The MJD convention is designed to facilitate simplified chronological calculations.
say Date.new('1995-09-27').daycount; # OUTPUT: «49987»
(Dateish) method IO
Defined as:
method IO(Dateish: --> IO::Path)
Returns an IO::Path object representing the stringified value of the Dateish object:
Date.today.IO.say; # OUTPUT: «"2016-10-03".IO»DateTime.now.IO.say; # OUTPUT: «"2016-10-03T11:14:47.977994-04:00".IO»
PORTABILITY NOTE: some operating systems (e.g. Windows) do not permit colons (:
) in filenames, which would be present in IO::Path
created from a DateTime object.