以下の関数はtime値とテキスト文字列の間で変換と逆変換を行います。time値はLispタイムスタンプ(時刻を参照)、またはデコード済みtime構造(時刻の変換を参照)のいずれかで表現されます。
この関数はtime文字列stringをパースして対応するLispタイムスタンプをリターンする。引数stringは日時を表現するparse-time-string
(以下参照)が認識する形式のいずれかであること。この関数はstringに明示的なタイムゾーン情報が欠落していれば万国標準時(Universal
Time)を仮定する。またstringに月、日、時刻がなければ、もっとも過去の値とみなす。timeの範囲およびzoneの値はオペレーティングシステムが制限する。
この関数はtime文字列stringをデコード済みtime構造(時刻の変換を参照)にパースする。引数stringはRFC 822(またはそれ以降)やISO 8601に類似した“Fri, 25 Mar 2016 16:24:56 +0100”や“1998-09-12T12:21:54-0200”のような文字列であることが必要だが、この関数は形式が若干不正なtime文字列のパースも同様に試みる。
この関数はdecode-time (時刻の変換を参照)と異なりtime文字列を解釈しない。特にstring引数の夏時間、タイムゾーン、UTCオフセットの部分の値は日付と時刻の値に反映されず、リターンされるデコード済みtime構造体の最後の2つのメンバーだけに反映されることに注意。たとえばstring内にタイムゾーン情報が与えられてリターンされるデコード済みtime構造体にはタイムゾーン情報が含まれるが、そうでなければリターン値のタイムゾーンメンバーはnilになるだろう。言い方を変えると、これは日付および時刻のテキスト的表現を個別の数値的表現単に解析する関数であり入力時刻がローカルか、あるいはUTCなのかは考慮しない。
Lispプログラムでこの関数のリターン値を他のtime関連APIに渡す場合にはデコード済みtime構造体のnilのメンバーが正しく解釈されること、特に呼び出し元のプログラムのニーズに応じて解釈されるUTCやローカル時刻にタイムゾーン情報がないことに留意すること。
Lispプログラムはこの関数を、より厳格な(無効な入力にはエラーを出力する)関数のかわりに使用できる。これはISO
8601標準の変種をパースできるので、上述のフォーマットに加えて“1998W45-3” (週番号)や“1998-245”
(序数日)のような日付をパースできる。期間(duration)のパースはiso8601-parse-duration、間隔(interval)のパースにはiso8601-parse-intervalがある。これらの関数は最後の関数(それらのうち開始、終了、期間の3つをリターンする)を除いて、すべてデコード済みtime構造をリターンする。
parse-time-stringと同じように、この関数はtime文字列を解釈せず、特にstring引数のタイムゾーン指定やUTCオフセット部分は、リターン値であるデコード済みtime構造体な日付と時刻には反映されず、最後の2つのメンバーだけに影響を与える。ISO8601標準の指定ではUTC関連に関する情報が含まれていないdate文字列およびtime文字列はlocal時刻とみなされるが、この関数はtime値を解釈しないのでその範疇ではない。たとえばstringにタイムゾーン情報が与えられればデコード済みtime構造体に含められるし、与えられなければリターン値のタイムゾーンメンバーはnilになるだろう。言い方を変えると、この関数が行うのは日付や時刻のテキスト標準を個別の数値に解析するだけであって、入力されたtime文字列がローカルかUTCなのかについては考慮しない。
この関数はLispタイムスタンプtime
(省略かnilの場合のデフォルトはカレント時刻)をformat-stringに応じて文字列に変換する。この変換にはタイムゾーンルールzone
(デフォルトはカレントのタイムゾーンルール)を使用する。タイムゾーンのルールを参照のこと。引数format-stringには、時刻を置換する‘%’シーケンスを含めることができる。以下は‘%’シーケンスは何を意味するかのテーブルである:
曜日の短縮名を意味する。
曜日の完全名を意味する。
月の短縮名を意味する。
月の完全名を意味する。
‘%x %X’のシノニム。
これは世紀、つまり年を100で除して小数点以下を切り捨てる。デフォルトのフィールド幅は2。
0パディングされた年月日の日。
‘%m/%d/%y’のシノニム。
ブランクでパディングされた年月日の日。
これは‘%+4Y-%m-%d’のようなISO 8601日付フォーマットと似ているが、‘+’と‘4’を任意のフラグとフィールド幅(6を減じた後)をオーバーライドする点が異なる。
これはカレントのISO週(ISO week)の番号に対応する、世紀部分(00–99)を除いた年を意味する。ISO週は月曜が開始で終了は日曜。ISO週の開始と終了の年が異なる場合に‘%g’が生成する年にたいする規則は複雑であり、ここでは説明しない。しかし一般的には、もし週のうちのほとんどが終了年にあれば‘%g’はその年を生成するだろう。
これはカレントのISO週番号に対応する、世紀を含めた年を意味する。
‘%b’のシノニム。
時分秒の時(00から23)を意味する。
時分秒の時(01から12)を意味する。
年内の経過日(001から366)を意味する。
ブランクでパディングされた時分秒の時(0から23)を意味する。
ブランクでパディングされた時分秒の時(1から12)を意味する。
年月日の月(01から12)を意味する。
時分秒の分(00から59)を意味する。
改行を意味する。
ナノ秒(000000000–999999999)を意味する。より少ない桁数を求める場合にはミリ秒は‘%3N’、マイクロ秒は‘%6N’を使用する。余分な桁は丸めずに切り捨てられる。
必要に応じて‘AM’か‘PM’を意味する。
これはカレンダーの四半期(1–4)を意味する(訳注: 会計年度で使用される4月1日を年度開始日とする四半期ではなく元旦を年度開始日とする四半期)。
‘%I:%M:%S %p’のシノニム。
‘%H:%M’のシノニム。
これはエポック以降の経過秒数を表す整数。
これは秒を意味する(00–59、閏年をサポートするプラットフォームでは00–60)。
タブ文字を意味する。
‘%H:%M:%S’のシノニム。
これは数字で表した曜日(1から7)で、月曜日が1。
週の開始を日曜日とみなした年内の週(01から52)。
これはISO 8601にたいする年内の週を意味する。
数字で表した曜日(0から6)で日曜日が0。
これは週の開始を月曜日とみなした年内の週(01から52)。
これはlocale固有の意味をもつ。デフォルトlocale(Cという名前のlocale)では‘%D’と等価。
これはlocale固有の意味をもつ。デフォルトlocale(Cという名前のlocale)では‘%T’と等価。
世紀を含まない年(00から99)を意味する。
世紀を併なう年を意味する。
タイムゾーンの短縮形(たとえば‘EST’)を意味する。
これはタイムゾーンの数値オフセットを意味する。‘z’の前に1つ、2つ、または3つのコロンを前置できる。単なる‘%z’が‘-0500’を意味する場合には‘%:z’は‘-05:00’、‘%::z’は‘-05:00:00’を意味する。‘%:::z’は‘%::z’と同様だが末尾の‘:00’を無するので、この例では‘-05’を意味する。
これは単独の‘%’を意味する。
‘%’の直後には1つ以上のフラグ文字を記述してもよい。‘0’は0、‘+’は0をパディングして5桁以上の非負の年の前に‘+’を配置、‘_’は空白によるパディング、‘-’はパディングの抑制、‘^’は英大文字、‘#’は文字のcase(大文字小文字)を反転させる。
これらの‘%’シーケンスすべてにたいしてフィールド幅とパディングのタイプの指定でのきる。これはprintfと同じように機能する。フィールド幅は‘%’シーケンス内の任意のフラグの後に数字として記述するたとえば‘%S’は分内で経過した秒数を指定するが、‘%03S’は3箇所の0、‘%_3S’は3箇所にスペースをパディングすることを意味する。ただの‘%3S’は0でパディングを行う。これは‘%S’が通常において2箇所にパディングする方法だからである。
文字‘E’と‘O’は、‘%’シーケンス内のすべてのフラグとフィールド幅の後に使用されたときは修飾子として作用する。‘E’は日付と時刻にカレントlocaleの“代替”バージョンの使用を指定する。たとえば日本のlocaleでは、%Exでは日本の元号にもとづく日付フォーマットを得られるだろう。‘E’では‘%Ec’、‘%EC’、‘%Ex’、‘%EX’、‘%Ey’、‘%EY’の使用が許されている。
‘O’は通常の10進数字(訳注： アラビア数字)ではなく、カレントlocaleの数字の代替表現を使用する。これは数字を出力する、ほとんどすべてのアルファベットで使用が許されている。
デバッグプログラム支援のために、認識されない‘%’シーケンスはそれ自体を意味しており、そのまま出力される。将来のEmacsバージョンでは拡張として新たな‘%’シーケンスが認識されるかもしれないので、プログラムはこの挙動に頼るべきではない。
この関数は処理のほとんどを行うためにCライブラリー関数strftimeを使用している(Formatting Calendar
Time in The GNU C Library Reference
Manualを参照)。その関数とやり取りするために最初にtimeとzoneを内部形式に変換する。timeの範囲およびzoneの値はオペレーティングシステムが制限する。この関数はformat-stringもエンコードする。strftimeが結果文字列をリターンした後に同じコーディングシステムを使用してformat-time-stringはデコードを行う。
この関数は引数secondsをformat-stringに応じた年、日、時、...の文字列に変換する。引数format-stringには変換を制御する‘%’シーケンスを指定することができる。以下のテーブルは‘%’の意味:
年間365日での年の整数。
年月日の日。
時分秒の時の整数。
時分秒の分の整数。
秒数。オプションの‘,’パラメーターが使用されていたらそれは浮動小数点数であり、‘,’の後の数は使用する小数点以下の桁数を指定する。‘%,2s’は“小数点以下2桁の使用”を意味する。
非プリント制御フラグ。これを使用する際には他の指定はサイズ減少順、すなわち年、日、時刻、分、...のように与えなければならない。最初の非0変換に遭遇するまで‘%z’の左側の結果文字列は生成されない。たとえばemacs-uptime
(emacs-uptimeを参照)で使用されるデフォルトフォーマットでは、秒数は常に生成されるが年、日、時、分はそれらが非0の場合のみ生成されるだろう。
‘%z’と同じ行に作用する非プリント制御フラグだが、末尾にある0値のtime要素のプリントを抑制する。
リテラルの‘%’を生成する。
大文字のフォーマットシーケンスは数字に加えて単位を生成するが、小文字フォーマットは数字だけを生成する。
‘%’に続けてフィールド幅を指定できる。指定したフ幅より短ければブランクでパディングされる。この幅の前にオプションでピリオドを指定すれば、かわりに0パディングを要求する。たとえば"%.3Y"は"004
years"を生成するだろう。