表題

著者

状態

この SRFI は現在「確定」の状態である。SRFI の各状態の説明については ここ を参照せよ。 この SRFI に関する議論については メーリングリストのアーカイブ を参照せよ。

• 草案: 2000-02-28 から 2000-08-28
• 確定: 2000-08-31
• 参照実装の確定: 2003-02-28
• 文書の ~D の誤りを修正: 2003-05-30
• 文書のさまざまな誤りを修正: 2004-03-15

概要

日付は、グレゴリオ暦と、 (ナノ秒精度の) 24 時間形式の時刻と、 UTC からのタイムゾーン オフセットで表現する。 時刻と日付の変換関数や、 日付の文字列表現を読み書きする手続きを提供する。

課題

論拠

仕様

時刻 オブジェクトは、他のデータ型とは異なる型であり、 何らかの標準時システムにおける時刻や時間差を表す。 標準時システムとしては以下のものがある:

• 協定世界時 (UTC)
• 国際原子時 (TAI)
• モノトニック時刻 (何らかのエポックからの単調増加な時刻を表す、実装依存の時刻)
• 現在のスレッドにおける CPU 時刻 (実装依存)
• 現在のプロセスにおける CPU 時刻 (実装依存)
• 時間差 (time duration)

時刻オブジェクトは、次の 3 つの要素で構成される。

• 時刻タイプ: 時刻システムを表すシンボル。 シンボル TIME-TAI, TIME-UTC, TIME-MONOTONIC, TIME-THREAD, TIME-PROCESS, TIME-DURATION は、それぞれの時刻システムを表す。 独自の標準時システムを実装する場合は、そのシンボルを提供すべきである。
• 秒: エポックからの経過秒数を表す整数。
• ナノ秒: 秒の端数を、ナノ秒単位の整数で表す。 時刻オブジェクトはナノ秒の精度を表現できるが、 時刻システムによっては、それより小さい解像度しかもたない場合もある。

日付オブジェクトは、他のデータ型とは異なる型であり、 グレゴリオ暦の時刻とタイムゾーンを表す。 日付は変更不可能 (immutable) なオブジェクトである。 日付は以下の要素で構成される。

• ナノ秒: 0 から 9,999,999 までの整数
• 秒: 0 から 60 までの整数 (60 は閏秒を表す)
• 分: 0 から 59 までの整数
• 時: 0 から 23 までの整数
• 日: 0 から 31 までの整数で、上限は月と年により決まる。
• 月: 1 から 12 までの整数
• 年: 年を表す整数
• タイムゾーン: タイムゾーンを GMT から東への秒数で表した整数

ユリウス日 は -4714-11-24T12:00:00Z (-4714年11月24日の正午, UTC) からの日数を実数で表現する時刻表現である。

準ユリウス日 は 1858-11-17T00:00:00Z (1858年11月17日の夜中, UTC) からの日数を実数で表現する時刻表現である。

定数

以下の定数を提供しなければならない。

time-duration

時間差を表すシンボル

time-monotonic

モノトニック時刻を表すシンボル

time-process

現在のプロセスの経過時間を表すシンボル

time-tai

TAI 時刻を表すシンボル

time-thread

現在のスレッドの経過時間を表すシンボル

time-utc

UTC 時刻を表すシンボル

現在の時刻と時計の解像度

以下の手続きを提供しなければならない。

current-date [tz-offset] -> date

現在の UTC 時刻に対応する日付。

current-julian-day -> jdn

現在のユリウス日。

current-modified-julian-day -> mjdn

現在の準ユリウス日。

current-time [time-type] -> time

現在の時刻を、時刻タイプ time-type の時刻システムで返す。 デフォルトの時刻タイプは TIME-UTC である。

time-resolution [time-type] -> integer

時刻タイプ time-type の時刻システムの解像度をナノ秒単位で返す。 デフォルトの時刻タイプは TIME-UTC である。

時刻オブジェクトとアクセッサ

以下の手続きを提供しなければならない。

make-time type nanosecond second -> time

時刻オブジェクトを作成する。

time? object -> boolean

時刻オブジェクトであれば #t を返し、 そうでなければ #f を返す。

