The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Tripletail-0.18
River stage zero No dependents
++
/ Tripletail::DateTime

NAME

Tripletail::DateTime - 日付と時刻

SYNOPSIS

  my $dt = $TL->newDateTime('2006-02-17 15:18:01');
  $dt->addDay(1);
  $dt->addSecond(-1);
  print $dt->toStr('rfc822'); # Fri, 18 Feb 2006 15:18:00 JST

DESCRIPTION

日付と時刻を扱うクラス。グレゴリオ歴にのみ対応している。精度は秒。 うるう秒や夏時間を考慮しない。

METHODS

$TL->newDateTime
  $dt = $TL->newDateTime;         # 現在時刻
  $dt = $TL->newDateTime($str);   # 文字列をパース

Tripletail::DateTime オブジェクトを生成。 二番目の形式では、文字列から日付や時刻をパースする。

存在しない日付が指定された場合は、それが自動的に補正される。 例えば次の 2 行は同じ結果になる。

  $dt = $TL->newDateTime('2000-04-31');
  $dt = $TL->newDateTime('2000-05-01');

但し、次の行はパースに失敗する。

  $dt = $TL->newDateTime('2000-99-99'); # 正しい形式に沿っていない

パースに失敗した場合はdieする。時刻が与えられない場合は 0 時 0 分 0秒 に設定され、タイムゾーンが与えらない場合は localtime と gmtime の差か ら求めた値が設定される。パースできる形式は次の通り。

一般
 YYYY-MM-DD
 YYYY-MM-DD HH:MM:SS

ハイフンやコロンは別の記号であっても良く、何も無くても良い。 例:

 YYYY@MM@DD
 YYYY/MM/DD HH.MM.SS
 YYYYMMDD
 YYYYMMDDHHMMSS
date コマンド
 Wdy Mon DD HH:MM:SS TIMEZONE YYYY
 (Fri Feb 17 11:24:41 JST 2006)
Apache access_log
 DD/Mon/YYYY:HH:MM:SS +TTTT
 (17/Feb/2006:11:24:41 +0900)
Apache error_log
 Wdy Mon DD HH:MM:SS YYYY
 (Fri Feb 17 11:24:41 2006)
Apache directory index
 DD-Mon-YYYY HH:MM:SS
RFC 822
 Wdy, DD-Mon-YY HH:MM:SS TIMEZONE
 (Fri, 17 Feb 06 11:24:41 +0900)

 Wdy, DD-Mon-YYYY HH:MM:SS TIMEZONE
 (Fri, 17 Feb 2006 11:24:41 +0900)
RFC 850
 Wdy, DD-Mon-YY HH:MM:SS TIMEZONE
 (Fri, 17-Feb-06 11:24:41 JST)

 Wdy, DD-Mon-YYYY HH:MM:SS TIMEZONE
 (Fri, 17-Feb-2006 11:24:41 JST)
W3C Date and Time
 YYYY
 YYYY-MM
 YYYY-MM-DD
 YYYY-MM-DDTHH:MMTzd (2006-02-17T11:40+09:00)
 YYYY-MM-DDTHH:MM:SSTzd (2006-02-17T11:40:10+09:00)
 YYYY-MM-DDTHH:MM:SS.sTzd (2006-02-17T11:40:10.45+09:00)

ここで Tzd とはタイムゾーン指定であり、+hh:mm / -hh:mm / 'Z' の何れか の形式で表される。Z は UTC を表す。例:

 2006-02-17T11:40:10Z

最後の形式の .s は時刻の端数を表すものであるが、このクラスの精度は秒で あるので、端数はパース後に切り捨てられる。

TAI64N
 @4000000043f529721590b6bc

一秒未満は切り捨てられる。

clone
  $dt2 = $dt->clone;

DateTimeオブジェクトを複製して返す。

set
  $dt->set;
  $dt->set($str);

引数はコンストラクタと同じ。

setEpoch
  $dt->setEpoch($epoch);

エポックからの秒数を設定する。このクラスでエポックとは gmtime(0) の返 す日付と時刻を云う。負の値を与えた場合は、エポック以前の日付/時刻に設 定される。

setJulianDay
  $dt->setJulianDay($julian);

ユリウス日を設定する。小数で指定された場合は、その値から時刻を求める。

setYear
  $dt->setYear(2006);

年を設定する。引数は、現在設定されているタイムゾーンでの値として解釈さ れる。

setMonth
  $dt->setMonth(1);

月を設定する。負の値 n を与えた場合は、最大値(setMonthの場合は12) + 1 + n が与えられたものと見なす。例えば setMonth(-1) は setMonth(12) に等 しい。

引数が0または13以上である場合、及び-13以下である場合は die する。

また、月を変更する事により日が存在する範囲から外れた場合は、日が最終日 に設定される。例えば1月31日で setMonth(4) すると4月30日になる。

setDay
setHour
setMinute
setSecond

