DateTime-Lite

 view release on metacpan or  search on metacpan

lib/DateTime/Lite/TimeZone/JA.pod  view on Meta::CPAN

=item B<Android>

C<$ENV{TZ}>、次にC<getprop persist.sys.timezone>を試し、その後C<UTC>へフォールバックします。

=item B<VMS>

環境変数C<TZ>、C<SYS$TIMEZONE_RULE>、C<SYS$TIMEZONE_NAME>、C<UCX$TZ>、C<TCPIP$TZ>を確認します。

=item B<Symbian、EPOC、MS-DOS、Mac OS 9以前>

C<$ENV{TZ}>のみを確認します。

=back

ローカルタイムゾーンを判定できない場合は、エラーが設定され、スカラコンテキストではC<undef>、リストコンテキストでは空リストが返されます。チェーン呼び出し（オブジェクトコãƒ...

=item C<latitude>およびC<longitude>引数による座標。

C<name>の代わりに10進度の座標を渡すことで、C<DateTime::Lite::TimeZone>に最も近いIANAタイムゾーンを自動解決させることができます。

    my $tz = DateTime::Lite::TimeZone->new(
        latitude  => 35.658558,
        longitude => 139.745504,
    );
    say $tz->name;  # Asia/Tokyo

解決にはIANAC<zone1970.tab>ファイルに保存された参照座標（正規ゾーンごとに1つの代表点）を使用し、L<haversine great-circle distance|https://en.wikipedia.org/wiki/Haversine_formula>により最も近いゾーンをæ...

C<latitude>はC<-90>からC<90>、C<longitude>はC<-180>からC<180>の範囲でなければなりません。値が範囲外である場合、またはデータベース内に座標付きゾーンが見つからない場合、L<エラーオブジェ...

haversine公式は、データベースがC<-DSQLITE_ENABLE_MATH_FUNCTIONS>付きでコンパイルされている場合、SQLite内で計算されます（SQLite version E<gt>= 3.35.0、L<2021å¹´3月リリース|https://sqlite.org/changes.html>）ã€...

古いシステム、または数学関数が存在しないビルドでは、必要な関数（C<sqrt>、C<sin>、C<cos>、C<asin>）が、初回使用時にL<DBD::SQLite/sqlite_create_function>経由でPerl UDF（User Defined Functions）としてè...

検出はバージョンを考慮して行われます。つまり：

=over 8

=item * SQLite version E<gt>= 3.35.0では、UDFを登録する前に特殊なsystem table C<pragma_function_list>でC<sqrt>を問い合わせ、ネイティブ関数を優先的に使用することを確認します。

=item * SQLite version E<lt>3.35.0では、数学関数がまだ存在しないため、C<pragma_function_list>を問い合わせずにUDFを直接登録します。

=item * SQLite version E<lt>3.16.0では、C<pragma_function_list>はtable-valued functionとして利用できないため、UDFを直接登録します。

=back

UDFはSQLite version E<gt>= 3.0.0のすべてで利用できます。

古いシステムでSQLite 3.31.1が同梱されている場合も、必要な関数（C<sqrt>、C<sin>、C<cos>、C<asin>）は初回使用時にL<DBD::SQLite/sqlite_create_function>経由でPerl UDF（User Defined Functions）として自動登録...

=back

真の値を持つbooleanオプションC<use_cache_mem>は、この呼び出しに対してプロセスレベルのメモリキャッシュを有効化します。設定されると、同じゾーン名（またはそのエイリアス）での以å¾...

    # これらは最初の構築後、キャッシュにヒットします:
    my $tz = DateTime::Lite::TimeZone->new(
        name          => 'America/New_York',
        use_cache_mem => 1,
    );

真の値を持つbooleanオプションC<extended>は、名前が有効なIANAタイムゾーン名として認識されない場合に、略称解決をフォールバックとして有効化します。これは、呼び出し元が外部ソース...

C<extended>が設定され、名前がIANAタイムゾーンとして未知の場合、C<new>は内部的にC<extended>オプションを真にしてC<resolve_abbreviation>を呼び出します。そして単一の曖昧でない候補が見つかっ...

    my $tz = DateTime::Lite::TimeZone->new( name => 'JST', extended => 1 );
    say $tz->name;  # Asia/Tokyo

