=encoding euc-jp =head1 NAME =begin original Time::Piece - Object Oriented time objects =end original Time::Piece - オブジェクト指向な時間オブジェクト =head1 SYNOPSIS use Time::Piece; my $t = localtime; print "Time is $t\n"; print "Year is ", $t->year, "\n"; =head1 DESCRIPTION =begin original This module replaces the standard localtime and gmtime functions with implementations that return objects. It does so in a backwards compatible manner, so that using localtime/gmtime in the way documented in perlfunc will still return what you expect. =end original このモジュールは、標準の localtime と gmtime 関数を、オブジェクトを返す 実装のものに置き換えます。 これを後方互換性がある形で行うので、perlfunc に書かれているように localtime/gmtime を使っても、期待通りのものを返します。 =begin original The module actually implements most of an interface described by Larry Wall on the perl5-porters mailing list here: http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000-01/msg00241.html =end original このモジュールは、Larry Wall が perl5-porters メーリングリストに書いた、 インターフェースのほとんどを実際に実装します: http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000-01/msg00241.html =head1 USAGE (使い方) =begin original After importing this module, when you use localtime or gmtime in a scalar context, rather than getting an ordinary scalar string representing the date and time, you get a Time::Piece object, whose stringification happens to produce the same effect as the localtime and gmtime functions. There is also a new() constructor provided, which is the same as localtime(), except when passed a Time::Piece object, in which case it's a copy constructor. The following methods are available on the object: =end original このモジュールをインポートした後は、スカラコンテキストで localtime か gmtime を使うと、日付と時間を表現する普通のスカラ文字列ではなく、 Time::Piece オブジェクトを得ます。 Time::Piece オブジェクトの文字列化は、偶然にも localtime と gmtime 関数と 同じ効果があります。 new() コンストラクタもありますが、Time::Piece オブジェクトが渡されない限り localtime() と同じです。 Time::Piece オブジェクトが渡されると、コピーコンストラクタになります。 下記のメソッドがオブジェクトで利用できます: =begin original $t->sec # also available as $t->second $t->min # also available as $t->minute $t->hour # 24 hour $t->mday # also available as $t->day_of_month $t->mon # 1 = January $t->_mon # 0 = January $t->monname # Feb $t->month # same as $t->monname $t->fullmonth # February $t->year # based at 0 (year 0 AD is, of course 1 BC) $t->_year # year minus 1900 $t->yy # 2 digit year $t->wday # 1 = Sunday $t->_wday # 0 = Sunday $t->day_of_week # 0 = Sunday $t->wdayname # Tue $t->day # same as wdayname $t->fullday # Tuesday $t->yday # also available as $t->day_of_year, 0 = Jan 01 $t->isdst # also available as $t->daylight_savings $t->hms # 12:34:56 $t->hms(".") # 12.34.56 $t->time # same as $t->hms $t->ymd # 2000-02-29 $t->date # same as $t->ymd $t->mdy # 02-29-2000 $t->mdy("/") # 02/29/2000 $t->dmy # 29-02-2000 $t->dmy(".") # 29.02.2000 $t->datetime # 2000-02-29T12:34:56 (ISO 8601) $t->cdate # Tue Feb 29 12:34:56 2000 "$t" # same as $t->cdate $t->epoch # seconds since the epoch $t->tzoffset # timezone offset in a Time::Seconds object $t->julian_day # number of days since Julian period began $t->mjd # modified Julian date (JD-2400000.5 days) $t->week # week number (ISO 8601) $t->is_leap_year # true if it its $t->month_last_day # 28-31 $t->time_separator($s) # set the default separator (default ":") $t->date_separator($s) # set the default separator (default "-") $t->day_list(@days) # set the default weekdays $t->mon_list(@days) # set the default months $t->strftime(FORMAT) # same as POSIX::strftime (without the overhead # of the full POSIX extension) $t->strftime() # "Tue, 29 Feb 2000 12:34:56 GMT" Time::Piece->strptime(STRING, FORMAT) # see strptime man page. Creates a new # Time::Piece object =end original $t->sec # $t->second も可 $t->min # $t->minute も可 $t->hour # 24 時制 $t->mday # $t->day_of_month も可 $t->mon # 1 = 一月 $t->_mon # 0 = 一月 $t->monname # Feb $t->month # $t->monname と同じ $t->fullmonth # February $t->year # 0 始まり(AD 0 年は、もちろん、BC 1 年) $t->_year # 年から 1900 を引いたもの $t->yy # 2 桁の年 $t->wday # 1 = 日曜 $t->_wday # 0 = 日曜 $t->day_of_week # 0 = 日曜 $t->wdayname # Tue $t->day # wdayname と同じ $t->fullday # Tuesday $t->yday # $t->day_of_year も可, 0 = 1 月 1 日 $t->isdst # $t->daylight_savings も可。 $t->hms # 12:34:56 $t->hms(".") # 12.34.56 $t->time # $t->hms と同じ $t->ymd # 2000-02-29 $t->date # $t->ymd と同じ $t->mdy # 02-29-2000 $t->mdy("/") # 02/29/2000 $t->dmy # 29-02-2000 $t->dmy(".") # 29.02.2000 $t->datetime # 2000-02-29T12:34:56 (ISO 8601) $t->cdate # Tue Feb 29 12:34:56 2000 "$t" # $t->cdate と同じ $t->epoch # epochからの秒 $t->tzoffset # Time::Seconds オブジェクトによるタイムゾーンオフセット $t->julian_day # ユリウス歴が始まってからの日の数 $t->mjd # 修正ユリウス日 (JD-2400000.5 日) $t->week # 週番号 (ISO 8601) $t->is_leap_year # 閏年なら真を返す $t->month_last_day # 28-31 $t->time_separator($s) # デフォルトのセパレータを設定 (デフォルト ":") $t->date_separator($s) # デフォルトのセパレータを設定 (デフォルト "-") $t->day_list(@days) # デフォルトの曜日を設定 $t->mon_list(@days) # デフォルトの月名を設定 $t->strftime(FORMAT) # POSIX::strftime と同じ(しかし完全な # POSIX 拡張のためのオーバーヘッドはありません) $t->strftime() # "Tue, 29 Feb 2000 12:34:56 GMT" Time::Piece->strptime(STRING, FORMAT) # strptime man ページを見て下さい。新しく # Time::Piece オブジェクトを作ります =head2 Local Locales (ローカルロケール) =begin original Both wdayname (day) and monname (month) allow passing in a list to use to index the name of the days against. This can be useful if you need to implement some form of localisation without actually installing or using locales. =end original wdayname (day) と monname (month) の両方ともに、曜日のインデックスに使う リストを渡すことができます。 実際にロケールをインストールしたり使ったりせずに、ある種の地域化を実装する 必要があるなら、有益でしょう。 my @days = qw( Dimanche Lundi Merdi Mercredi Jeudi Vendredi Samedi ); my $french_day = localtime->day(@days); =begin original These settings can be overriden globally too: =end original これらの設定はグローバルにもオーバーライドできます: Time::Piece::day_list(@days); =begin original Or for months: =end original また、月なら: Time::Piece::mon_list(@months); =begin original And locally for months: =end original 月に関してローカルに行うなら: print localtime->month(@months); =head2 Date Calculations (日付の演算) =begin original It's possible to use simple addition and subtraction of objects: =end original 単純なオブジェクトの足し算、引き算ができます: use Time::Seconds; my $seconds = $t1 - $t2; $t1 += ONE_DAY; # add 1 day (constant from Time::Seconds) =begin original The following are valid ($t1 and $t2 are Time::Piece objects): =end original 下記のものは有効です($t1 と $t2 は Time::Piece オブジェクト): $t1 - $t2; # returns Time::Seconds object $t1 - 42; # returns Time::Piece object $t1 + 533; # returns Time::Piece object =begin original However adding a Time::Piece object to another Time::Piece object will cause a runtime error. =end original ですが、Time::Piece オブジェクトに別の Time::Piece オブジェクトを 足すのは、実行時エラーを引き起こします。 =begin original Note that the first of the above returns a Time::Seconds object, so while examining the object will print the number of seconds (because of the overloading), you can also get the number of minutes, hours, days, weeks and years in that delta, using the Time::Seconds API. =end original 上の例の最初のものは、Time::Seconds オブジェクトを返すことに注意して下さい; オブジェクトを試験することで(オーバーロードによって)秒数を出力する一方で、 Time::Seconds の API を使って、その差異から、分数、時間数、日数、週の数、 年数を得ることが出来ます。 =begin original In addition to adding seconds, there are two APIs for adding months and years: =end original 秒の加算に加えて、月と年を加算するための二つの API があります: $t->add_months(6); $t->add_years(5); =begin original The months and years can be negative for subtractions. Note that there is some "strange" behaviour when adding and subtracting months at the ends of months. Generally when the resulting month is shorter than the starting month then the number of overlap days is added. For example subtracting a month from 2008-03-31 will not result in 2008-02-31 as this is an impossible date. Instead you will get 2008-03-02. This appears to be consistent with other date manipulation tools. =end original 月と年は減算のために負数にもなり得ます。 月末で月を加減算すると「おかしな」振る舞いになることに注意してください。 一般的に結果となる月が開始月より短い場合、重なった日の分が追加されます。 例えば、2008-03-31 から 1 ヶ月引くと、あり得ない日付である 2008-02-31 には なりません。 代わりに 2008-03-02 になります。 これは他の日付操作ツールと一貫性があるように思われます。 =head2 Date Comparisons (日付の比較) =begin original Date comparisons are also possible, using the full suite of "<", ">", "<=", ">=", "<=>", "==" and "!=". =end original 日付の比較も可能です; "<"、 ">"、"<="、 ">="、 "<=>"、 "=="、 "!=" の全てが使えます。 =head2 Date Parsing (日付の解析) =begin original Time::Piece has a built-in strptime() function (from FreeBSD), allowing you incredibly flexible date parsing routines. For example: =end original Time::Piece は、驚くほど柔軟に日付を解析する組み込みの (FreeBSD 由来の) strptime() 関数を使えます。 たとえば: my $t = Time::Piece->strptime("Sunday 3rd Nov, 1943", "%A %drd %b, %Y"); print $t->strftime("%a, %d %b %Y"); =begin original Outputs: =end original 次のように出力します: Wed, 03 Nov 1943 =begin original (see, it's even smart enough to fix my obvious date bug) =end original (ほら、私の一目瞭然な日付のバグを直すのに十分なくらい賢いです) =begin original For more information see "man strptime", which should be on all unix systems. =end original もっと知りたければ、"man strptime" を見て下さい; これは、すべての unix システムで使えるはずです。 =begin original Alternatively look here: http://www.unix.com/man-page/FreeBSD/3/strftime/ =end original あるいは、次のリンクを見てください: http://www.unix.com/man-page/FreeBSD/3/strftime/ =head2 YYYY-MM-DDThh:mm:ss =begin original The ISO 8601 standard defines the date format to be YYYY-MM-DD, and the time format to be hh:mm:ss (24 hour clock), and if combined, they should be concatenated with date first and with a capital 'T' in front of the time. =end original ISO 8601 標準は、日付のフォーマットを YYYY-MM-DD として、 時刻は hh:mm:ss(24 時制) として定めています。 組み合わせる場合、日付を最初にして、時刻の前に大文字の 'T' で結び付ける 必要があります。 =head2 Week Number (週番号) =begin original The I may be an unknown concept to some readers. The ISO 8601 standard defines that weeks begin on a Monday and week 1 of the year is the week that includes both January 4th and the first Thursday of the year. In other words, if the first Monday of January is the 2nd, 3rd, or 4th, the preceding days of the January are part of the last week of the preceding year. Week numbers range from 1 to 53. =end original I<週番号> は、概念を知らない読者もいるかもしれません。 ISO 8601 標準は、週は月曜で始まり、その年の第 1 週は 1 月 4 日と 一年の最初の木曜日の両方を含む週であると定義しています。 言い換えると、1 月の最初の月曜日が 2 日か、3 日か、4 日であれば、 それより前の日は、昨年の最後の週の一部になります。 週番号は、1 から 53 の範囲です。 =head2 Global Overriding (グローバルなオーバーライド) =begin original Finally, it's possible to override localtime and gmtime everywhere, by including the ':override' tag in the import list: =end original 最後に、localtime と gmtime をどこにでもオーバーライドすることが可能です; インポートリストに、':override' タグを含めて下さい: use Time::Piece ':override'; =head1 CAVEATS =head2 Setting $ENV{TZ} in Threads on Win32 (Win32 でスレッドで $ENV{TZ} を設定する) =begin original Note that when using perl in the default build configuration on Win32 (specifically, when perl is built with PERL_IMPLICIT_SYS), each perl interpreter maintains its own copy of the environment and only the main interpreter will update the process environment seen by strftime. =end original Win32 で perl をデフォルトビルド設定で使う場合 (特に perl が PERL_IMPLICIT_SYS でビルドされている場合)、 それぞれの perl インタプリタは独自の環境変数のコピーを保守していて、 メインインタプリタのみが strftime で見られるプロセス環境変数を 更新できることに注意してください。 =begin original Therefore, if you make changes to $ENV{TZ} from inside a thread other than the main thread then those changes will not be seen by strftime if you subsequently call that with the %Z formatting code. You must change $ENV{TZ} in the main thread to have the desired effect in this case (and you must also call _tzset() in the main thread to register the environment change). =end original 従って、メインスレッド以外のスレッド内から $ENV{TZ} を変更すると、 後で strftime の %Z フォーマッティングコードを使っても変更は見えません。 この場合、望み通りの効果を得るためにはメインスレッドで $ENV{TZ} を変更しなければなりません (そして環境変数の変更を登録するために メインスレッドで _tzset() を呼び出さなければなりません)。 =begin original Furthermore, remember that this caveat also applies to fork(), which is emulated by threads on Win32. =end original さらに、この問題は fork() にも適用されることを忘れないでください; これは Win32 ではスレッドでエミュレートされています。 =head2 Use of epoch seconds (紀元秒を使う) =begin original This module internally uses the epoch seconds system that is provided via the perl C function and supported by C and C. =end original このモジュールは、perl の C 経由で提供され、C と C が対応している紀元秒システムを内部で使用しています。 =begin original If your perl does not support times larger than C<2^31> seconds then this module is likely to fail at processing dates beyond the year 2038. There are moves afoot to fix that in perl. Alternatively use 64 bit perl. Or if none of those are options, use the L module which has support for years well into the future and past. =end original C<2^31> 秒以上の時間に対応していない perl を使っている場合、このモジュールは 2038 年以降の日付を扱おうとするとおそらく失敗するでしょう。 これは perl 内で修正する動きがみられます。 あるいは、64 ビット perl を使ってください。 またはこれらの選択肢を取れない場合は、過去と未来の年に対応している L モジュールを使ってください。 =head1 AUTHOR Matt Sergeant, matt@sergeant.org Jarkko Hietaniemi, jhi@iki.fi (while creating Time::Piece for core perl) =head1 License This module is free software, you may distribute it under the same terms as Perl. =head1 SEE ALSO =begin original The excellent Calendar FAQ at http://www.tondering.dk/claus/calendar.html =end original http://www.tondering.dk/claus/calendar.html にある素晴らしいカレンダー FAQ。 =head1 BUGS =begin original The test harness leaves much to be desired. Patches welcome. =end original テストハーネスは望ましい状態にはほど遠いです。 パッチを歓迎します。 =begin meta Translate: 加藤敦 (1.08) Update: SHIRAKATA Kentaro (1.20) =end meta =cut