🔍 ⌘K/ctrl-K

class DateTime

Calendar date with time 
class DateTime 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 Ints in seconds offset from UTC, not by time zone name. 

my $dt = DateTime.new(
    year    => 2015,
    month   => 11,
    day     => 21,
    hour    => 16,
    minute  => 1,
);

say $dt;                            # OUTPUT: «2015-11-21T16:01:00Z␤»
say $dt.later(days => 20);          # OUTPUT: «2015-12-11T16:01:00Z␤»
say $dt.truncated-to('hour');       # OUTPUT: «2015-11-21T16:00:00Z␤»
say $dt.in-timezone(-8 * 3600);     # OUTPUT: «2015-11-21T08:01:00-0800␤»

my $now = DateTime.now(formatter => { sprintf "%02d:%02d", .hour, .minute });
say $now;                           # 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 :$year!, Int :$month = 1, Int :$day = 1,
                 Int :$hour = 0, Int :$minute = 0, :$second = 0,
                 Int :$timezone = 0, :&formatter)
multi method new(Date :$date!,
                 Int :$hour = 0, Int :$minute = 0, :$second = 0,
                 Int :$timezone = 0, :&formatter)
multi method new(Int() $year, Int() $month, Int() $day,
                 Int() $hour, Int $minute, $second,
                 Int() :$timezone = 0, :&formatter)
multi method new(Instant:D $i,  :$timezone=0, :&formatter)
multi method new(Numeric:D $posix,  :$timezone=0, :&formatter)
multi method new(Str:D $format, :$timezone=0, :&formatter)

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 = DateTime.new(year => 2015,
                                month => 1,
                                day => 1,
                                hour => 1,
                                minute => 1,
                                second => 1,
                                timezone => 1);
    $datetime = DateTime.new(date => Date.new('2015-12-24'),
                             hour => 1,
                             minute => 1,
                             second => 1,
                             timezone => 1);
    $datetime = DateTime.new(2015, 1, 1, # First January of 2015
                             1, 1, 1);   # Hour, minute, second with default time zone
    $datetime = DateTime.new(now);                       # Instant.
    # from a Unix timestamp
    say $datetime = DateTime.new(1470853583.3);          # OUTPUT: «2016-08-10T18:26:23.300000Z␤»
    $datetime = 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(:$timezone = $*TZ, :&formatter --> DateTime:D)

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:D: :$year, :$month, :$day, :$hour, :$minute, :$second, :$timezone, :&formatter)

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 { default { put .^name, ': ', .Str } };
    # OUTPUT: «X::OutOfRange: Day out of range. Is: 29, should be in 1..28␤»

method hh-mm-ss 

method hh-mm-ss(DateTime:D: --> Str:D)

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:D: --> Int:D)

Returns the hour component. 

say DateTime.new('2012-02-29T12:34:56Z').hour;      # OUTPUT: «12␤»

method minute 

method minute(DateTime:D: --> Int:D)

Returns the minute component. 

say DateTime.new('2012-02-29T12:34:56Z').minute;     # OUTPUT: «34␤»

method second 

method second(DateTime:D:)

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:D:)

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:D: --> Int:D)

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:D: --> Int:D)

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:D: --> Real:D)

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:D: --> Real:D)

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:D: --> Str:D)

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:D: --> Instant:D)

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:D: --> Instant:D)

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:D: --> Instant:D)

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:D: --> Real:D)

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:D: --> Real:D)

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:D: --> Real:D)

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:D: $ignore-timezone = False --> Int:D)

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:D: $ignore-timezone = False, :$real --> Num:D)

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:D: Cool $unit)

Returns a copy of the invocant, with everything smaller than the specified unit truncated to the smallest possible value. 

my $d = DateTime.new("2012-02-29T12:34:56.946314Z");
    say $d.truncated-to('second');      # OUTPUT: «2012-02-29T12:34:56Z␤»
    say $d.truncated-to('minute');      # OUTPUT: «2012-02-29T12:34:00Z␤»
    say $d.truncated-to('hour');        # OUTPUT: «2012-02-29T12:00:00Z␤»
    say $d.truncated-to('day');         # OUTPUT: «2012-02-29T00:00:00Z␤»
    say $d.truncated-to('month');       # OUTPUT: «2012-02-01T00:00:00Z␤»
    say $d.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:U --> Date:U)
    multi method Date(DateTime:D --> Date:D)

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:D: --> DateTime:D)

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:D: Int(Cool) $timezone = 0 --> DateTime:D)

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:D: --> DateTime:D)

