名前

Date::Simple - Date::Simple - 簡単な日付オブジェクト。

(訳註：Date::Simple 2.03は、次のDate::Simpleです。CPAN.pm で "install Date::Simple" でとれるのは、1.03です。)

概要

    use Date::Simple ('date', 'today');

    # Difference in days between two dates:
    $diff = date('2001-08-27') - date('1977-10-05');

    # Offset $n days from now:
    $date = today() + $n;
    print "$date\n";  # uses ISO 8601 format (YYYY-MM-DD)

    use Date::Simple ();
    my $date  = Date::Simple->new('1972-01-17');
    my $year  = $date->year;
    my $month = $date->month;
    my $day   = $date->day;

    use Date::Simple (':all');
    my $date2 = ymd($year, $month, $day);
    my $date3 = d8('19871218');
    my $today = today();
    my $tomorrow = $today + 1;
    if ($tomorrow->year != $today->year) {
        print "Today is New Year's Eve!\n";
    }

    if ($today > $tomorrow) {
        die "warp in space-time continuum";
    }

    print "Today is ";
    print(('Sun','Mon','Tues','Wednes','Thurs','Fri','Satur')
          [$today->day_of_week]);
    print "day.\n";

    # you can also do this:
    ($date cmp "2001-07-01")
    # and this
    ($date <=> [2001, 7, 1])

説明

日付は、時間と時間帯なしでも、十分に複雑です。このモジュールは、簡単な日付オブジェクトを作ります。次のものを取り扱います：

妥当性
1999-02-29は、拒否し、2000-02-29は、受け入れます。
間隔の計算
与えられた2つの日付の間には、何日間あるか？今日からN日後の日付は何か？
曜日の計算
与えられた日付は何曜日か？

Date::Simpleは、時分秒、時間帯は取り扱いません。

日付は、妥当な範囲の、年月日の数字によって、ユニークに特定されます。このモジュールは、不当な日付のオブジェクトを作ることを許しません。不当な日付で作ろうとすると、undefを返します。月のナンバリングは、1月が1で始まります。Cや、Javaとは、違っています。年は、4桁です。

9999年までのグレゴリオ日付が正確に取り扱われます。ですが、現在の日付が要求された場合、Perlの組み込み関数のlocaltimeを当てにします。プラットフォームの中には、localtimeは、 UNIX time_tの2038年1月の回り込みのように転覆する脆弱性があるかもしれません。

オーバーロードが使われているので、2つの日付を比較するか、引き算をするのに、標準的な数値演算子、==のようなものを使うことが出来ます。また、日付オブジェクトと数字の足し算は、別の日付ブジェクトになります。

Date::Simpleオブジェクトは、不変です。$date1を$date2に割り当てた後、 $date1の変更は$date2にまったく影響を与えません。このことは、たとえば、set_yearオペレーションのようなものがないと言うことを意味します。 $date++は、$dateに、新しいオブジェクトを割り当てます。

このモジュールは、さまざまなドキュメント化されていない関数を含んでいます。それらは、全てのプラットフォームで利用可能でないし、将来のリリースで、変更するか、消えるかもしれません。これらのいくつかを公にすべきと思うなら、作者に教えてください。

複数のコンストラクタ

いくつかの関数は、文字列か数字の表現をとり、対応する日付オブジェクトを返します。もっとも一般的なのは、newです。newの引数リストは、空か (現在の日付を返します)、ISO 8601フォーマット(YYYY-MM-DD)の文字列か、年月日の数字の配列または配列リファレンスか、日付オブジェクトです。

Date::Simple->new ([ARG, ...])
date ([ARG, ...])
```
    my $date = Date::Simple->new('1972-01-17');
```
渡された値が妥当な日付を指定していたら、newメソッドは、日付オブジェクトを返します。渡された値が不正であれば、メソッドは、undefを返します。引数が数字の範囲に反したフォーマットで不正なら、newは、死にます。

date関数は同じ機能を提供しますが、インポートされなければならないか、 Date::Simple::Dateのように、修飾されなければなりません。 (すべてのパブリックな関数をインポートするためには、use Date::Simple (':all');としてください)。この関数は、不正な入力は全て、undefを返します。 newのようにいくつかのケースで死ぬことはありません。
today()
localtimeによって、現在の日付を返します。

