strptime - ライブラリコールの説明 - Linux コマンド集 一覧表
名前
strptime - 文字列であらわされている時間を tm 構造体の時間に変換する
書式
#define _XOPEN_SOURCE
/* glibc2 では、これが必要。 */
#include <time.h>
char *strptime(const char *
s
, const char *
format
,
struct tm *
tm
);
説明
strptime ()関数は strftime ()の逆関数であり、ポインタ s が指す文字列を時間に変換する。 変換の際には format で指定したフォーマットを用い、値はポインタ tm が指す tm 構造体に収められる。 format は、 scanf (3) で使われているような、 フィールドディスクリプターとテキスト文字で構成されている文字列である。 個々のフィールドディスクリプターは % とそれに続く文字からなり、 後者にフィールドディスクリプターを置き換える内容を指定する。 format 文字列中の他の全ての文字には、入力文字列にマッチする文字がなければならない。 フォーマット文字列中にある空白は例外であり、 入力文字列中の 0 個以上の空白とマッチする。 2 つのフィールドディスクリプターの間には、 空白・英字・数字がなければならない。
strptime () 関数は、入力文字列を左から右へ処理する。 入力された 3 つの要素 (空白・文字・フォーマット) は、順に処理される。 入力がフォーマット文字列とマッチできない場合、関数は停止する。 残りのフォーマット文字列と入力文字列は処理されない。
使用可能なフィールドディスクリプターを以下に挙げる。 (曜日や月の名前といった) 文字列をマッチさせる場合、 大文字と小文字は区別せずに比較する。 数をマッチさせる場合、前に 0 をつけても構わないが必ずしも必要ではない。
- %%
- 文字としての % 。
- %a または %A
- 現在のロケールでの曜日名 (省略名または完全な名前)。
- %b または %B または %h
- 現在のロケールでの月名 (省略名または完全な名前)。
- %c
- 現在のロケールでの日付と時刻の表現。
- %C
- 1 世紀中の年 (0-99)。
- %d または %e
- 月内の日付 (1-31)。
- %D
- 日付。%m/%d/%y と同じ。 (これはアメリカ式の日付形式で、 ヨーロッパでは特に %d/%m/%y という形式が広く使われているために、 アメリカ人以外には紛らわしく感じられる。 ISO 8601 規格では %Y-%m-%d という形式である。)
- %H
- 時間 (0-23)。
- %I
- 12 時間制での時間 (1-12)。
- %j
- 年の初めからの通算の日付 (1-366)。
- %m
- 数字表現の月 (1-12)。
- %M
- 分 (0-59)。
- %n
- 任意の空白。
- %p
- ロケールの AM (午前) と PM (午後) に対応するもの。 (注意: 対応するものがないかもしれない。)
- %r
- (ロケールの AM と PM を使った) 12 時間制の時間。 POSIX ロケールでは %I:%M:%S %p と同じ。 現在のロケールにおいて LC_TIME パートの t_fmt_ampm が定義されていない場合、 動作は未定義である。
- %R
- %H:%M と同じ。
- %S
- 秒 (0-60; 60 は閏秒を示す。以前は 61 も指定できた)。
- %t
- 任意の空白。
- %T
- %H:%M:%S と同じ。
- %U
- 日曜日を週の始まりとした年通算での週数 (0-53)。 1 月の最初の日曜日を第 1 週目の最初の日する。
- %w
- 日曜日を 0 とした数字表記の曜日 (0-6)。
- %W
- 月曜日を週の始まりとした年通算での週数 (0-53)。 1 月の最初の月曜日を第 1 週目の最初の日する。
- %x
- 日付。ロケールの日付フォーマットを使う。
- %X
- 時刻。ロケールの時刻フォーマットを使う。
- %y
- 1 世紀中の年 (0-99)。 世紀が指定されない場合、 値が 69-99 の範囲のときは 20 世紀の年 (1969-1999)、 値が 00-68 の範囲のときは 21 世紀の年 (2000-2068) とする。
- %Y
-
年。世紀の部分を含む (例: 1991)。
E や O という修正子を使うことで変更できるフィールドディスクリプタもある。 これらの修正子は、別のフォーマットや仕様を使うことを指示する。 別のフォーマットや仕様が現在のロケールに存在しないときは、 変更していないフィールドディスクリプタが使われる。
E 修正子は、ロケールに依存した日付と時刻の別の表現形式が 入力文字列に含まれていることを指定する。
- %Ec
- 日付と時刻。ロケールに依存した別の表現形式を使う。
- %EC
- 基準年 (期間) の名前。ロケールに依存した別の表現形式を使う。
- %Ex
- 日付。ロケールに依存した別の表現形式を使う。
- %EX
- 時刻。ロケールに依存した別の表現形式を使う。
- %Ey
- %EC (年のみ) からのオフセット。ロケールに依存した別の表現形式を使う。
- %EY
-
完全な形式の年。別の表現型式を使う。
O 修正子は、ロケールに依存した別のフォーマットの中に 数値の入力があることを指定する。
- %Od または %Oe
- 月の初めからの通算の日付。ロケールに依存した別の数値シンボルを使う。 0 を頭につけてもよいが、必須ではない。
- %OH
- 時間 (24 時間制)。ロケールに依存した別の数値シンボルを使う。
- %OI
- 時間 (12 時間制)。ロケールに依存した別の数値シンボルを使う。
- %Om
- 月。ロケールに依存した別の数値シンボルを使う。
- %OM
- 分。ロケールに依存した別の数値シンボルを使う。
- %OS
- 秒。ロケールに依存した別の数値シンボルを使う。
- %OU
- 年の初めからの通算の週数 (日曜日を週の始めとする)。 ロケールに依存した別の数値シンボルを使う。
- %Ow
- 数値表記の曜日 (日曜日を 0 とする)。 ロケールに依存した別の数値シンボルを使う。
- %OW
- 年の初めからの通算の週数 (月曜日を週の始めとする)。 ロケールに依存した別の数値シンボルを使う。
- %Oy
-
年 (%C からのオフセット)。ロケールに依存した別の数値シンボルを使う。
要素別の時刻構造体 tm は <time.h> 内で以下の様に定義されている。
struct tm { int tm_sec; /* 秒 */ int tm_min; /* 分 */ int tm_hour; /* 時間 */ int tm_mday; /* 日 */ int tm_mon; /* 月 */ int tm_year; /* 年 */ int tm_wday; /* 曜日 */ int tm_yday; /* 年内通算日 */ int tm_isdst; /* 夏時間 */ };
返り値
この関数の返り値は、関数の中で処理されなかった最初の文字へのポインタである。 フォーマット文字列が必要する以上の文字が入力文字列に含まれている場合、 返り値は最後に処理された入力文字の次の文字を指す。 すべての入力文字列が処理された場合、 返り値は文字列末尾の NULL バイトを指す。 strptime () がフォーマット文字列のすべての比較に失敗し、 エラーが起こった場合、関数は NULL ポインタを返す。
準拠
SUSv2, POSIX.1-2001.
例
以下の例は strptime
() と strftime
() の使用法を示している。
#include <stdio.h> #include <time.h>
int main() { struct tm tm; char buf[255];
strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm); strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm); puts(buf); return 0; }
GNU 版での拡張
対象性のために、glibc では strptime ()に strftime ()と同じフォーマット文字をサポートさせようとしている。 多くの場合、対応するフィールドが解釈されるが、 tm フィールドは変更されない。 使用可能なフォーマット文字を以下に示す。
- %F
- %Y-%m-%d と同じ。ISO 8601 の日付形式。
- %g
- ISO 週数に対応した西暦年。世紀は含まず (0-99) の範囲。
- %G
- ISO 週数に対応した西暦年 (例えば 1991)。
- %u
- 10 進数表記の曜日 (1-7 で月曜日を 1 とする)。
- %V
- ISO 8601:1988 形式での年通算の 10 進数表記での週数 (1-53)。 1 月 1 日を含む (月曜日から始まる) 週に 4 日以上が含まれている場合は、 その週を第 1 週とする。 3 日以下しか含まれていない場合は、1 月 1 日を含む週を前年の最終の週として、 次の週を第 1 週とする。
- %z
- RFC-822/ISO 8601 標準タイムゾーンを指定する。
- %Z
-
タイムゾーン名。
同様にして、strftime () の GNU 版での拡張のために、 %k は %H、%l は %I、%P は %p と同じく扱われる。 さらに
- %s
-
紀元年 (例えば 1970-01-01 00:00:00 UTC) からの通算の秒数。
閏秒がサポートされていない限り、閏秒はカウントしない。
GNU libc における実装では、2 つのフィールド間の空白は必要ない。
注意
原則として、この関数は tm の初期化はせずに、 指定された値のみを入れる。 つまり、この関数の呼び出しの前に tm を初期化しなければならない。 他の Unix システムとは、細かい点で異なる。 GNU libc の実装では、明示的に指定されないフィールドは変更されない。 例外として、年・月・日のいずれかの要素が変更された場合に tm_wday と tm_yday が再計算される。
この関数は、libc 4.6.8 以降で使用できる。 Linux の libc4 と libc5 のインクルードファイルは、 この関数のプロトタイプを常に定義する。 glibc2 のインクルードファイルは、 _XOPEN_SOURCE または _GNU_SOURCE が定義された場合のみ、 この関数のプロトタイプを提供する。
libc 5.4.13 より前では、空白 (と 'n' または 't' 指定) は扱われなかった。 ロケールの修正子 'E' と 'O' は受け付けられなかった。 また、'C' の指定は 'c' の指定と同じ意味で扱われた。
y' (1 世紀中の年) の指定は、libc4 と libc5 では 20 世紀の年として解釈される。 glibc 2.0 では 1950-2049 の範囲として解釈される。 glibc 2.1 からは 1969-2068 の範囲として解釈される。