成功時には新しいオブジェクトを返します。エラー時にはC<error()>によりL<例外オブジェクト|DateTime::Lite::Exception>を設定し、スカラコンテキストではC<undef>、リストコンテキストでは空リã‚...

=head1 メモリキャッシュ

デフォルトでは、L</new>を呼び出すたびにSQLiteクエリを使って新しいオブジェクトを構築します。同じゾーン名でC<DateTime::Lite::TimeZone>オブジェクトを繰り返し構築するアプリケーション向...

B<Layer 1 - オブジェクトキャッシュ>：有効化されている場合、同じゾーン名に対する2回目以降の呼び出しは、データベースを完全に迂回し、元のオブジェクトをハッシュから直接返しまã...

B<Layer 2 - spanキャッシュ>：キャッシュ済みの各TimeZoneオブジェクトは、直近に一致したUTCおよびローカル時刻spanを保存します。C<offset_for_datetime>およびC<offset_for_local_datetime>の呼び出しでは...

B<Layer 3 - POSIX footerキャッシュ>：現在の日付が繰り返しDST規則（POSIX TZ footer文字列）によって管理されるゾーンでは、footer計算の結果が暦日単位でキャッシュされます。DST遷移は年に2回ç™...

これら3層により、C<< DateTime::Lite->new( time_zone => 'America/New_York' ) >>の呼び出しごとのコストは約430 µsから約25 µsまで低下し、C<DateTime>と同等になります。

キャッシュエントリは、L</new>に渡された名前と、エイリアス解決後の正規名をキーにします。そのため、C<US/Eastern>とC<America/New_York>は同じキャッシュ済みオブジェクトへ対応します。

通常の使用では、キャッシュ済みオブジェクトは不変です。すべてのpublic accessorは読み取り専用なので、複数の呼び出し元でオブジェクトを共有しても安全です。

=head2 enable_mem_cache

クラスメソッドです。以後のすべてのL</new>呼び出しに対してメモリキャッシュを有効化します。

    DateTime::Lite::TimeZone->enable_mem_cache;

    # すべての new() 呼び出しは、最初の構築後にキャッシュへヒットします:
    my $tz = DateTime::Lite::TimeZone->new( name => 'America/New_York' );
    my $tz2 = DateTime::Lite::TimeZone->new( name => 'America/New_York' );
    # $tz と $tz2 は同じオブジェクトです

すべてのL</new>呼び出しにC<< use_cache_mem => 1 >>を渡すことと同等ですが、プロセスの存続期間中キャッシュを有効にしたい場合には、こちらの方が便利です。チェーン呼び出しを可能にすã‚...

=head2 disable_mem_cache

クラスメソッドです。メモリキャッシュを無効化し、すべてのキャッシュエントリをクリアします。以後のL</new>呼び出しでは、新しいオブジェクトが構築されます。

    DateTime::Lite::TimeZone->disable_mem_cache;

クラス名を返します。

=head2 clear_mem_cache

クラスメソッドです。キャッシュを無効化せずに空にします。任意のゾーン名に対する次のL</new>呼び出しでは、データベースへ再クエリし、キャッシュを再構築します。

C<tz.sqlite3>データベースが実行時に置き換えられた場合に便利です（通常はまれな操作です）。

    DateTime::Lite::TimeZone->clear_mem_cache;

クラス名を返します。

=head1 METHODS

=head2 aliases

    # エラーも確認します

lib/DateTime/Lite/TimeZone/JA.pod  view on Meta::CPAN

=item C<< < >>

より小さい。その略称の最後の使用が指定日より古いゾーンを返します。

=item C<< <= >>

以下。

=back

演算子C<=>とC<!=>も受け付けますが、それぞれSQLのC<IS>とC<IS NOT>に対応します。タイムスタンプ比較では実用性がなく、推奨されません。

B<値の型>: C<1950-01-01>のようなISO日付文字列は、SQLiteのC<strftime('%s', ...)>によりUnix epochへ変換されます。通常の整数はepoch秒として扱われ、Perlスカラの内部表現に関係なく正しい数値比較ã‚...

特別な値C<current>は、その略称の直近の使用が過去にあり、かつ次に予定されている遷移がまだ発生していないゾーンのみを返します。つまり、現在その略称を使用しているゾーンを意味...

    period => '>1950-01-01'                   # 1950 年以降に最後に使用されたもの（ISO 日付）
    period => ['>1941-01-01', '<1946-01-01']  # 第二次世界大戦中の範囲で最後に使用されたもの
    period => '>1262304000'                   # 2010-01-01 以降に最後に使用されたもの（epoch int）
    period => 'current'                       # 現在有効なもののみ