setMonth と同様。負の値を与えた場合等の動作も setMonth に準じる。

setTimeZone
  $dt->setTimeZone();         # localtimeとgmtimeの差から計算
  $dt->setTimeZone(9);        # +09:00 に設定
  $dt->setTimeZone('+0900');  # +09:00 に設定 (RFC 822)
  $dt->setTimeZone('+09:00'); # +09:00 に設定 (W3C)
  $dt->setTimeZone('gmt');    # +00:00 に設定

タイムゾーンを設定する。タイムゾーンを変更すると、絶対時間であるエポッ ク秒やユリウス日は変化しないが、getSecond等で返される日付や時刻等が変 化する。

getEpoch
  $epoch = $dt->getEpoch;

エポック秒を返す。エポック以前の日付と時刻では負の値が返る。

getJulianDay
  $julian = $dt->getJulianDay;

ユリウス日を小数で返す。

getYear
  $year = $dt->getYear;

年を返す。現在設定されているタイムゾーンでの値が返される。

getMonth
  $mon = $dt->getMonth;       # 数値 1-12 で返す。

月を返す。

getDay
getHour
getMinute
getSecond

getYearと同様。

getWday
  $wday = $dt->getWday;       # 数値 0-6 で返す。0が日曜、1が月曜である。

曜日を返す。数値 0-6 で返す。0が日曜、1が月曜である。

getTimeZone
  $tz = $dt->getTimeZone();         # 時間で返す

タイムゾーンを時間単位で返す。端数がある場合は小数で返る。

getAnimal
  $animal = $dt->getAnimal;      # 数値 0-11 を返す

この年の十二支を返す。0: 子, 1: 丑, ... 11: 亥

getAllHolidays
  $hash = $dt->getAllHolidays;

この年にある日本の祝祭日を返す。返される値は、キーが MM-DD 形式の日付、 値が祝祭日名のハッシュである。

isHoliday
  $bool = $dt->isHoliday($type);

この日が特定の日であれば 1 を、そうでなければ undef を返す。

特定の日とは以下の通り。

$typeが0の場合、土日及び日本の祝祭日。

$typeが1の場合、日及び日本の祝祭日。

$typeが2の場合、日本の祝祭日。

デフォルトは0。

getHolidayName
  $str = $dt->getHolidayName;

この日が祝祭日であればその名前を、そうでなければ undef を返す。

isLeapYear

この年がうるう年であれば 1 を、そうでなければ undef を返す。

getCalendar
  $array = $dt->getCalendar;

この月の日数分の DateTime オブジェクトが入った配列を返す。

getCalendarMatrix
  $matrix = $dt->getCalendarMatrix(\$option);

この月のカレンダーを二次元配列で返す。 引数は次の通り:

type

'normal' または 'fixed' の2種類。fixed にすると常に６週分を返す.

begin

'sun' または 'mon' の2種類。sun なら週が日曜から始まり、mon なら月曜。 デフォルトは sun 。

戻り値はカレンダーの一行分の DateTime オブジェクトの配列を1ヶ月分格納した配列。

spanSecond
  $seconds = $dt->spanSecond($dt2);
  $seconds = $dt->spanSecond($dt1,$dt2);

引数との秒数の差を計算し、結果を整数で返す。 引数が2つ指定された場合は、引数同士の差を計算する。

spanは、実際の期間を、指定された単位で計算する。 spanDay で1日が返った場合は、2つの日付の間に24時間の間隔があることを示す。

spanMonth / Year の場合、それ以下の日部分の大小や年部分の大小を比較して、マイナス１すべきか判断する。 秒数を平均的な１月の長さや１年の長さで割って求めているわけではない。（年齢計算等に利用できる）

例：spanMonthの場合（2006年1月1日00時00分00秒と2005年12月31日00時00分00秒の場合、0が返る）

引数が DateTime オブジェクトだった場合はそのオブジェクトと比較し、 それ以外の場合は引数をそのまま $TL->newDateTime に渡して生成した オブジェクトと比較する。

返される値は ($dt) - ($dt2) もしくは、($dt1) - ($dt2)であり、引数が過去ならば結果は負になる。

spanMinute
spanHour
spanDay
spanMonth
spanYear

spanSecond と同様。

minusSecond
  $seconds = $dt->minusSecond($dt2);
  $seconds = $dt->minusSecond($dt1,$dt2);

引数との秒数の差を計算し、結果を整数で返す。 引数が2つ指定された場合は、引数同士の差を計算する。

minusは、指定された単位部分の差を計算する。 minusDayであれば、時・分・秒の部分を無視し、 年月日のみで差を計算し、その差が何日分かを返す。

例：minsMonthの場合（2006年1月1日と2005年12月31日の場合、1が返る）

引数が DateTime オブジェク トだった場合はそのオブジェクトと比較し、それ以外の場合は引数をそのまま $TL->newDateTime に渡して生成したオブジェクトと比較する。

