41.7 時刻の変換

以下の関数はtime値(Time of Dayを参照)をLispタイムスタンプ暦情報に変換したり逆の変換を行います。

32ビットオペレーティングシステムの多くは、秒数コンポーネントに32ビット情報を含んだシステム時刻に制限されます。これらのシステムは通常は万国標準時の1901-12-13 20:45:52から2038-01-19 03:14:07までの時刻だけを処理します。しかし64ビット、およびいくつかの32ビットオペレーティングシステムは、より大きな秒数コンポーネント値をもち、より遠い過去や未来の時刻を表現できます。

暦変換関数は、たとえグレゴリオ暦導入前の日付にたいしても常にグレゴリオ暦を使用します。年はBC. 1年から年数を数えて伝統的なグレゴリオ年が行うように0年をスキップしません。たとえば年数-37はグレゴリオ年のBC. 38年を表します。

Function: time-convert time &optional form

この関数はtime値をLispタイムスタンプに変換する。

オプションのform引数はリターンするタイムスタンプ形式を指定する。この関数はformがシンボルintegerなら整数でカウントした秒数をリターンする。正の整数のformはクロック周波数を指定する。その場合にはこの関数は(ticks . form)という整数ペアのタイムスタンプをリターンする²⁸。formがtなら、この関数はタイムスタンプを適切に表現するような正の整数としてそれを扱う。たとえばtimeがnilでプラットフォームのタイムスタンプがナノ秒の解像度をもつ場合には1000000000としてそれを扱う。formがlistなら、この関数は整数のリスト(high low micro pico)をリターンする。現在のところformが省略かnilならlistのように動作するとしても、Emacsの将来バージョンで変更が予定されているので、呼び出し側がリスト形式のタイムスタンプを必要とする場合には明示的にlistを渡すこと。

timeが無限(infinite)やNaN(not a number: 数字ではない)なら、この関数はエラーをシグナルする。それ以外の場合には、timeを正確に表せなければ、負の無限大方向に切り詰めて変換する。formがtなら変換は常に正確なので切り詰めは発生せず、リターン値のクロック解像度がtimeの解像度より小さくなることはない。対照的にfloat-timeは、たとえ結果が正確でなくても、任意のLisp time値をエラーをシグナルせずに変換できる。Time of Dayを参照のこと。

この関数は効率化のためにtimeとeqな値、あるいはtimeと構造を共有する値をリターンするかもしれない。

(time-convert nil nil)は(current-time)と等価だが後者は幾分速い。

(setq a (time-convert nil t))
⇒ (1564826753904873156 . 1000000000)

(time-convert a 100000)
⇒ (156482675390487 . 100000)