periodフィルタはextended aliasの結果には適用されません。

=item C<utc_offset>

UTCの東側を正とする整数秒です。同じ文字列から一緒に解析された数値オフセット（たとえばC<%z>トークン由来）が既に分かっている場合に、結果を一致するオフセットの候補へ絞り込ã‚...

=back

成功時には、次のキーを持つハッシュリファレンスの配列リファレンスを返します。

=over 4

=item C<zone_name>

C<Asia/Tokyo>のような正規IANAゾーン名です。

=item C<utc_offset>

このゾーンでこの略称が表す、UTCの東側を正とするUTCオフセット秒数です。extended aliasの結果ではC<undef>です。

=item C<is_dst>

この略称がDST期間を表す場合はC<1>、そうでなければC<0>です。extended aliasの結果ではC<undef>です。

=item C<ambiguous>

IANAの結果では、この略称が複数の異なるUTCオフセットへ対応する場合（C<IST>やC<CST>のような真の曖昧性）はC<1>、すべての候補が同じUTCオフセットを共有する場合はC<0>です。

extended aliasの結果では、候補が複数あり、かつC<is_primary>として印が付いた候補が0個または複数ある場合にC<1>、ちょうど1つの候補がC<is_primary = 1>を持つ場合にC<0>です。

=item C<extended>

結果がC<extended_aliases>テーブル由来であればC<1>、IANA typesテーブル由来であればC<0>です。

=item C<is_active>

IANAの結果（C<extended =E<gt> 0>）にのみ存在します。ゾーンのPOSIX C<TZ> footer文字列が現在もこの略称を参照している場合はC<1>です。これは、そのゾーンが現在の夏時間規則の下でこの略称を...

たとえばC<Europe/Berlin>のfooterはC<CET-1CEST,M3.5.0,M10.5.0/3>なので、C<CET>とC<CEST>はどちらもC<is_active =E<gt> 1>になります。対照的に、C<Europe/Kaliningrad>のfooterはC<EET-2>です。そのため、C<resolve_abbreviat...

このフィールドは主要なソートキーとして使用されるため、C<is_active =E<gt> 1>のゾーンはC<is_active =E<gt> 0>のゾーンより先に表示されます。現在有効なゾーンのみが必要な呼び出し元は、C<gr...

検出はfooter文字列に対する単語境界正規表現です。アルファベット略称は非アルファベット文字に隣接していなければなりません（そのためC<CST>はC<CEST>に一致しません）。また、C<-03>や...

extended aliasの結果には存在しません。そこでは代わりに編集上のC<is_primary>マーカーが順序付けのシグナルになります。

=item C<is_primary>

extended aliasの結果（C<extended =E<gt> 1>）にのみ存在します。複数の候補が一致する場合、C<1>はその略称に対して編集上選ばれた正規ゾーン（たとえばC<BRT>に対するC<America/Sao_Paulo>）を示し、...

CLDR的な意味での正規または優先ゾーン指定が必要な場合は、L<Locale::Unicode::Data>を使用してください。これはタイムゾーンごとにCLDRのC<is_golden>, C<is_primary>, C<is_preferred>フラグを公開してい...

=item C<first_trans_time>

このゾーンでその略称を使用した最も古い遷移のUnix epochです。extended aliasの結果には存在しません。C<is_active>の後、昇順のソートキーとして使用されます。そのため、同じC<is_active>値をæ...

=item C<last_trans_time>

このゾーンでその略称を使用した最も新しい遷移のUnix epochです。extended aliasの結果には存在しません。降順の副次ソートキーとして使用されます。同じC<is_active>および同じC<first_trans_time>...

=back

エラーが発生した場合はL<例外オブジェクト|DateTime::Lite::Exception>を設定し、スカラコンテキストではC<undef>、リストコンテキストでは空リストを返します。例外オブジェクトはその後L</err...

C<EST>ã‚„C<PST>のような多くの略称は、同じUTCオフセットを共有する複数のゾーン名に一致する点に注意してください。これらはdatetime文字列の解析という目的では真に曖昧ではありませんã€...