注意:明日の日付(または、今日からの一定のオフセット)を得るためにtoday + 1を使ってはいけません。Perlは、これを、today(+1)として、解釈します。関数の後に、空の括弧が必要です：today() + 1
ymd (YEAR, MONTH, DAY)
与えられた年月日の数字で、日付をブジェクトを返します。引数が、妥当な日付を指定していなければ、undefを返します。

例:
```
    use Date::Simple ('ymd');
    $pbd = ymd(1987, 12, 18);
```
d8 (STRING)
"YYYYMMDD"として、文字列を解釈し、対応する日付オブジェクトを返します。文字列が間違ったフォーマットか、妥当な日付を指定していなければ、 undefを返します。

例:
```
    use Date::Simple ('d8');
    $doi = d8('17760704');
```
覚え方：文字列が /\d{8}/にマッチする. また、"d8" は、もし、8 が、発音どおりに広げられたら、"date" と綴ります。

インスタンスメソッド

DATE->next
```
    my $tomorrow = $today->next;
```
明日に相当するオブジェクトを返します。
DATE->prev
```
    my $yesterday = $today->prev;
```
昨日に相当するオブジェクトを返します。
DATE->year
```
    my $year  = $date->year;
```
日付オブジェクトの年を数字で返します。
DATE->month
```
    my $month = $date->month;
```
日付オブジェクトの月を1から12の数字で返します。
DATE->day
```
    my $day   = $date->day;
```
日付オブジェクトの月の日を、1から31の数字で返します。
DATE->day_of_week
0から6の日付オブジェクトの曜日を表す数字を返します。 0は、日曜日を意味します。
DATE->as_ymd
```
    my ($year, $month, $day) = $date->as_ymd;
```
3っつの数字のリストを返します：年と月と日です。
DATE->as_d8
"d8"表記(d8を見てください)で返します。 $date->format("%Y$m$d")>とおなじです。
DATE->format (STRING)
DATE->strftime (STRING)
これらの関数は同等です。日付を表す文字列を、指定されたフォーマットで返します。パラメータを渡さなければ、ISO8601フォーマットが返ります。
```
    my $change_date = $date->format("%d %b %y");
    my $iso_date1 = $date->format("%Y-%m-%d");
    my $iso_date2 = $date->format;
```
フォーマットのパラメータは、srrftime(3)に渡すものと、似ています。これは私たちが日付をフォーマットするためにそれを実際にstrftimeに渡すからです。このことは、プラットフォームや地域を横切って、異なる振舞を生じるかもしれませんし、さらに、どこでも働くとは限らないかもしれません。

演算子

Date:Simpleインスタンスと一緒に、いくつかの演算子を使うことが出来ます。式の片方が日付オブジェクトで、演算子が2つの日付オブジェクトを期待するなら、もう片方がdate(ARG)として、解釈されます。ですので、配列リファレンスかISO 8601の文字列ならば動くでしょう。

DATE + NUMBER
DATE - NUMBER
+と-演算子を使うことで、日数で、新しい日付オフセットを生成出来ます。
DATE1 - DATE2
日付の間の日数を見つけるために2つの日付を引くことができます。
DATE1 == DATE2
DATE1 < DATE2
DATE1 <=> DATE2
DATE1 cmp DATE2
など
算術/文字列比較演算子を使って、2つの日付を比較することが出来ます。
DATE += NUMBER
DATE -= NUMBER
+= と、-= 演算子を使って、日数によって、日付をインクリメント、デクリメント出来ます。これは、実際、新しい日付オブジェクトを生み出しますので、$date = $date + $numberと同じです。
"$date"
ISO 8601(例：2000-01-17)で、指定された形式で、日付オブジェクトを直接に文字列に挿入できます。

ユーティリティ

leap_year (YEAR)
その年が閏年なら、真を返します。
days_in_month (YEAR, MONTH)
年と月の日数を返します。

著者

(原文まま)

    Marty Pauley <marty@kasei.com>
    John Tobey <jtobey@john-edwin-tobey.org>

著作権

(原文まま)

      Copyright (C) 2001  Kasei
      Copyright (C) 2001 John Tobey.

      This program is free software; you can redistribute it and/or
      modify it under the terms of either:

      a) the GNU General Public License;
         either version 2 of the License, or (at your option) any later
         version.  You should have received a copy of the GNU General
         Public License along with this program; see the file COPYING.
         If not, write to the Free Software Foundation, Inc., 59
         Temple Place, Suite 330, Boston, MA 02111-1307 USA

      b) the Perl Artistic License.

      This program is distributed in the hope that it will be useful,
      but WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.