view release on metacpan or  search on metacpan

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

    $dt->set_day(1);
    $dt->set_hour(0);
    $dt->set_minute(0);
    $dt->set_second(0);
    $dt->set_nanosecond(0);
    $dt->set_time_zone('America/New_York');
    $dt->set_locale('en-US');  # sets a new DateTime::Locale::FromCLDR object
    $dt->set_formatter( $formatter );
    $dt->truncate( to => 'day' );   # 'year','month','week','day','hour','minute','second'

    # Works for second, minute, hour, day, week, local_week, month, quarter,
    # year, decade, century
    $dt->end_of( 'month' );
    say $dt;  # 2026-04-30T23:59:59.999999999
    $dt->start_of( 'month' );
    say $dt;  # 2026-04-01T00:00:00

    # Comparison
    my @sorted = sort { $a <=> $b } @datetimes;  # overloaded <=>
    DateTime::Lite->compare( $dt1, $dt2 );       # -1, 0, 1
    DateTime::Lite->compare_ignore_floating( $dt1, $dt2 );
    $dt->is_between( $lower, $upper );

    # Class-level settings
    DateTime::Lite->DefaultLocale('fr-FR');
    my $class = $dt->duration_class;  # 'DateTime::Lite::Duration'

    # Constants
    DateTime::Lite::INFINITY();        # +Inf
    DateTime::Lite::NEG_INFINITY();    # -Inf
    DateTime::Lite::NAN();             # NaN
    DateTime::Lite::MAX_NANOSECONDS(); # 1_000_000_000
    DateTime::Lite::SECONDS_PER_DAY(); # 86400

    # Error handling
    my $dt2 = DateTime::Lite->new( %bad_args ) ||
        die( DateTime::Lite->error );
    # Chaining: bad calls return a NullObject so the chain continues safely;
    # check the return value of the last call in the chain.
    my $result = $dt->some_method->another_method ||
        die( $dt->error );

=head1 VERSION

    v0.7.3

=head1 DESCRIPTION

C<DateTime::Lite> is a lightweight, memory-efficient, drop-in replacement for L<DateTime> with the following design goals:

=over 4

=item Low dependency footprint

Runtime dependencies are limited to: L<DateTime::Lite::TimeZone> (bundled SQLite timezone data, with automatic fallback to L<DateTime::TimeZone> if L<DBD::SQLite> is unavailable), L<DateTime::Locale::FromCLDR> (locale data via L<Locale::Unicode::Data...

The heavy L<Specio>, L<Params::ValidationCompiler>, L<Try::Tiny>, and C<namespace::autoclean> are eliminated entirely.

=item Low memory footprint

C<DateTime> loads a cascade of modules which inflates C<%INC> significantly. C<DateTime::Lite> avoids this via selective lazy loading.

=item Accurate timezone data from TZif binaries

C<DateTime::TimeZone> derives its zone data from the IANA Olson I<source> files (C<africa>, C<northamerica>, etc.) via a custom text parser (C<DateTime::TimeZone::OlsonDB>), then pre-generates one C<.pm> file per zone at distribution build time. This...

C<DateTime::Lite::TimeZone> instead compiles the IANA source files with C<zic(1)>, which is the official IANA compiler, and reads the resulting TZif binary files directly, following L<RFC 9636|https://www.rfc-editor.org/rfc/rfc9636> (TZif versions 1 ...

Crucially, the POSIX footer TZ string embedded in every TZif v2+ file, such as C<EST5EDT,M3.2.0,M11.1.0>, is extracted and stored in the SQLite database.

This string encodes the recurring DST rule for all dates beyond the last explicit transition. At runtime, C<DateTime::Lite::TimeZone> evaluates the footer rule via an XS implementation of the IANA C<tzcode> reference algorithm (see C<dtl_posix.h>, de...

=item XS-accelerated hot paths

The XS layer covers all CPU-intensive calendar arithmetic (C<_rd2ymd>, C<_ymd2rd>, C<_seconds_as_components>, all leap-second helpers), plus new functions not in the original: C<_rd_to_epoch>, C<_epoch_to_rd>, C<_normalize_nanoseconds>, and C<_compar...

=item Compatible API

The public API mirrors L<DateTime> as closely as possible, so existing code using C<DateTime> should work with C<DateTime::Lite> as a drop-in replacement.

=item Full Unicode CLDR / BCP 47 locale support

C<DateTime> is limited to the set of pre-generated C<DateTime::Locale::*> modules, one per locale. C<DateTime::Lite> accepts any valid Unicode CLDR / BCP 47 locale tag, including complex forms with Unicode extensions (C<-u->), transform extensions (C...

    my $dt = DateTime::Lite->now( locale => 'en' );    # simple form
    my $dt = DateTime::Lite->now( locale => 'en-GB' ); # simple form
    # And more complex forms too
    my $dt = DateTime::Lite->now( locale => 'he-IL-u-ca-hebrew-tz-jeruslm' );
    my $dt = DateTime::Lite->now( locale => 'ja-Kana-t-it' );
    my $dt = DateTime::Lite->now( locale => 'ar-SA-u-nu-latn' );

Locale data is resolved dynamically by L<DateTime::Locale::FromCLDR> via L<Locale::Unicode::Data>, so tags like C<he-IL-u-ca-hebrew-tz-jeruslm> or C<ja-Kana-t-it> work transparently without any additional installed modules.

Additionally, if the locale tag carries a L<Unicode timezone extension|Locale::Unicode/"Unicode extensions"> (C<-u-tz->), and no explicit C<time_zone> argument is provided to the constructor, C<DateTime::Lite> will automatically resolve the correspon...

    # time_zone is inferred as 'Asia/Jerusalem' from the -u-tz-jeruslm extension
    my $dt = DateTime::Lite->now( locale => 'he-IL-u-ca-hebrew-tz-jeruslm' );
    say $dt->time_zone;            # Asia/Jerusalem
    say $dt->time_zone_long_name;  # Asia/Jerusalem

An explicit C<time_zone> argument always takes priority over the locale extension.

=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