Returns a DateTime object for the same time, but in the local time zone ($*TZ). 

my $*TZ = -3600;
    say DateTime.new('2015-12-24T12:23:00+0200').local; # OUTPUT: «2015-12-24T09:23:00-0100␤»

sub infix:<-> 

multi infix:<-> (DateTime:D, Duration:D --> DateTime:D)
    multi infix:<-> (DateTime:D, DateTime:D --> Duration:D)

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:D, Duration:D --> DateTime:D)
    multi infix:<+> (Duration:D, DateTime:D --> DateTime:D)

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:D \a, DateTime:D \b --> Order:D)

Compares the equivalent instant, returns the Order.

See Also

class int

Native integer

class Allomorph

Dual value number and string

class Any

Thing/object

class AST

Abstract representation of a piece of source code

class atomicint

Integer (native storage at the platform's atomic operation size)

class Block

Code object with its own lexical scope

class CallFrame

Captures the current frame state

class Code

Code object

class Collation

Encapsulates instructions about how strings should be sorted

class Compiler

Information related to the compiler that is being used

class Complex

Complex number

class ComplexStr

Dual value complex number and string

class Cool

Object that can be treated as both a string and number

class CurrentThreadScheduler

Scheduler that synchronously executes code on the current thread

class Date

Calendar date

class Distribution::Hash

Distribution::Hash

class Distribution::Locally

Distribution::Locally

class Distribution::Path

Distribution::Path

class Distribution::Resource

Every one of the resources installed with a distribution

class Duration

Length of time

class Encoding::Registry

Management of available encodings

class FatRat

Rational number (arbitrary-precision)

class ForeignCode

Rakudo-specific class that wraps around code in other languages (generally NQP)

class Format

Convert values to a string given a format specification

class Formatter

Produce Callable for given format specification

class HyperSeq

An object for performing batches of work in parallel with ordered output

class HyperWhatever

Placeholder for multiple unspecified values/arguments

class Instant

Specific moment in time

class Int

Integer (arbitrary-precision)

class IntStr

Dual value integer and string

class Junction

Logical superposition of values

class Label

Tagged location in the source code

class Lock::Async

A non-blocking, non-re-entrant, mutual exclusion lock

class Macro

Compile-time routine

class Method

Member function

class Mu

The root of the Raku type hierarchy.

class Nil

Absence of a value or a benign failure

class Num

Floating-point number

role Numeric

Number or object that can act as a number

class NumStr

Dual value floating-point number and string

class ObjAt

Unique identification for an object

class Parameter

Element of a Signature

class Perl

Perl related information

class Proxy

Item container with custom storage and retrieval

class RaceSeq

Performs batches of work in parallel without respecting original order.

class Raku

Raku related information

package RakuAST

Namespace for holding RakuAST related classes

class RakuAST::Doc::Block

Contains the information of a RakuDoc block

class RakuAST::Doc::Declarator

Contains the declarator docs of a RakuAST object

class RakuAST::Doc::Markup

Contains the information about RakuDoc markup

class RakuAST::Doc::Paragraph

Contains the information about a RakuDoc paragraph

class Rat

Rational number (limited-precision)

class RatStr

Dual value rational number and string

class Routine

Code object with its own lexical scope and return handling

class Routine::WrapHandle

Holds all information needed to unwrap a wrapped routine.

class Scalar

A mostly transparent container used for indirections

class Signature

Parameter list pattern

class Str

String of characters

class StrDistance

Contains the result of a string transformation.

class Sub

Subroutine

class Submethod

Member function that is not inherited by subclasses

class Telemetry

Collect performance state for analysis

class Telemetry::Instrument::Thread

Instrument for collecting Thread data

class Telemetry::Instrument::ThreadPool

Instrument for collecting ThreadPoolScheduler data

class Telemetry::Instrument::Usage

Instrument for collecting getrusage data

class Telemetry::Period

Performance data over a period

class Telemetry::Sampler

Telemetry instrument pod

Subset UInt

Unsigned integer (arbitrary-precision)

class ValueObjAt

Unique identification for value types

class Variable

Object representation of a variable for use in traits

class Version

Module version descriptor

class Whatever

Placeholder for the value of an unspecified argument

class WhateverCode

Code object constructed by Whatever-priming

The Camelia image is copyright 2009 by Larry Wall. "Raku" is trademark of the Yet Another Society. All rights reserved.