time-type time -> time-type

時刻タイプ。

time-nanosecond time -> integer

ナノ秒。

time-second time -> integer

秒。

set-time-type! time time-type

時刻タイプを設定する。 ノート: この手続きを呼び出すと、時刻オブジェクトの表す時刻が変化する。 時刻システムの間で時刻を変換するためには、後述の変換手続きを使用すること。

set-time-nanosecond! time integer

ナノ秒を設定する。

set-time-second! time integer

秒を設定する。

copy-time time1 -> time2

time1 と同じ時刻タイプ、ナノ秒、秒をもつ 新しい時刻オブジェクトを作成する。

時刻の比較手続き

時刻の比較手続きでは、比較する時刻オブジェクトが同じ時刻タイプをもたなければらない。 異なる時刻タイプをもつ時刻オブジェクトに対して 比較手続きを呼び出すことはエラーである。 時刻を表す時刻システム (TIME-TAI や TIME-UTC) に対しては、比較の意味を (括弧外の) 通常の文章で説明している。 時間差を表す時刻システム (TIME-DURATION や TIME-CPU) に対しては、比較の意味を括弧内で説明している。

以下の手続きを提供しなければならない。

time<=? time1 time2 -> boolean

time1 が time2 以前であれば (以下であれば) #t を返し、そうでなければ #f を返す。

time<? time1 time2 -> boolean

time1 が time2 より前であれば (小さければ) #t を返し、そうでなければ #f を返す。

time=? time1 time2 -> boolean

time1 が time2 と同じであれば (等しければ) #t を返し、そうでなければ #f を返す。

time>=? time1 time2 -> boolean

time1 が time2 以後であれば (以上であれば) #t を返し、そうでなければ #f を返す。

time>? time1 time2 -> boolean

time1 が time2 より後であれば (大きければ) #t を返し、そうでなければ #f を返す。

時刻の演算手続き

以下の手続きを提供しなければならない。

time-difference time1 time2 -> time-duration

time1 と time2 の間の TIME-DURATION を返す。 time1 と time2 の時刻タイプが異なる場合は、エラーである。 新しい時刻オブジェクトを作成して返す。

time-difference! time1 time2 -> time-duration

time1 と time2 の間の TIME-DURATION を返す。 time1 と time2 の時刻タイプが異なる場合は、エラーである。 time1 を破壊的に使用して戻り値の TIME-DURATION オブジェクトを返してもよい。

add-duration time1 time-duration -> time

time1 に time-duration を加算した時刻を返す。 戻り値は time1 と同じ時刻タイプの時刻オブジェクトである。 新しい時刻オブジェクトを作成して返す。

add-duration! time1 time-duration -> time

time1 に time-duration を加算した時刻を返す。 戻り値は time1 と同じ時刻タイプの時刻オブジェクトである。 time1 を破壊的に使用して戻り値のオブジェクトを返してもよい。

subtract-duration time1 time-duration -> time

time1 から time-duration を減算した時刻を返す。 戻り値は time1 と同じ時刻タイプの時刻オブジェクトである。 新しい時刻オブジェクトを作成して返す。

subtract-duration! time1 time-duration -> time

time1 から time-duration を減算した時刻を返す。 戻り値は time1 と同じ時刻タイプの時刻オブジェクトである。 time1 を破壊的に使用して戻り値のオブジェクトを返してもよい。

日付オブジェクトとアクセッサ

日付オブジェクトは、いったん作成すると変更することはできない。 以下の手続きを提供しなければならない。

make-date nanosecond second minute hour day month year zone-offset -> date

日付オブジェクトを作成する。

date? date -> boolean

時刻オブジェクトであれば #t を返し、そうでなければ #f を返す。

date-nanosecond date -> integer

ナノ秒。

date-second date -> integer

秒。

date-minute date -> integer

分

date-hour date -> integer

時。

date-day date -> integer

日。

date-month date -> integer

月。

date-year date -> integer

年。

date-zone-offset date -> integer

タイムゾーン オフセット。

date-year-day date -> integer

その年の何番目の日であるかを返す。1月1日であれば 1 を返す。

date-week-day date -> integer

