---

41.7 時刻の変換

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

32ビットオペレーティングシステムの多くでは、秒の要素に32ビット情報が含まれるシステム時刻に制限されています。これらのシステムが処理できるのは、通常は協定世界時の1901-12-13 20:45:52から2038-01-19 03:14:07までだけです。ただし64ビットのオペレーティングシステムや一部の32ビットのオペレーティングシステムではより大きな秒の要素をもつことができ、より遠い過去や将来の時刻を表すことができます。

暦変換関数は、たとえグレゴリオ暦導入前の日付であっても常にグレゴリオ暦を使用します。伝統的なグレゴリオ年が行うように0年をスキップせずにBC. 1年から年数を数えます。たとえば年数-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と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の値はオペレーティングシステムが制限する。

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構造体を受け取り、(同じくデコード済みtime構造体である)deltaを加える。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 ¶

与えられたキーワードだけを満たし、他はnilであるようなデコード済みtime構造体をリターンする。たとえば“2ヶ月(two months)”を表すデコード済みtime構造体を得るには以下のようにすればよい:

(make-decoded-time :month 2)

Function: encode-time time &rest obsolescent-arguments ¶

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

最初の要素は、通常は(second minute hour day month year ignored dst zone)のようなリスト。これは(encode-time (decode-time ...))が機能するように、decode-time形式でデコード済みtimeを指定する。リストのこれらのメンバーについてはdecode-timeにあるテーブルを参照のこと。

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