クラスメソッドまたはインスタンスメソッドです。C<JST>ã‚„C<EST>のようなタイムゾーン略称を、同梱されているC<tz.sqlite3>データベース内のIANAデータに照合し、その略称を過去に使用したã...

IANAの結果は、次の4段階のキーでソートされます。

=over 4

=item 1. C<is_active>の降順：POSIX footerが現在もその略称を参照しているゾーンが、すでに使用しなくなったゾーンより先に表示されます。

=item 2. C<first_trans_time>の昇順：同じC<is_active>値を持つゾーンの中では、その略称を最も早く採用したゾーンが先に表示されます。

=item 3. C<last_trans_time>の降順：最初の2つのキーが同じゾーンの中では、その略称をより最近まで使用していたゾーンが先に表示されます。

=item 4. C<zone_name>の昇順：最後の決定的なタイブレークです。

=back

実際には、C<CEST>のような略称では、現在も有効な中央ヨーロッパのゾーンが先に表示されます（採用日の順）。その後に、C<Europe/Kaliningrad>のように、過去にはCESTを使用していたもののã€...

拡張エイリアスの結果（C<extended =E<gt> 1>によりC<extended_aliases>テーブルへフォールバックした場合）は、異なる順序を使用します。C<is_primary>の降順、次にC<zone_name>の昇順です。下記のL</is_...

必須引数は略称文字列1つです。次の任意のキーワード引数を受け付けます。

=over 4

=item C<extended>

真偽値です。真の場合で、略称がIANA typesテーブルに見つからないとき、このメソッドはC<extended_aliases>テーブルの検索にフォールバックします。これは、C<AFT>, C<AMST>, C<HAEC>のように、実éš...

拡張結果が返される場合、C<utc_offset>とC<is_dst>はC<undef>になります。これは、拡張エイリアステーブルが略称をゾーン名に対応付けるだけだからです。オフセットが必要な場合は、返されã...

=item C<period>

結果を、最も新しい一致する遷移時刻（C<MAX(trans_time)>）が指定された時間範囲内にあるゾーンに限定します。単一の文字列、または複数条件用の文字列の配列リファレンスを受け付けまã...

lib/DateTime/Lite/TimeZone/JA.pod  view on Meta::CPAN

=item C<< < >>

より小さい。最後の使用時刻が、指定された日付より古いゾーンを返します。

=item C<< <= >>

以下。

=back

演算子C<=>とC<!=>も受け付けますが、それぞれSQLのC<IS>とC<IS NOT>に対応します。タイムスタンプ比較では実用的な意味がなく、推奨されません。

B<値の型>: C<1950-01-01>のようなISO日付文字列は、SQLiteのC<strftime('%s', ...)>によってUnix epochに変換されます。単なる整数はepoch秒として扱われ、Perlスカラーの内部表現にかかわらず正しい数å€...

特別な値C<current>は、その略称の最も新しい使用時刻が過去にあり、かつ次に予定されている遷移がまだ発生していないゾーンだけを返します。つまり、現在その略称を使用しているゾー...

    period => '>1950-01-01'                   # 1950 年以降に最後に使用されたもの（ISO 日付）
    period => ['>1941-01-01', '<1946-01-01']  # 第二次世界大戦中の範囲で最後に使用されたもの
    period => '>1262304000'                   # 2010-01-01 以降に最後に使用されたもの（epoch 整数）
    period => 'current'                       # 現在有効なもののみ

期間フィルタは、拡張エイリアスの結果には適用されません。

=item C<utc_offset>

UTCの東方向を正とする整数秒です。結果を、一致するオフセットを持つ候補に絞り込みます。これは、同じ文字列から数値オフセットもすでに解析済みの場合（たとえば同時に解析されã...

=back

成功時には、ハッシュリファレンスの配列リファレンスを返します。各ハッシュには次のキーが含まれます。

=over 4

=item C<zone_name>

C<Asia/Tokyo>のような正規IANAゾーン名です。

=item C<utc_offset>

このゾーンでこの略称が表す、UTCの東方向を正とするUTCオフセット秒です。拡張エイリアスの結果ではC<undef>です。

=item C<is_dst>

この略称が夏時間期間を表す場合はC<1>、そうでない場合はC<0>です。拡張エイリアスの結果ではC<undef>です。

=item C<ambiguous>

