9.8. データ型書式設定関数

PostgreSQL の書式設定関数は多彩なデータ型（日付/時刻データ型、整数データ型、浮動小数点数データ型、数値データ型）を整形された文字列に変換したり、整形された文字列を特定のデータ型に変換する強力なツールの一式を提供しています。 表9-21 にこれらを列挙しています。 これら関数は共通の呼び出し規約を踏襲しています。最初の引数は整形される値で2番目の引数は入力書式または出力書式を定義するテンプレートです。

単一引数の to_timestamp 関数も利用可能です。 これは double precision 型の引数を取り、Unix時刻（1970-01-01 00:00:00+00からの秒数）から timestamp with time zone に変換します。 （ Integer 型のUnix時刻は暗黙的に double precision にキャストされます。）

（ to_char 用）出力テンプレート文字列には、値に基づいて認識され、適切に整形されたデータで置き換えられるパターンがあります。 テンプレートパターンではない全てのテキストは単にそのままコピーされます。 同様に、（その他の関数に対し）入力テンプレート文字列では、テンプレートパターンは入力されたデータ文字列で供給される値を特定します。

表9-22 に、日付/時刻型の値の書式に使用可能なテンプレートパターンを示します。

修飾子はどのようなテンプレートパターンに対しても、その振舞いを変更するために適用することができます。 例えば、 FMMonth は FM 修飾子の付いた Month パターンです。 表9-23 に、日付/時刻書式の修飾子パターンを示します。

日付/時刻型書式の使用上の注意事項は次のとおりです。

• FM はパターンの出力を固定長にするため、先頭にはゼロ、末尾には空白を追加してしまう機能を無効にします。 PostgreSQL では、 FM はその次に記述されたものだけを変更します。一方Oracleでは、 FM はそれに続く全ての記述に対して影響し、 FM 修飾詞の切り替えに応じて繰り返されます。

• TM には末尾の空白は含まれません。

• FX オプションがテンプレートが使用されている場合を除き、 to_timestamp と to_date は入力文字列の複数の空白スペースを無視します。 例えば、 to_timestamp にはたった1つのスペースがあることになっているので、 to_timestamp('2000    JUN', 'YYYY MON') は動作しますが、 to_timestamp('2000    JUN','FXYYYY MON') はエラーを返します。 FX はテンプレートの第1項目として指定される必要があります。

• to_timestamp と to_date は単純なキャストでは変換できない入力書式を扱うために存在します。 この関数は最低限のエラー検査で入力を自由に解釈します。 有効な出力を生成しますが、変換は思わぬ結果を生じることがあります。 例えば、この関数への入力は通常の範囲で制限されてはいませんので、 to_date('20096040','YYYYMMDD') はエラーを起こすのではなく、 2014-01-17 を返します。 キャストにはこのような動作はありません。

• to_char テンプレートでは、通常のテキストが許され、そのまま出力されます。 部分文字列を二重引用符で括ることで、部分文字列にパターン用のキーワードがあったとしても、強制的にリテラルテキストとして解釈させることができます。 例えば、 '"Hello Year "YYYY' では YYYY は年データに置換されてしまいますが、 Year 内の Y は置換されません。 to_date 、 to_number 、 to_timestamp では、二重引用符で括られた文字の数だけ入力された文字をスキップします。例えば "XX" が指定された場合は2文字がスキップされます。

• 出力に二重引用符を付けたい場合、 '\"YYYY Month\"' のようにその前にバックスラッシュを付けなければなりません。

• もし、 YYY の様に4桁未満の年書式が指定され、かつ与えられる年が4桁未満だった場合、年は2020年に最も近くなるよう調整されます。例えば、 95 の場合は1995年になります。

• 文字列を timestamp 型もしくは date 型にする YYYY 変換は、4桁以上の年数値を処理するとき制限が加えられます。 このような場合、数字以外の文字または YYYY の後にテンプレートを使わなければなりません。 そうしないと年は常に4桁と解釈されます。 例えば（20000年として）、 to_date('200001131', 'YYYYMMDD') は4桁の年と解釈されるので、 to_date('20000-1131', 'YYYY-MMDD') または to_date('20000Nov31', 'YYYYMonDD') のように数字でない区切り符号の使用をお勧めします。

• 文字列から timestamp もしくは date への変換において、 YYY 、 YYYY 、もしくは Y,YYY フィールドが存在すると CC （世紀）フィールドは無視されます。 CC が YY もしくは Y と共に使用されると、指定された世紀の年と計算されます。 世紀が指定され、年が指定されないときは、その世紀の最初の年と想定されます。

