GNU Emacs Lisp Reference Manual: Time Parsing

41.8 時刻のパースとフォーマット

以下の関数はtime値と文字列内のテキストの変換と逆変換を行います。time値にはnil、整数、およびLispタイムスタンプが含まれます(Time of Dayを参照)。

Function: date-to-time string: この関数はtime文字列stringをパースして対応するLispタイムスタンプをリターンする。引数stringは日時を表現するparse-time-string (以下参照)が認識する形式のいずれかであること。この関数はstringに明示的なタイムゾーン情報が欠落していれば万国標準時(Universal Time)を仮定する。timeの範囲およびzoneの値はオペレーティングシステムが制限する。

Function: parse-time-string string

この関数はtime文字列stringを以下の形式のリストにパースする:

(sec min hour day mon year dow dst tz)

このリストのフォーマットはdecode-timeが受け取るフォーマットと同じであり、詳細はそこに説明してある(Time Conversionを参照)。入力から判断できないdst要素は-1、それ以外の未知の要素はすべてnilにセットされる。引数stringはRFC 822(またはそれ以降)やISO 8601に類似した“Fri, 25 Mar 2016 16:24:56 +0100”や“1998-09-12T12:21:54-0200”のような文字列であることが必要だが、この関数は形式が若干不正なtime文字列のパースも同様に試みる。

Function: iso8601-parse string: より厳格な(無効な入力にはエラーを出力する)関数のかわりに、この関数を使用できる。これはISO 8601標準の変種をパースできるので、上述のフォーマットに加えて“1998W45-3” (週番号)や“1998-245” (序数日)のような日付をパースできる。期間(duration)のパースはiso8601-parse-duration、間隔(interval)のパースにはiso8601-parse-intervalがある。これらの関数は最後の関数(それらのうち開始、終了、期間の3つをリターンする)を除いて、すべてデコード済みtime構造をリターンする。

Function: format-time-string format-string &optional time zone

この関数はtime (省略かnilならカレント時刻)をformat-stringに応じて文字列に変換する。この変換にはタイムゾーンルールzone (デフォルトはカレントのタイムゾーンルール)を使用する。Time Zone Rulesを参照のこと。引数format-stringには、時刻を置換する‘%’シーケンスを含めることができる。以下は‘%’シーケンスは何を意味するかのテーブルである:

‘%a’: 曜日の短縮名を意味する。
‘%A’: 曜日の完全名を意味する。
‘%b’: 月の短縮名を意味する。
‘%B’: 月の完全名を意味する。
‘%c’: ‘%x %X’のシノニム。
‘%C’: これは世紀、つまり年を100で除して小数点以下を切り捨てる。デフォルトのフィールド幅は2。
‘%d’: 0パディングされた年月日の日。
‘%D’: ‘%m/%d/%y’のシノニム。
‘%e’: ブランクでパディングされた年月日の日。
‘%F’: これは‘%+4Y-%m-%d’のようなISO 8601日付フォーマットと似ているが、‘+’と‘4’を任意のフラグとフィールド幅(6を減じた後)をオーバーライドする点が異なる。
‘%g’: これはカレントのISO週(ISO week)の番号に対応する、世紀部分(00–99)を除いた年を意味する。ISO週は月曜が開始で終了は日曜。ISO週の開始と終了の年が異なる場合に‘%g’が生成する年にたいする規則は複雑であり、ここでは説明しない。しかし一般的には、もし週のうちのほとんどが終了年にあれば‘%g’はその年を生成するだろう。
‘%G’: これはカレントのISO週番号に対応する、世紀を含めた年を意味する。
‘%h’: ‘%b’のシノニム。
‘%H’: 時分秒の時(00から23)を意味する。
‘%I’: 時分秒の時(01から12)を意味する。
‘%j’: 年内の経過日(001から366)を意味する。
‘%k’: ブランクでパディングされた時分秒の時(0から23)を意味する。
‘%l’: ブランクでパディングされた時分秒の時(1から12)を意味する。
‘%m’: 年月日の月(01から12)を意味する。
‘%M’: 時分秒の分(00から59)を意味する。
‘%n’: 改行を意味する。
‘%N’: ナノ秒(000000000–999999999)を意味する。より少ない桁数を求める場合にはミリ秒は‘%3N’、マイクロ秒は‘%6N’を使用する。余分な桁は丸めずに切り捨てられる。
‘%p’: 必要に応じて‘AM’か‘PM’を意味する。
‘%q’: これはカレンダーの四半期(1–4)を意味する(訳注: 会計年度で使用される4月1日を年度開始日とする四半期ではなく元旦を年度開始日とする四半期)。
‘%r’: ‘%I:%M:%S %p’のシノニム。
‘%R’: ‘%H:%M’のシノニム。
‘%s’: これはエポック以降の経過秒数を表す整数。
‘%S’: これは秒を意味する(00–59、閏年をサポートするプラットフォームでは00–60)。
‘%t’: タブ文字を意味する。
‘%T’: ‘%H:%M:%S’のシノニム。
‘%u’: これは数字で表した曜日(1から7)で、月曜日が1。
‘%U’: 週の開始を日曜日とみなした年内の週(01から52)。
‘%V’: これはISO 8601にたいする年内の週を意味する。
‘%w’: 数字で表した曜日(0から6)で日曜日が0。
‘%W’: これは週の開始を月曜日とみなした年内の週(01から52)。
‘%x’: これはlocale固有の意味をもつ。デフォルトlocale(Cという名前のlocale)では‘%D’と等価。
‘%X’: これはlocale固有の意味をもつ。デフォルトlocale(Cという名前のlocale)では‘%T’と等価。
‘%y’: 世紀を含まない年(00から99)を意味する。
‘%Y’: 世紀を併なう年を意味する。
‘%Z’: タイムゾーンの短縮形(たとえば‘EST’)を意味する。
‘%z’: これはタイムゾーンの数値オフセットを意味する。‘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はデコードを行う。

Function: format-seconds format-string seconds

この関数は引数secondsをformat-stringに応じた年、日、時、...の文字列に変換する。引数format-stringには変換を制御する‘%’シーケンスを指定することができる。以下のテーブルは‘%’の意味:

‘%y’
‘%Y’: 年間365日での年の整数。
‘%d’
‘%D’: 年月日の日。
‘%h’
‘%H’: 時分秒の時の整数。
‘%m’
‘%M’: 時分秒の分の整数。
‘%s’
‘%S’: 秒数。オプションの‘,’パラメーターが使用されていたらそれは浮動小数点数であり、‘,’の後の数は使用する小数点以下の桁数を指定する。‘%,2s’は“小数点以下2桁の使用”を意味する。
‘%z’: 非プリント制御フラグ。これを使用する際には他の指定はサイズ減少順、すなわち年、日、時刻、分、...のように与えなければならない。最初の非0変換に遭遇するまで‘%z’の左側の結果文字列は生成されない。たとえばemacs-uptime (emacs-uptimeを参照)で使用されるデフォルトフォーマットでは、秒数は常に生成されるが年、日、時、分はそれらが非0の場合のみ生成されるだろう。
‘%%’: リテラルの‘%’を生成する。

大文字のフォーマットシーケンスは数字に加えて単位を生成するが、小文字フォーマットは数字だけを生成する。

‘%’に続けてフィールド幅を指定できる。指定したフ幅より短ければブランクでパディングされる。この幅の前にオプションでピリオドを指定すれば、かわりに0パディングを要求する。たとえば"%.3Y"は"004 years"を生成するだろう。