IANAの結果では、この略称が複数の異なるUTCオフセットに対応する場合（C<IST>やC<CST>のような真の曖昧性）はC<1>です。すべての候補が同じUTCオフセットを共有する場合はC<0>です。

拡張エイリアスの結果では、候補が複数あり、C<is_primary>が付いた候補が1つもない、または複数ある場合はC<1>です。C<is_primary = 1>の候補がちょうど1つだけある場合はC<0>です。

=item C<extended>

この結果がC<extended_aliases>テーブル由来であればC<1>、IANA typesテーブル由来であればC<0>です。

=item C<is_active>

IANAの結果（C<extended =E<gt> 0>）にのみ存在します。そのゾーンのPOSIX C<TZ> footer文字列が現在もこの略称を参照している場合はC<1>です。これは、そのゾーンが現在の夏時間規則のもとで引き...

たとえば、C<Europe/Berlin>のfooterはC<CET-1CEST,M3.5.0,M10.5.0/3>なので、C<CET>とC<CEST>のどちらもC<is_active =E<gt> 1>になります。一方、C<Europe/Kaliningrad>のfooterはC<EET-2>なので、C<resolve_abbreviation('CEST')>は...

このフィールドは主ソートキーとして使用されるため、C<is_active =E<gt> 1>のゾーンはC<is_active =E<gt> 0>のゾーンより前に表示されます。現在有効なゾーンだけが必要な呼び出し側は、C<grep { $...

検出はfooter文字列に対する単語境界の正規表現で行われます。アルファベット略称は非アルファベット文字に隣接している必要があります（そのためC<CST>はC<CEST>に一致しません）。また...

拡張エイリアスの結果には存在しません。そこでは、編集上のC<is_primary>マーカーが順序付けのシグナルになります。

=item C<is_primary>

拡張エイリアスの結果（C<extended =E<gt> 1>）にのみ存在します。複数の候補が一致する場合、C<1>はこの略称に対して編集上選ばれた正規ゾーンを示します（たとえばC<BRT>に対するC<America/Sao...

CLDR的な意味での正規または優先ゾーン指定が必要な場合は、L<Locale::Unicode::Data>を使用してください。このモジュールは、タイムゾーンごとにCLDRのC<is_golden>, C<is_primary>, C<is_preferred>フラグ...

=item C<first_trans_time>

このゾーンでその略称を使用した最も古い遷移のUnix epochです。拡張エイリアスの結果には存在しません。C<is_active>の後に昇順のソートキーとして使用されるため、同じC<is_active>値を持つ...

=item C<last_trans_time>

このゾーンでその略称を使用した最も新しい遷移のUnix epochです。拡張エイリアスの結果には存在しません。二次ソートキーとして降順で使用されます。つまり、C<is_active>とC<first_trans_time...

=back

エラーが発生した場合、このメソッドはL<例外オブジェクト|DateTime::Lite::Exception>を設定し、スカラーコンテキストではC<undef>、リストコンテキストでは空リストを返します。その後、例外...

C<EST>ã‚„C<PST>のような多くの略称は、すべて同じUTCオフセットを共有する複数のゾーン名に一致することに注意してください。これらは日時文字列の解析という目的では真に曖昧ではありã...

=head2 short_name_for_datetime

    say $zone->short_name_for_datetime( $dt );

L<DateTime::Lite>オブジェクトを受け取り、C<JST>やC<EDT>のような、該当する省略形のタイムゾーン名を返します。

=head2 transition_count

このタイムゾーンの遷移レコード数を返します。

TZifヘッダーフィールドC<timecnt>に相当します。

L<rfc9636, section 3.1|https://www.rfc-editor.org/rfc/rfc9636.html#name-tzif-header>を参照してください。

=head2 type_count

このタイムゾーンのtype数を返します。

L<rfc9636, section 3.1|https://www.rfc-editor.org/rfc/rfc9636.html#name-tzif-header>を参照してください。

=head2 tz_version

データベースのC<metadata>テーブルから、C<2026a>のようなIANA tzdataバージョン文字列を返します。

=head2 tzif_version

タイムゾーンデータのTZifバージョン文字列を返します。

可能な値はC<1>, C<2>, C<3>, C<4>です。

L<rfc9636, section 3.1|https://www.rfc-editor.org/rfc/rfc9636.html#name-tzif-header>を参照してください。

=head1 正規指定のためにLocale::Unicode::Dataを使用する