• ISO 8601週番号日は（グレゴリオ暦の日付とは異なって） to_timestamp と to_date の２つの方法のうちのひとつで指定できます。

  • 年、通年の週番号、週の曜日番号。 例えば、 to_date('2006-42-4', 'IYYY-IW-ID') は、日付 2006-10-19 を返します。 曜日番号を省略した場合、1（月曜日）と想定されます。

  • 年と通年の日付番号。例えば、 to_date('2006-291', 'IYYY-IDDD') のは、同様 2006-10-19 を返します。

    ISO 8601週番号とグレゴリオ暦日のフィールドを混在して使用して日付を構築する試みは無意味なことで、エラーの原因になります。 ISO 8601週番号年の文脈によると、 "月" 、あるいは "月中日付番号" は意味を持ちません。 グレゴリオ暦の年の文脈では、ISO週番号は意味を持ちません。

    注意

    to_date はグレゴリオとISO週番号日のフィールドの混在を拒否しますが、 to_char はそうではありません。 YYYY-MM-DD (IYYY-IDDD) のような出力書式指定が有用な場合があるからです。 しかし、 IYYY-MM-DD のような書き方は避けてください。年の初めの近くで驚くべき結果になるでしょう。 (より詳細な情報は 項9.9.1 を参照してください。)

  • 文字列型から timestamp 型への変換に際し、ミリ秒 MS またはマイクロ秒 US の値は小数点の位置の後の秒の桁として使用されます。 例えば、 to_timestamp('12:3', 'SS:MS') は3ミリ秒ではなく300ミリ秒です。なぜなら変換においてこれは12 + 0.3と計算されるからです。 ということは、 SS:MS 書式に対して入力値である 12:3 、 12:30 、および 12:300 は同じミリ秒数を指定します。 3ミリ秒数が必要な場合には 12:003 のようにしなければなりません。この時、変換において12 + 0.003 = 12.003秒と計算します。

    もう少し複雑な例を挙げます。 to_timestamp('15:12:02.020.001230','HH:MI:SS.MS.US') は15時間12分と2秒+20ミリ秒+1230マイクロ秒 = 2.021230秒です。

  • to_char(..., 'ID') の曜日番号付けは extract(isodow from ...) 関数に一致しますが、 to_char(..., 'D') の曜日番号付けは extract(dow from ...) の曜日番号付けに一致しません。

  • to_char(interval) 関数は、 HH と HH12 により、すなわち0時と36時を 12 とするような、12時間表示の出力をします。一方 HH24 はインターバル間で23を超えることが可能な24時間表示の出力をします。

    表9-24 に、数値型の値の書式設定に使用可能なテンプレートパターンを示します。

    表 9-24. 数値書式用のテンプレートパターン

    パターン	説明
    9	指定された桁数での値
    0	前にゼロが付いた値
    . （ピリオド）	小数点
    , (コンマ)	千単位で区切る符号
    PR	負の値の角括弧表示
    S	（ロケール使用の）符号付き値
    L	（ロケール使用の）通貨記号
    D	（ロケール使用の）小数点
    G	（ロケール使用の）グループ区切り文字
    MI	（数値 < 0であれば）指定位置にマイナス記号
    PL	（数値 > 0であれば）指定位置にプラス記号
    SG	指定された位置にプラス/マイナス記号
    RN	（1〜3999の入力値による）ローマ数字
    TH または th	序数接尾辞
    V	n 桁シフト（注意事項を参照）
    EEEE	科学技術表記法用の指数

    数値型書式の使用上の注意事項は次のとおりです。

    • SG 、 PL 、または MI で整形された符号は、数値と関連付けられません。 例えば、 to_char(-12, 'MI9999') は '  -12' となる一方、 to_char(-12, 'S9999') は '  -12' となります。 Oracleの実装では 9 の前の MI が置かれてはならず、 9 の後に MI が置かれることを要求しています。

    • 9 は 9 が並んでいる数と同じ桁数の値を出力します。 桁が使用可能でない場合、スペースを出力します。

    • TH はゼロ未満の値と小数は変換しません

    • PL 、 SG 、および TH は PostgreSQL の拡張です。

    • V は入力値を実質的に 10^ n 乗します。 ここで n は V に続く桁数です。 to_char 関数は小数点と V との混在をサポートしません（例えば、 99.9V99 は許可されません）。

    • EEEE (科学技術表記)は、他の書式パターンや桁と小数点のパターンを除く修飾子との組み合わせで使うことはできず、また必ず書式文字列の最後に位置しなければなりません(例えば、 9.99EEEE は正しい表記となります)。