Time-Piece-1.20 > Time::Piece
Other versions:


Time::Piece - Object Oriented time objects

Time::Piece - オブジェクト指向な時間オブジェクト


    use Time::Piece;
    my $t = localtime;
    print "Time is $t\n";
    print "Year is ", $t->year, "\n";


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.

このモジュールは、標準の localtime と gmtime 関数を、オブジェクトを返す 実装のものに置き換えます。 これを後方互換性がある形で行うので、perlfunc に書かれているように localtime/gmtime を使っても、期待通りのものを返します。

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

このモジュールは、Larry Wall が perl5-porters メーリングリストに書いた、 インターフェースのほとんどを実際に実装します: http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000-01/msg00241.html


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:

このモジュールをインポートした後は、スカラコンテキストで localtime か gmtime を使うと、日付と時間を表現する普通のスカラ文字列ではなく、 Time::Piece オブジェクトを得ます。 Time::Piece オブジェクトの文字列化は、偶然にも localtime と gmtime 関数と 同じ効果があります。 new() コンストラクタもありますが、Time::Piece オブジェクトが渡されない限り localtime() と同じです。 Time::Piece オブジェクトが渡されると、コピーコンストラクタになります。 下記のメソッドがオブジェクトで利用できます:

    $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
    $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 オブジェクトを作ります


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.

wdayname (day) と monname (month) の両方ともに、曜日のインデックスに使う リストを渡すことができます。 実際にロケールをインストールしたり使ったりせずに、ある種の地域化を実装する 必要があるなら、有益でしょう。

  my @days = qw( Dimanche Lundi Merdi Mercredi Jeudi Vendredi Samedi );

  my $french_day = localtime->day(@days);

These settings can be overriden globally too:



Or for months:



And locally for months:


  print localtime->month(@months);


It's possible to use simple addition and subtraction of objects:


    use Time::Seconds;
    my $seconds = $t1 - $t2;
    $t1 += ONE_DAY; # add 1 day (constant from Time::Seconds)

The following are valid ($t1 and $t2 are Time::Piece objects):

下記のものは有効です($t1 と $t2 は Time::Piece オブジェクト):

    $t1 - $t2; # returns Time::Seconds object
    $t1 - 42; # returns Time::Piece object
    $t1 + 533; # returns Time::Piece object

However adding a Time::Piece object to another Time::Piece object will cause a runtime error.

ですが、Time::Piece オブジェクトに別の Time::Piece オブジェクトを 足すのは、実行時エラーを引き起こします。

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.

上の例の最初のものは、Time::Seconds オブジェクトを返すことに注意して下さい; オブジェクトを試験することで(オーバーロードによって)秒数を出力する一方で、 Time::Seconds の API を使って、その差異から、分数、時間数、日数、週の数、 年数を得ることが出来ます。

In addition to adding seconds, there are two APIs for adding months and years:

秒の加算に加えて、月と年を加算するための二つの API があります:


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.

月と年は減算のために負数にもなり得ます。 月末で月を加減算すると「おかしな」振る舞いになることに注意してください。 一般的に結果となる月が開始月より短い場合、重なった日の分が追加されます。 例えば、2008-03-31 から 1 ヶ月引くと、あり得ない日付である 2008-02-31 には なりません。 代わりに 2008-03-02 になります。 これは他の日付操作ツールと一貫性があるように思われます。


Date comparisons are also possible, using the full suite of "<", ">", "<=", ">=", "<=>", "==" and "!=".

日付の比較も可能です; "<"、 ">"、"<="、 ">="、 "<=>"、 "=="、 "!=" の全てが使えます。


Time::Piece has a built-in strptime() function (from FreeBSD), allowing you incredibly flexible date parsing routines. For example:

Time::Piece は、驚くほど柔軟に日付を解析する組み込みの (FreeBSD 由来の) strptime() 関数を使えます。 たとえば:

  my $t = Time::Piece->strptime("Sunday 3rd Nov, 1943",
                                "%A %drd %b, %Y");
  print $t->strftime("%a, %d %b %Y");



  Wed, 03 Nov 1943

(see, it's even smart enough to fix my obvious date bug)


For more information see "man strptime", which should be on all unix systems.

もっと知りたければ、"man strptime" を見て下さい; これは、すべての unix システムで使えるはずです。

Alternatively look here: http://www.unix.com/man-page/FreeBSD/3/strftime/

あるいは、次のリンクを見てください: http://www.unix.com/man-page/FreeBSD/3/strftime/


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.

ISO 8601 標準は、日付のフォーマットを YYYY-MM-DD として、 時刻は hh:mm:ss(24 時制) として定めています。 組み合わせる場合、日付を最初にして、時刻の前に大文字の 'T' で結び付ける 必要があります。


The week number 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.

週番号 は、概念を知らない読者もいるかもしれません。 ISO 8601 標準は、週は月曜で始まり、その年の第 1 週は 1 月 4 日と 一年の最初の木曜日の両方を含む週であると定義しています。 言い換えると、1 月の最初の月曜日が 2 日か、3 日か、4 日であれば、 それより前の日は、昨年の最後の週の一部になります。 週番号は、1 から 53 の範囲です。


Finally, it's possible to override localtime and gmtime everywhere, by including the ':override' tag in the import list:

最後に、localtime と gmtime をどこにでもオーバーライドすることが可能です; インポートリストに、':override' タグを含めて下さい:

    use Time::Piece ':override';


Win32 でスレッドで $ENV{TZ} を設定する

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.

Win32 で perl をデフォルトビルド設定で使う場合 (特に perl が PERL_IMPLICIT_SYS でビルドされている場合)、 それぞれの perl インタプリタは独自の環境変数のコピーを保守していて、 メインインタプリタのみが strftime で見られるプロセス環境変数を 更新できることに注意してください。

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).

従って、メインスレッド以外のスレッド内から $ENV{TZ} を変更すると、 後で strftime の %Z フォーマッティングコードを使っても変更は見えません。 この場合、望み通りの効果を得るためにはメインスレッドで $ENV{TZ} を変更しなければなりません (そして環境変数の変更を登録するために メインスレッドで _tzset() を呼び出さなければなりません)。

Furthermore, remember that this caveat also applies to fork(), which is emulated by threads on Win32.

さらに、この問題は fork() にも適用されることを忘れないでください; これは Win32 ではスレッドでエミュレートされています。


This module internally uses the epoch seconds system that is provided via the perl time() function and supported by gmtime() and localtime().

このモジュールは、perl の time() 経由で提供され、gmtime()localtime() が対応している紀元秒システムを内部で使用しています。

If your perl does not support times larger than 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 DateTime module which has support for years well into the future and past.

2^31 秒以上の時間に対応していない perl を使っている場合、このモジュールは 2038 年以降の日付を扱おうとするとおそらく失敗するでしょう。 これは perl 内で修正する動きがみられます。 あるいは、64 ビット perl を使ってください。 またはこれらの選択肢を取れない場合は、過去と未来の年に対応している DateTime モジュールを使ってください。


Matt Sergeant, matt@sergeant.org Jarkko Hietaniemi, jhi@iki.fi (while creating Time::Piece for core perl)


This module is free software, you may distribute it under the same terms as Perl.


The excellent Calendar FAQ at http://www.tondering.dk/claus/calendar.html

http://www.tondering.dk/claus/calendar.html にある素晴らしいカレンダー FAQ。


The test harness leaves much to be desired. Patches welcome.

テストハーネスは望ましい状態にはほど遠いです。 パッチを歓迎します。