日付の曜日を返す。日曜日=0, 月曜日=1 など。

date-week-number date day-of-week-starting-week -> integer

その日を含む週がその年の何番目の週であるかを返す。 ただし、その年の最初の７日に満たない週は無視する。 'day-of-week-starting-week' 引数は、週の最初の曜日を整数で指定する (日曜日=0, 月曜日=1 など)。

時刻/日付/ユリウス日/準ユリウス日の変換

date->julian-day date -> jd

日付をユリウス日に変換する。

date->modified-julian-day date -> mjd

日付を準ユリウス日に変換する。

date->time-monotonic date -> time-monotonic

日付をモノトニック時刻に変換する。

date->time-tai date -> time-tai

日付を TAI 時刻に変換する。

date->time-utc date -> time-utc

日付を UTC 時刻に変換する。

julian-day->date jd [tz-offset] -> date

タイムゾーン オフセットを使用して、ユリウス日を日付に変換する。 タイムゾーンのデフォルトは、ローカル タイムゾーンである。

julian-day->time-monotonic jd -> time-monotonic

ユリウス日をモノトニック時刻に変換する。

julian-day->time-tai jd -> time-tai

ユリウス日を TAI 時刻に変換する。

julian-day->time-utc jd -> time-utc

ユリウス日を UTC 時刻に変換する。

modified-julian-day->date mjd [tz-offset] -> date

タイムゾーン オフセットを使用して、準ユリウス日を日付に変換する。 タイムゾーンのデフォルトは、ローカル タイムゾーンである。

modified-julian-day->time-monotonic mjd -> time-monotonic

準ユリウス日をモノトニック時刻に変換する。

modified-julian-day->time-tai mjd -> time-tai

準ユリウス日を TAI 時刻に変換する。

modified-julian-day->time-utc mjd -> time-utc

準ユリウス日を UTC 時刻に変換する。

time-monotonic->date time-monotonic [tz-offset] -> date

タイムゾーン オフセットを使用して、モノトニック時刻を日付に変換する。 タイムゾーンのデフォルトは、ローカル タイムゾーンである。

time-monotonic->julian-day time-monotonic -> jd

モノトニック時刻をユリウス日に変換する。

time-monotonic->modified-julian-day time-monotonic -> mjd

モノトニック時刻を準ユリウス日に変換する。

time-monotonic->time-tai time-monotonic -> time-tai

モノトニック時刻を TAI 時刻に変換する。

time-monotonic->time-tai! time-monotonic -> time-tai

モノトニック時刻を TAI 時刻に変換する。時刻構造体は再利用される可能性がある。

time-monotonic->time-utc time-monotonic -> time-utc

モノトニック時刻を UTC 時刻に変換する。

time-monotonic->time-utc! time-monotonic -> time-utc

モノトニック時刻を UTC 時刻に変換する。時刻構造体は再利用される可能性がある。

time-tai->date time-tai [tz-offset] -> date

タイムゾーン オフセットを使用して、TAI 時刻を日付に変換する。 タイムゾーンのデフォルトは、ローカル タイムゾーンである。

time-tai->julian-day time-tai -> jd

TAI 時刻をユリウス日に変換する。

time-tai->modified-julian-day time-tai -> mjd

TAI 時刻を準ユリウス日に変換する。

time-tai->time-monotonic time-tai -> time-monotonic

TAI 時刻をモノトニック時刻に変換する。

time-tai->time-monotonic! time-tai -> time-monotonic

TAI 時刻をモノトニック時刻に変換する。時刻構造体は再利用される可能性がある。

time-tai->time-utc time-tai -> time-utc

TAI 時刻を UTC 時刻に変換する。

time-tai->time-utc! time-tai -> time-utc

TAI 時刻を UTC 時刻に変換する。時刻構造体は再利用される可能性がある。

time-utc->date time-utc [tz-offset] -> time-utc

タイムゾーン オフセットを使用して、UTC 時刻を日付に変換する。 タイムゾーンのデフォルトは、ローカル タイムゾーンである。

time-utc->julian-day time-utc -> jd

UTC 時刻をユリウス日に変換する。

time-utc->modified-julian-day time-utc -> mjd

