"date_in_English": Date notation in English utilities in C
hacker emblem Happy Hacking!


English Here (machine translation)

date_in_English: 西暦日付を扱うユーティリティ

この C 言語ユーティリティは、西暦日付を扱うためのユーティリティです。5 桁以上の半角数字列を yyy...yyymmdd とみなした場合に、西暦日付として正当であるか否かを判定する is_valid_date()、英語表記での日付文字列に変換する date_in_English()、その年の何日目かを求める get_day_of_year()、西暦 1 年 1 月 1 日を 1 とする通算日数を求める days_count()、days_count() で求めた通算日数をベースとした整数値を "YYY...MMDD" 形式 (年は 4 桁以上) の文字列に変換しなおす days_count_to_date_str()、同じく days_count() で求めた通算日数を曜日を表す整数値 (Day_of_week_e 型) と文字列に変換する day_of_week() マクロと day_of_week_str() API、そして、ふたつの日付の経過日数を求める diff_dates() を含みます。

API を使用するためのヘッダは days.h で、API の実装は days.c です。API の説明は、この文書で後述しています。

テスト・プログラム days-test.c そして make ファイル Makefile を記述しました。


API の説明

  1. 半角数字文字列が西暦日付として正当であることを判定する is_valid_date()
    int is_valid_date(char *date, size_t sz)

    date には "yyy...yyymmdd" 形式の半角数字文字列を指定します。
    sz には date の文字列長を指定します。

    "yyy...yyy" に "0" から "4294967295" までの数字列を指定した場合、正当な西暦年であると判定します。ただし、"0" から "999" までの文字列の場合は、西暦 2000 年代を指定したものと解釈します。西暦 1 年から 999 年までを指定するには、"0001" から "0999" とゼロ詰めの半角数字列とする必要があります。

    戻り値は以下の意味を持ちます。

    • DAYS_ILLEGAL_ARGS (= -1) : 不正な引数が渡された場合
    • DAYS_FALSE (= 0) : 西暦日付として不当な文字列の場合
    • DAYS_TRUE (= 1) : 西暦日付として正当な文字列の場合

  2. 半角数字文字列を英語表記の西暦日付に変換する date_in_English()
    char *date_in_English(char *date
    , size_t sz
    , DAYS_FMT fmt
    , char *str
    , size_t str_sz
    )

    date には "yyy...yyymmdd" 形式の半角数字文字列を指定します。
    sz には date の文字列長を指定します。
    fmt には DAYS_FMT_EUROPEAN あるいは DAYS_FMT_AMERICAN のいずれかを指定します。fmt に DAYS_FMT_EUROPEAN を指定すると "<dd>, <月の英語名> <yyy..yyy>" に、DAYS_FMT_AMERICAN を指定すると "<月の英語名> <dd>, <yyy...yyy>" に変換します。
    str には変換後の文字列を出力します。
    str_sz には str が指すメモリ領域のサイズを指定します。

    "yyy...yyy" には is_valid_date() と同じ制限を持ちます。

    戻り値は以下の意味を持ちます。

    • NULL : 不正な引数が渡された場合
    • NULL 以外のアドレス : 変換後の文字列アドレス (str と同じアドレス)

  3. その年の何日目かを求める get_day_of_year()
    int get_day_of_year(char *date, size_t sz)

    date には "yyy...yyymmdd" 形式の半角数字文字列を指定します。
    sz には date の文字列長を指定します。

    "yyy...yyy" には is_valid_date() と同じ制限を持ちます。

    戻り値は以下の意味を持ちます。

    • ゼロ : 不正な引数が渡された場合
    • 1 以上の整数 : その西暦年の何日目であるかの値

  4. 西暦日付の通算日数を求める days_count()
    long long days_count(char *date, size_t sz)

    date には "yyy...yyymmdd" 形式の半角数字文字列を指定します。
    sz には date の文字列長を指定します。

    "yyy...yyy" には is_valid_date() と同じ制限を持ちます。

    戻り値は以下の意味を持ちます。

    • LLONG_MIN : 不正な引数が渡された場合
    • 1 以上の整数 : 西暦 1 年 1 月 1 日の場合を 1 とする西暦通算日数

  5. days_count() で求めた西暦日付の通算日数をベースとする整数値を日付を表す 8 桁以上の数字文字列に変換しなおす days_count_to_date_str()
    char *days_count_to_date_str(long long day_count
    , char *date
    , size_t sz
    )

    day_count には days_count() で求めた西暦日付の通算日数をベースとする 1 以上の整数値を指定します。
    date には "yyyy...mmdd" 形式の 8 桁以上の半角数字文字列を出力できるバッファのアドレスを指定します。
    sz には date のバッファ・サイズを指定します。

    date に出力される半角数字文字列は、sz に指定されたバッファ・サイズが不足している場合を除いて、is_valid_date() と同じ制限を満たします。

    戻り値は以下の意味を持ちます。

    • NULL : 不正な引数が渡された場合 (errno に EINVAL を出力します)
    • 非 NULL : 正常に終了した場合 (date に指定されたアドレスになります)

  6. 西暦日付の曜日を求める day_of_week() and day_of_week_str()
    Day_of_week_e day_of_week(Days_counts)
    char *day_of_week_str(long long days_counts)

    Days_counts あるいは days_counts 引数に days_count() の戻り値を渡されると、曜日を表す整数値 (Day_of_week_e 型) に変換するマクロ day_of_week() と曜日を表す英語表記文字列のアドレスに変換する day_of_week_str() API です。

    Day_of_week_e 型は enum 型として以下のように定義されています。

    Sunday    = 0 /* 日曜日 */
    Monday = 1 /* 月曜日 */
    Tuesday = 2 /* 火曜日 */
    Wednesday = 3 /* 水曜日 */
    Thursday = 4 /* 木曜日 */
    Friday = 5 /* 金曜日 */
    Saturday = 6 /* 土曜日 */
    Illegal_day_of_week = 7 /* 不正な引数 */

    不正な引数 (負数) を渡されると、day_of_week() マクロは Illegal_day_of_week を返し、day_of_week_str() API は NULL を返します。

  7. ふたつの西暦日付の経過日数を求める diff_dates()
    long long diff_dates(char *date1
    , size_t sz1
    , char *date2
    , size_t sz2
    )

    date1 と date2 には "yyy...yyymmdd" 形式の半角数字文字列を指定します。
    sz1 と sz2 には date1 と date2 それぞれの文字列長を指定します。

    "yyy...yyy" には is_valid_date() と同じ制限を持ちます。

    戻り値が LLONG_MIN 以外の値を返した場合、その値は date1 と date2 の経過日数になります。

    • LLONG_MIN : 不正な引数が渡された場合
    • LLONG_MIN より大きな負の整数 : date1 が date2 より過去の西暦日付の場合
    • ゼロ : date1 と date2 が同じ西暦日付である場合
    • ゼロより大きな正の整数 : date1 が date2 より未来の西暦日付の場合