view release on metacpan or  search on metacpan

README-ja-JP.md  view on Meta::CPAN

UTCでの構築、`now()`、アクセサ、算術演算、フォーマットについては、`DateTime::Lite`は同等または高速です。算術演算での向上は、XSで高速化されたcloneと、より軽量なバリデーション層にã...

## TimeZone キャッシュモデル

これは理解すべき最も重要なトレードオフです。

**DateTime::TimeZone**は、名前付きゾーンが初めて構築された時点で、IANAタイムゾーン規則一式をRAMに読み込みます（起動約180ms、メモリ上のハッシュ構造約4MB）。その後の`DateTime::TimeZone->new...

**DateTime::Lite::TimeZone**は、同じIANAデータをコンパクトなSQLiteデータベース（配布物に含まれる`tz.sqlite3`）に格納します。あるゾーン名に対する最初の呼び出しではクエリが実行され（約22...

**任意のメモリキャッシュ:**`DateTime::Lite::TimeZone`は、プロセスレベルのメモリキャッシュもopt-inで提供します。これにより、呼び出しごとの速度は`DateTime::TimeZone`と同等、またはそれ以上ã...

    # アプリケーション起動時に一度だけ有効化します:
    DateTime::Lite::TimeZone->enable_mem_cache;

    # または呼び出しごとに指定します:
    my $tz = DateTime::Lite::TimeZone->new(
        name          => 'America/New_York',
        use_cache_mem => 1,
    );

メモリキャッシュが有効な場合、同じゾーンに対する繰り返しの`new()`呼び出しは、単純なハッシュ参照からキャッシュ済みオブジェクトを返し、約0.8µsで完了します。

                              DateTime::TimeZone   DateTime::Lite::TimeZone
    ------                    -----------------   ------------------------
    Cold first call                    ~225 ms                      ~22 ms
    Warm (no mem cache)                  ~2 µs                      ~19 µs
    Warm (mem cache only)                ~2 µs                      ~0.4 µs
    Warm (mem+span+footer cache)         ~2 µs                      ~0.4 µs
    new(named zone, all caches)         ~25 µs                      ~14 µs

実用上の指針:

- 名前付きゾーンを持つdatetimeオブジェクトを構築する長時間稼働サービスでは、起動時に一度`DateTime::Lite::TimeZone->enable_mem_cache`を呼び出してください。
これにより、3層のキャッシュが有効になります。

    - 1. オブジェクトキャッシュ（SQLite構築を回避します）。
    - 2. spanキャッシュ（UTCオフセットクエリを回避します）。
    - 3. footerキャッシュ（POSIX DST規則計算を回避します）。

    すべての層が準備完了してから、`new(named zone)`のコストは約14µsで、`DateTime`（約25µs）より高速です。

- 明示的な制御を好む場合は、個々の`new()`呼び出しごとに`use_cache_mem => 1`を渡すか、1つの`TimeZone`オブジェクトを構築して再利用してください。

        my $tz = DateTime::Lite::TimeZone->new( name => 'America/New_York' );
        my $dt = DateTime::Lite->new( ..., time_zone => $tz );

- バッチ処理（ログ解析、ETL、レポート生成）では、タイムゾーン構築は総I/O時間のごく一部であることが多いため、どの選択肢を選んでも差は体感できません。
- 短命なスクリプトやコマンドラインツールでは、`DateTime::Lite`は起動時間（約120ms 対 約320ms）とメモリ（約19MB 対 約28MB）の両方で有利です。

## ベンチマークの実行

自己完結したベンチマークスクリプトが配布物に含まれています。

    cd DateTime-Lite-vX.X.X
    perl Makefile.PL && make  # XS コードがコンパイルされていることを確認します
    perl -Iblib/lib -Iblib/arch scripts/benchmark.pl

    # より安定した数値を得るために反復回数を増やす:
    perl -Iblib/lib -Iblib/arch scripts/benchmark.pl --iterations 50000

    # 機械可読な CSV 出力:
    perl -Iblib/lib -Iblib/arch scripts/benchmark.pl --csv > results.csv

# 使用方法

## 0起点の数値と1起点の数値

`DateTime::Lite`は、0起点と1起点の数値について単純な規則に従います。

月、月内の日、曜日、年内通算日は**1起点**です。すべての1起点メソッドには`_0`版もあります。たとえば、`day_of_week`は1（月曜日）から7（日曜日）までを返しますが、`day_of_week_0`は0かã‚...

すべての_時刻_関連の値（時、分、秒）は**0起点**です。

年はどちらでもありません。正の値にも負の値にもなり得ます。年0も存在します。

`quarter_0`メソッドはありません。

## Floating DateTimes（タイムゾーン非固定の日時）

新しい`DateTime::Lite`オブジェクトのデフォルトタイムゾーンは、特に明記されていない限り、`floating`タイムゾーンです。この概念はiCal標準に由来します。floating datetimeは特定のタイムゾãƒ...

floating datetimeと実際のタイムゾーンを持つdatetimeの間で日付計算や比較を行うと、結果の妥当性は限定的になります。一方はうるう秒を含み、もう一方は含まないためです。

実際のタイムゾーンを持つオブジェクトを使用する予定がある場合は、floating datetimeと混在させないことを**強く推奨します**。

## ローカルタイムゾーンの判定は遅い場合があります

`$ENV{TZ}`が設定されていない場合、ローカルタイムゾーンの検索には`/etc`以下の複数のファイルを読む必要があることがあります。プログラムの実行中にローカルタイムゾーンが変わらな...

    my $local_tz = DateTime::Lite::TimeZone->new( name => 'local' );

    my $dt = DateTime::Lite->new( ..., time_zone => $local_tz );

`DateTime::Lite::TimeZone`は、このコストを完全に取り除くプロセスレベルのキャッシュも提供しています。

    DateTime::Lite::TimeZone->enable_mem_cache;
    my $dt = DateTime::Lite->new( ..., time_zone => 'local' );

## 遠い将来の DST

現在から数千年後のような非常に遠い将来の日付では、名前付きタイムゾーンを使う`DateTime`は大量のメモリを消費することがあります。これは`DateTime::TimeZone`が、現在からその日付までã...

`DateTime::Lite`はこの問題の影響を受けません。`DateTime::Lite::TimeZone`は、コンパクトなSQLiteデータベースとPOSIX footer TZ文字列を使用して、完全な遷移テーブルを展開することなく、任意の将æ...

## デフォルトタイムゾーンをグローバルに設定する

**警告: これは非常に危険です。自己責任で使用してください。**

次のように設定することで、`DateTime::Lite`に特定のデフォルトタイムゾーンを強制できます。

    $ENV{PERL_DATETIME_DEFAULT_TZ} = 'America/New_York';

これは、使用しているCPANモジュールを含め、`DateTime::Lite`オブジェクトを作成するすべてのコードに影響します。本番環境で使用する前に、依存関係を監査してください。

## 上限と下限

内部的には、日付は`0001-01-01`の前後の日数として保存され、Perl整数に保持されます。利用可能な範囲は、プラットフォームの整数サイズ（`$Config{ivsize}`）に依存します。

- **32ビットPerl:**およそ`+/-1,469,903`年