view release on metacpan or  search on metacpan

lib/DateTime/Lite.pm  view on Meta::CPAN

=item No die() in normal operation

Following the L<Module::Generic> / L<Locale::Unicode> error-handling philosophy, C<DateTime::Lite> never calls C<die()> in normal error paths.

Instead it sets a L<DateTime::Lite::Exception> object and returns C<undef> in scalar context, or an empty list in list context.

However, if you really want this module to C<die> upon error, you can pass the C<fatal> option with a true value upon object instantiation.

=back

=head1 KNOWN DIFFERENCES FROM DateTime

=over 4

=item Validation

C<DateTime> uses L<Specio> / L<Params::ValidationCompiler> for constructor validation. C<DateTime::Lite> performs equivalent checks manually. Error messages are similar but not identical.

=item No warnings::register abuse

C<DateTime::Lite> uses C<warnings::enabled> consistently and does not depend on the C<warnings::register> mechanism for user-facing output.

=back

=head1 METHODS NOT IMPLEMENTED

None at this time. If you encounter a method missing from the L<DateTime> API, please file a report.

=head1 CONSTRUCTORS

=head2 new

Accepted parameters are:

=over 4

=item * C<year> (required)

=item * C<month>

=item * C<day>

=item * C<hour>

=item * C<minute>

=item * C<second>

=item * C<nanosecond>

=item * C<time_zone>

The time zone for the datetime. Accepts:

=over 8

=item * A zone name string, such as C<Asia/Tokyo>, a fixed-offset string such as C<+09:00>, C<UTC>, C<floating>, or C<local>.

=item * A L<DateTime::Lite::TimeZone> object.

=item * A hash reference whose keys are passed directly to L<DateTime::Lite::TimeZone/new>. This allows passing options that are not available on the string form, such as C<< extended => 1 >> (to resolve timezone abbreviations such as C<JST> or C<CET...

    time_zone => { name => 'JST', extended => 1 }
    time_zone => { latitude => 35.658558, longitude => 139.745504 }

=back

If omitted, and the C<locale> argument carries a BCP47 C<-u-tz-> extension, such as C<he-IL-u-ca-hebrew-tz-jeruslm>, the corresponding IANA canonical timezone is resolved automatically. If neither is provided, the default floating timezone is used (o...

=item * C<locale>

Any valid locale as defined by the Unicode CLDR (Common Locale Data Repository), and BCP47. See L<Locale::Unicode>

=item * C<formatter>

=item * C<fatal>

=back

Returns the new object upon success, or sets an L<error|DateTime::Lite::Exception> and returns C<undef> in scalar context, or an empty list in list context. In chaining (object context), it returns a dummy object (C<DateTime::Lite::Null>) to avoid th...

=head2 from_day_of_year

    my $dt2 = DateTime::Lite->from_day_of_year(
        year        => 2026,
        day_of_year => 100,
        time_zone   => 'UTC',
        locale      => 'fr-FR',
    );

Constructs from a year and day-of-year (1-366).

Returns the new object upon success, or sets an L<error|DateTime::Lite::Exception> and returns C<undef> in scalar context, or an empty list in list context. In chaining (object context), it returns a dummy object (C<DateTime::Lite::Null>) to avoid th...

=head2 from_epoch

    my $dt = DateTime::Lite->from_epoch(
        epoch     => 1775769030,
        time_zone => 'Asia/Tokyo',
        locale    => 'ja-JP',
        formatter => $formatter,
    );

Constructs from a Unix epoch value (integer or float). Non-integer values are rounded to the nearest microsecond.

It accepts the C<time_zone>, C<locale>, and C<formatter> parameters.

The returned object will be in the C<UTC> time zone.

If you provide the C<time_zone> argument, it will be applied I<after> the object is instantiated. Thus, the epoch value provided will always be set in the UTC time zone.

For example:

    my $dt = DateTime->from_epoch(
        epoch     => 0,
        time_zone => 'Asia/Tokyo'
    );
    say $dt; # Prints 1970-01-01T09:00:00 as Asia/Tokyo is +09:00 from UTC.
    $dt->set_time_zone('UTC');
    say $dt; # Prints 1970-01-01T00:00:00