返される値は ($dt) - ($dt2) もしくは、($dt1) - ($dt2)であり、引数が過去ならば結果は負になる。

minusMinute
minusHour
minusDay
minusMonth
minusYear

minusSecond と同様。

addSecond
  $dt->addSecond($sec);

$sec 秒後の時刻にする。

addMinute
addHour
addDay

addSecond と同様。

addMonth

addSecond と同様だが、もし変更前の日が変更後の年/月に存在しないもので あったら、日はその月の最後の日に変更される。

addYear

addMonth と同様。

addBusinessDay
  $dt->addBusinessDay($day,$type);

$day 営業日後にする。 お盆や年末年始などは考慮しない。

例としては、12月31日で、$dayに1を指定した場合、翌年の1月2日になる。 （2日が振替休日の場合、3日になる）

休業日は$typeで決定する。

$typeが0の場合、土日及び日本の祝祭日。

$typeが1の場合、日及び日本の祝祭日。

$typeが2の場合、日本の祝祭日。

を休業日として営業日を判定する。

デフォルトは0。

nextDay

次の日にする。

prevDay

前の日にする。

firstDay

その月の最初の日にする。

lastDay

その月の最後の日にする。

toStr
  $str = $dt->toStr('mysql');  # YYYY-MM-DD HH:MM:SS の形式で返す。
  $str = $dt->toStr('rfc822'); # rfc822 形式で返す。
  $str = $dt->toStr('rfc850'); # rfc850 形式で返す。
  $str = $dt->toStr('w3c');    # W3c Date and Time の形式で返す。
  $str = $dt->toStr;           # mysql と同じ。

文字列で表した日付と時刻を返す。

strFormat
  $str = $dt->strFormat('%Y 年 %m 月 %d 日 (%J) %H 時 %M 分');

指定されたフォーマットに従って文字列化したものを返す。

%a

短縮された曜日の名前 (Sun - Sat)

%A

完全な曜日の名前 (Sunday - Saturday)

%J

日本語での曜日の名前 (日 - 土)

%b

短縮された月の名前 (Jan - Dec)

%B

完全な月の名前 (January - December)

%_B

日本語での月の名前 (睦月 - 師走)

%d

日を2桁で表現 (01 - 31)

%_d

日 (1 - 31)

%m

月を2桁で表現 (01-12)

%_m

月 (1-12)

%w

曜日を10進数で表現。0 - 6 で、日曜が 0 、月曜が 1 。

%y

年を下2桁で表現 (00 - 99)

%Y

年を4桁で表現

%_Y

年を和暦で表現。 (平成11年 等)

和暦の定義されていない範囲では空文字列。

%H

時を24時間表記で2桁で表現 (00-23)

%_H

時を24時間表記で表現 (0-23)

%I

時を12時間表記で2桁で表現 (00-11)

%_I

時を12時間表記で表現 (0-11)

%P

時刻が午前なら 'a.m.', 午後なら 'p.m.' に置換する。 24時間表記での0時0分は午前とし、12時0分は午後とする。

このパターンが parseFormat で使われる時は、大文字と小文字は無視され、 ピリオドの有無も無視される。例えば 'AM', 'A.M.', 'a.M' はいずれも午前 としてパースされる。

%_P

時刻が午前なら '午前', 午後なら '午後' に置換する。

%M

分を2桁で表現 (00-59)

%_M

分 (0-59)

%S

秒を2桁で表現 (00-59)

%_S

秒 (0-59)

%E

十二支を表す文字 (子 - 亥)

%z

RFC 822 形式に於けるタイムゾーン。JSTの場合は '+0900' になる。

%_z

W3C Date and Time 形式に於けるタイムゾーン。JSTの場合は '+09:00' になる。

%Z

タイムゾーンを表す名称。存在しない場合は空文字列になる。

%T

'%H:%M:%S' のフォーマットで返される文字列

%%

'%' という文字

parseFormat
  $dt->parseFormat('%Y %d %m', '2006 01 13');

指定されたフォーマットを用いて日付と時刻の文字列をパースする。フォーマッ ト文字は strFormat のものと同一。フォーマット文字列から年を得 る事が出来ない場合や、パースに失敗した場合は、die する。

また、常に空白または0による桁揃えの有無、全角半角は無視して解析する。

12時間表記の時間である %I と %_I と、午前または午後を表す %P と %_P は、 用いられる際には必ず両方用いられなければならない。いずれか片方だけでは 正確な時刻が判らない為。

SEE ALSO

Tripletail

AUTHOR INFORMATION

    Copyright 2006 YMIRLINK Inc. All Rights Reserved.

    This framework is free software; you can redistribute it and/or modify it under the same terms as Perl itself

    このフレームワークはフリーソフトウェアです。あなたは Perl と同じライセンスの 元で再配布及び変更を行うことが出来ます。

    Address bug reports and comments to: tl@tripletail.jp

    HP : http://tripletail.jp/