view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    $dt->set_year(2027);
    $dt->set_month(1);
    $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 );

# VERSION

    v0.6.1

# DESCRIPTION

`DateTime::Lite` is a lightweight, memory-efficient, drop-in replacement for [DateTime](https://metacpan.org/pod/DateTime) with the following design goals:

- Low dependency footprint

    Runtime dependencies are limited to: [DateTime::Lite::TimeZone](https://metacpan.org/pod/DateTime%3A%3ALite%3A%3ATimeZone) (bundled SQLite timezone data, with automatic fallback to [DateTime::TimeZone](https://metacpan.org/pod/DateTime%3A%3ATimeZ...

    The heavy [Specio](https://metacpan.org/pod/Specio), [Params::ValidationCompiler](https://metacpan.org/pod/Params%3A%3AValidationCompiler), [Try::Tiny](https://metacpan.org/pod/Try%3A%3ATiny), and `namespace::autoclean` are eliminated entirely.

- Low memory footprint

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

- Accurate timezone data from TZif binaries

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

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

    Crucially, the POSIX footer TZ string embedded in every TZif v2+ file, such as `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, `DateTime::Lite::TimeZone` evaluates the footer rule via an XS implementation of the IANA `tzcode` reference algorithm (see `dtl_posix.h`, d...

- XS-accelerated hot paths

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

- Compatible API

    The public API mirrors [DateTime](https://metacpan.org/pod/DateTime) as closely as possible, so existing code using `DateTime` should work with `DateTime::Lite` as a drop-in replacement.

- Full Unicode CLDR / BCP 47 locale support

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

        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 [DateTime::Locale::FromCLDR](https://metacpan.org/pod/DateTime%3A%3ALocale%3A%3AFromCLDR) via [Locale::Unicode::Data](https://metacpan.org/pod/Locale%3A%3AUnicode%3A%3AData), so tags like `he-IL-u-ca-hebrew-...

    Additionally, if the locale tag carries a [Unicode timezone extension](https://metacpan.org/pod/Locale%3A%3AUnicode#Unicode-extensions) (`-u-tz-`), and no explicit `time_zone` argument is provided to the constructor, `DateTime::Lite` will automat...

        # 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 `time_zone` argument always takes priority over the locale extension.

- No die() in normal operation

    Following the [Module::Generic](https://metacpan.org/pod/Module%3A%3AGeneric) / [Locale::Unicode](https://metacpan.org/pod/Locale%3A%3AUnicode) error-handling philosophy, `DateTime::Lite` never calls `die()` in normal error paths.

    Instead it sets a [DateTime::Lite::Exception](https://metacpan.org/pod/DateTime%3A%3ALite%3A%3AException) object and returns `undef` in scalar context, or an empty list in list context.

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

# KNOWN DIFFERENCES FROM DateTime

- Validation

    `DateTime` uses [Specio](https://metacpan.org/pod/Specio) / [Params::ValidationCompiler](https://metacpan.org/pod/Params%3A%3AValidationCompiler) for constructor validation. `DateTime::Lite` performs equivalent checks manually. Error messages are...

- No warnings::register abuse

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

# METHODS NOT IMPLEMENTED