(time-convert a 'integer)
⇒ 1564826753

(time-convert a 'list)
⇒ (23877 23681 904873 156000)

Function: decode-time &optional time zone form

この関数はtime値を暦情報に変換する。timeを指定しなければカレント時刻をデコードする。同様にzoneのデフォルトはカレントのタイムゾーンルール。Time Zone Rulesを参照のこと。timeの範囲およびzoneの値はオペレーティングシステムが制限する。

form引数はリターンされるseconds要素の形式を制御する(以下参照)。リターン値は以下のような9要素のリスト:

(seconds minutes hour day month year dow dst utcoff)

以下は各要素の意味:

seconds

以下で説明する形式による、分秒の秒。

minutes

0から59までの整数で表した時を過ぎた時分秒の分。

hour

0から23までの整数で表した時分秒の時。

day

1から31までの整数で表した年月日の日。

month

1から12までの整数で表した年月日の月。

year

通常は1900より大きい整数で表した年月日の年。

dow

0から6までの整数で表した曜日であり0は日曜日を意味する。

dst

夏時間が有効ならt、無効ならnil、その情報が利用できなければ-1。

utcoff

万国標準時からの秒数、すなわち東グリニッジの秒数を示す整数。

Lispタイムスタンプのseconds要素は非負かつ61より小さいこと。これはは正の閏秒の間以外は60より小さくなる(オペレーティングシステムが閏秒をサポートする場合)。オプションのform引数がtなら、secondsはtimeと同じ精度を使用する。formがintegerならsecondsを整数に切り捨てる。たとえばtimeがタイムスタンプ(1566009571321 . 1000) (閏秒がない通常のシステムでは2019-08-17 02:39:31.321 UTCを表す)なら、(decode-time time t t)は((31321 . 1000) 39 2 17 8 2019 6 nil 0)だが(decode-time time t 'integer)は(31 39 2 17 8 2019 6 nil 0)をリターンする。formが省略かnilの場合のデフォルトは現在のところintegerだが、このデフォルトはEmacsの将来バージョンで変更されるかもしれないので、呼び出し側は特定の形式が必要ならformを指定すること。

Common Lispに関する注意: Common Lispではdowとutcoffの意味が異なり、secondは0から59(両端を含む)の整数である。

time値の要素にアクセス(や変更)するためにはアクセッサとしてdecoded-time-second、decoded-time-minute、decoded-time-hour、decoded-time-day、decoded-time-month、decoded-time-year、decoded-time-weekday、decoded-time-dst、decoded-time-zoneを使用できる。

たとえばデコード済みtimeの年を増加するには以下のようにする:

(setf (decoded-time-year decoded-time)
      (+ (decoded-time-year decoded-time) 4))

以下の関数も参照のこと。

Function: decoded-time-add time delta

この関数はデコード済みtime構造を受け取り、delta (これもデコード済みtime構造)を追加する。delta内のnilの要素は無視する。

たとえば“来月同刻”を得るには以下のようにする:

(let ((time (decode-time nil nil t))
      (delta (make-decoded-time :month 2)))
   (encode-time (decoded-time-add time delta)))

この日付が存在しない(たとえば1月31日に実行した)場合には、有効な日付を入手できるまで日付を戻る(2月の28日か29日になるだろう)。

フィールドはもっとも意味をもつ順に追加されるので、上述のような調整が発生したら日時分秒の追加の前に行われる。

値を減算するためにdelta内に負の値を指定できる。

リターン値はデコード済みtime構造。

Function: make-decoded-time &key second minute hour day month year dst zone

リターンされるデコード済みtime構造では、与えられたキーワードだけ充填されて、それ以外はnilのままとなる。たとえば“2ヵ月”を表す構造を得るには:

(make-decoded-time :month 2)

Function: encode-time time &rest obsolescent-arguments

これはtimeをLispタイムスタンプに変換する。これはdecode-timeの逆の関数として機能する。

最初の引数は通常はdecode-timeの形式でデコード済みtimeを指定するリスト(second minute hour day month year ignored dst zone)なので、(encode-time (decode-time ...))は機能する。これらのリストメンバーの意味はdecode-timeの下のテーブルを参照のこと。

廃れた呼び出し規約として、この関数は6つ以上の引数を受け取ることができる。最初の6つの引数second、minute、hour、day、month、yearはデコード済みtimeのほとんどの要素を指定する。7つ目以降の引数があれば、最後の引数はzoneとして使用されれるので、(apply #'encode-time (decode-time ...))は機能する。この廃れた規約においては、zoneのデフォルトはレントタイムゾーンルール(Time Zone Rulesを参照)であり、dstは-1であるかのように扱われる。

100未満の年が特別に扱われることはない。これに1900や2000を超える年を意味させたい場合には、encode-timeを呼び出す前に自身でこれらを修正しなければならない。timeの範囲およびzoneの値はオペレーティングシステムが制限する。

encode-time関数はdecode-timeのラフな逆関数として動作する。たとえば以下のように後者の出力を前者に渡すことができる:

(encode-time (decode-time …))

seconds、minutes、hour、day、monthに範囲外の値を使用することにより単純な日付計算ができる。たとえばdayが0なら与えられたmonthの前月末日になる。