<commit_before>=begin pod

=TITLE class DateTime

=SUBTITLE Calendar date with time

    class DateTime does Dateish { ... }

For handling points in civil time, a C<DateTime> object stores year, month,
day, hour, minute (all L<Int|/type/Int>), second (potentially fractional) and
a time zone.

It provides methods for calculating with date and time.

C<DateTime> methods are immutable; if you are tempted to modify one, create a
modified copy instead.

Time zones are handled as L<Integers|/type/Int> in B<seconds> offset from UTC,
not by time zone name.

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

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

=head1 Methods

=head2 method new

Defined as:

    multi method new(Int :$year!, Int :$month, Int :$day,
                     Int :$hour, Int :$minute, :$second
                     :$timezone, :&formatter)
    multi method new(Date :$date!,
                     Int :$hour, Int :$minute, :$second
                     :$timezone=0, :&formatter)
    multi method new(Instant:D $i,  :$timezone=0, :&formatter)
    multi method new(Int:D $posix,  :$timezone=0, :&formatter)
    multi method new(Str:D $format, :$timezone=0, :&formatter)

Usage:

    $datetime = DateTime.new(YEAR, MONTH?, DAY?, HOUR? MINUTE?, SECOND?,
    TIMEZONE?, FORMATTER?)
    $datetime = DateTime.new(DATE, HOUR?, MINUTE?, SECOND?, TIMEZONE?,
    FORMATTER?)
    $datetime = DateTime.new(INSTANT, TIMEZONE?, FORMATTER?)
    $datetime = DateTime.new(TIMESTAMP, TIMEZONE?, FORMATTER?)
    $datetime = DateTime.new(FORMAT, TIMEZONE?, FORMATTER?)

Creates a new C<DateTime> object. One option for creating a new DateTime object
is from the components (year, month, day, hour, ...) separately. Another is to
pass a L<Date|/type/Date> object for the date component, and specify the time
component-wise. Yet another is to obtain the time from an
L<Instant|/type/Instant>, and only supply the time zone and formatter. Or
instead of an Instant you can supply an L<Int|/type/Int> as a UNIX timestamp,
or a C<Str|/type/Str> formatted as C<yyyy-mm-ddThh:mm::ssZ> or
C<yyyy-mm-ddThh:mm:ss+0100> (ISO 8601 timestamp notation).

An invalid input string throws an exception of type
L<X::Temporal::InvalidFormat>. If you supply a string that includes a time
zone and supply the C<timezone> named argument, an exception of type
L<X::DateTime:TimezoneClash> is thrown.

=head2 method now

Defined as:

    method now(:$timezone=*$TZ, &formatter) returns DateTime:D

Usage:

    DateTime.now

Creates a new C<DateTime> object from the current system time, optionally with
a different timezone than the default attached.

=head2 method clone

Defined as:

    method clone(:$year, :$month, :$day, :$hour, :$minute, :$second,
                 :$timezone, :&formatter)<commit_msg>Fix typo. Closes #168<commit_after>=begin pod

=TITLE class DateTime

=SUBTITLE Calendar date with time

    class DateTime does Dateish { ... }

For handling points in civil time, a C<DateTime> object stores year, month,
day, hour, minute (all L<Int|/type/Int>), second (potentially fractional) and
a time zone.

It provides methods for calculating with date and time.

C<DateTime> methods are immutable; if you are tempted to modify one, create a
modified copy instead.

Time zones are handled as L<Integers|/type/Int> in B<seconds> offset from UTC,
not by time zone name.

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

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

=head1 Methods

=head2 method new

Defined as:

    multi method new(Int :$year!, Int :$month, Int :$day,
                     Int :$hour, Int :$minute, :$second
                     :$timezone, :&formatter)
    multi method new(Date :$date!,
                     Int :$hour, Int :$minute, :$second
                     :$timezone=0, :&formatter)
    multi method new(Instant:D $i,  :$timezone=0, :&formatter)
    multi method new(Int:D $posix,  :$timezone=0, :&formatter)
    multi method new(Str:D $format, :$timezone=0, :&formatter)

Usage:

    $datetime = DateTime.new(YEAR, MONTH?, DAY?, HOUR? MINUTE?, SECOND?,
    TIMEZONE?, FORMATTER?)
    $datetime = DateTime.new(DATE, HOUR?, MINUTE?, SECOND?, TIMEZONE?,
    FORMATTER?)
    $datetime = DateTime.new(INSTANT, TIMEZONE?, FORMATTER?)
    $datetime = DateTime.new(TIMESTAMP, TIMEZONE?, FORMATTER?)
    $datetime = DateTime.new(FORMAT, TIMEZONE?, FORMATTER?)

Creates a new C<DateTime> object. One option for creating a new DateTime object
is from the components (year, month, day, hour, ...) separately. Another is to
pass a L<Date|/type/Date> object for the date component, and specify the time
component-wise. Yet another is to obtain the time from an
L<Instant|/type/Instant>, and only supply the time zone and formatter. Or
instead of an Instant you can supply an L<Int|/type/Int> as a UNIX timestamp,
or a C<Str|/type/Str> formatted as C<yyyy-mm-ddThh:mm::ssZ> or
C<yyyy-mm-ddThh:mm:ss+0100> (ISO 8601 timestamp notation).

An invalid input string throws an exception of type
L<X::Temporal::InvalidFormat>. If you supply a string that includes a time
zone and supply the C<timezone> named argument, an exception of type
L<X::DateTime:TimezoneClash> is thrown.

=head2 method now

Defined as:

    method now(:$timezone=$*TZ, &formatter) returns DateTime:D

Usage:

    DateTime.now

Creates a new C<DateTime> object from the current system time, optionally with
a different timezone than the default attached.

=head2 method clone

Defined as:

    method clone(:$year, :$month, :$day, :$hour, :$minute, :$second,
                 :$timezone, :&formatter)
{'fraction_non_alphanumeric': 0.12127107652399481, 'fraction_numerical': 0.0312905317769131, 'mean_word_length': 3.3782824698367637, 'pattern_counts': {'":': 0, '<': 35, '<?xml version=': 0, '>': 47, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5963997', 'n_tokens_mistral': 2191, 'n_tokens_neox': 1977, 'n_words': 706}