UTC 時刻を準ユリウス日に変換する。

time-utc->time-monotonic time-utc -> time-monotonic

UTC 時刻をモノトニック時刻に変換する。

time-utc->time-monotonic! time-utc -> time-monotonic

UTC 時刻をモノトニック時刻に変換する。時刻構造体は再利用される可能性がある。

time-utc->time-tai time-utc -> time-tai

UTC 時刻を TAI 時刻に変換する。

time-utc->time-tai! time-utc -> time-tai

UTC 時刻を TAI 時刻に変換する。時刻構造体は再利用される可能性がある。

日付と文字列の変換

date->string date [format-string] -> string

形式文字列を使用して、日付を文字列に変換する。 形式文字列は、(チルダで記述する) エスケープ文字が置換されることを除けば、 そのままコピーされる。 エスケープ文字の置換の仕様を表 1 に示す。 実装によっては、この仕様を拡張してもよい。

string->date input-string template-string -> date

入力文字列をテンプレート文字列にしたがって日付に変換する。 入力文字列は、テンプレート文字列の (チルダで記述する) エスケープ文字を除いては、 そのままマッチしなければならない。 エスケープ文字は特殊な変換を表し、次のように解釈される。 (1) 入力文字列の中で、基準を満たす次の文字の位置まで移動する。 (2) その位置から値を読み取る。 (3) 読み取った値を使用して、何らかの操作を行う。 変換の仕様を表 2 に示す。 実装によっては、この仕様を拡張してもよい。

実装

TAI と UTC の差異は決定論的ではなく、 TAI 時刻を取得するための方法を提供しなければならない。 参照実装では、米国海軍観測所の時刻サービスが提供している閏秒テーブル (ftp://maia.usno.navy.mil/ser7/tai-utc.dat から入手できる) を読み取るための手続きを用意した。

この実装では 「SRFI 6: 基本的な文字列ポート」 を使用している。また error 手続きの存在を仮定している。 それから 「SRFI 8: receive による多重値の束縛」 も使用している。 この receive 構文は次のようにして容易に実装できる。

(define-syntax receive
  (syntax-rules ()
    ((receive formals expression body ...)
     (call-with-values (lambda () expression)
                       (lambda formals body ...)))))

参照実装には TAI-UTC.DAT リーダーが含まれている。

参照実装は MzScheme で実装した。 MzScheme は current-seconds 手続きを提供しており、 これは 1970-01-01T00:00:00Z+00:00 からの経過秒数 (UTC) を返す。 また current-milliseconds 手続きも提供しており、 これは、モノトニックなタイムクロックを返す。 この２つを組み合わせることで、 (current-time time-utc) を実装している。 この実装では、モノトニック時刻は TAI 時刻と同じである。 TAI と UTC の差異は閏秒テーブルにより補正される。 国際地球回転観測事業 (IERS: International Earth Rotation Service) によると、2000年12月には閏秒はないだろうとのことだ。 したがって、閏秒テーブルは 2000年1月までは正確であることが保証される。

また、MzScheme は (確か version 102 の時点では)、 SECONDS->DATE と CURRENT-DATE 手続きを介して、 現在のタイムゾーン オフセットを取得する方法を提供している。

時刻と日付のオブジェクトを定義するために MzScheme の DEFINE-STRUCT を使用した。 これの代わりに「SRFI 9: レコード型の定義」 を使うこともできるだろう。

内部的に使用する手続きは TM: で始まる名前にした。 ロケール関係の定数と手続きの名前には locale が含まれている。 将来、ロケール関係の SRFI が定義されるなら、 代わりにそのコードを使うほうがよいだろう。

これらを基礎として、参照実装の残りの部分が実装されている。

テストコードも用意した。

謝辞

前のバージョンの草案に対しては、 Mike Sperber, Marc Feely, Dave Mason, および "Prfnoff" も有用なコメントをくれた。 Shriram Krishnamurthi は編集上の助けをしてくれて感謝する。

DATE->STRING 手続きは GNU C の date 関数と scsh の FORMAT-DATE 手続きをベースにした書式文字列を使用している。

著作権

Copyright (C) Neodesic Corporation (2000). All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.