PostgreSQLの書式設定関数は多彩なデータ型（日付/時刻データ型、整数データ型、浮動小数点数データ型、数値データ型）を整形された文字列に変換したり、整形された文字列を特定のデータ型に変換する強力なツールの一式を提供しています。表9-20にこれらを列挙しています。これら関数は共通の呼び出し規約を踏襲しています。最初の引数は整形される値で2番目の引数は入力書式または出力書式を定義するテンプレートです。
to_timestamp関数はUnix時刻からtimestamp with time zoneに変換するただ一つのdouble precision引数を取ることもできます。（int Unix時刻は暗黙的にdouble precisionにキャストされます。）
表 9-20. 書式設定関数
| 関数 | 戻り値 | 説明 | 例 |
|---|---|---|---|
to_char(timestamp, text) | text | タイムスタンプを文字列に変換 | to_char(current_timestamp, 'HH12:MI:SS') |
to_char(interval, text) | text | 時間間隔を文字列に変換 | to_char(interval '15h 2m 12s', 'HH24:MI:SS') |
to_char(int, text) | text | 整数を文字列に変換 | to_char(125, '999') |
to_char(double precision,
text) | text | 実数、倍精度数を文字列に変換 | to_char(125.8::real, '999D9') |
to_char(numeric, text) | text | 数値を文字列に変換 | to_char(-125.8, '999D99S') |
to_date(text, text) | date | 文字列を日付に変換 | to_date('05 Dec 2000', 'DD Mon YYYY') |
to_number(text, text) | numeric | 文字列を数値に変換します | to_number('12,454.8-', '99G999D9S') |
to_timestamp(text, text) | timestamp with time zone | 文字列をタイムスタンプに変換 | to_timestamp('05 Dec 2000', 'DD Mon YYYY') |
to_timestamp(double precision) | timestamp with time zone | UNIX時刻をタイムスタンプに変換 | to_timestamp(200120400) |
（to_char用）出力テンプレート文字列には、それが認識され、整形される値から適切に整形されたデータで置き換えられるパターンがあります。
テンプレートパターンではない全てのテキストは単にそのままコピーされます。
同様に、（to_char以外用）入力テンプレート文字列では、テンプレートパターンは入力されたデータ文字列の探し出される部分と、そこで見つけ出される値を特定します。
表9-21に、日付/時刻型の値の書式に使用可能なテンプレートパターンを示します。
表 9-21. 日付/時刻型の書式テンプレートパターン
| パターン | 説明 |
|---|---|
| HH | 時（01〜12） |
| HH12 | 時（01〜12） |
| HH24 | 時（00〜23） |
| MI | 分（00〜59） |
| SS | 秒（00〜59） |
| MS | ミリ秒（000〜999） |
| US | マイクロ秒（000000〜999999） |
| SSSS | 深夜0時からの秒数（0〜86399） |
| AM、A.M.、 PM、またはP.M. | 午前/午後の指定（大文字） |
| am、a.m.、 pm、またはp.m. | 午前/午後の指定（小文字） |
| Y,YYY | 句読点（コンマ）付き年（4桁以上） |
| YYYY | 年（4桁以上） |
| YYY | 年の下3桁 |
| YY | 年の下2桁 |
| Y | 年の下1桁< |
| IYYY | ISO年（4以上の桁） |
| IYY | ISO年の下3桁 |
| IY | ISO年の下2桁 |
| I | ISO年の下1桁 |
| BC、B.C.、 AD、またはA.D. | 紀元前後の指定（大文字） |
| bc、b.c.、 ad、またはa.d. | 紀元前後の指定（小文字） |
| MONTH | 大文字での完全な月名（9文字になるように空白でパッド） |
| Month | 大文字小文字混在した完全な月名（9文字になるように空白でパッド） |
| month | 小文字での完全な月名（9文字になるように空白でパッド） |
| MON | 大文字での短縮形の月名（英語では3文字、現地語化された場合は可変長） |
| Mon | 大文字小文字混在した短縮形の月名（英語では3文字。現地語化された場合は可変長） |
| mon | 小文字での短縮形の月名（英語では3文字。現地語化された場合は可変長） |
| MM | 月番号（01〜12） |
| DAY | 大文字での完全な曜日名（9文字になるように空白でパッド） |
| Day | 大文字小文字混在した完全な曜日名（9文字になるように空白でパッド） |
| day | 小文字での完全な曜日名（9文字になるように空白でパッド） |
| DY | 短縮形の大文字での短縮形の曜日名（英語では3文字。現地語化された場合は可変長） |
| Dy | 短縮形の大文字小文字混在した短縮形の曜日名（英語では3文字。現地語化された場合は可変長） |
| dy | 小文字での短縮形の曜日名（英語では3文字。現地語化された場合は可変長） |
| DDD | 通年の日にち番号（001〜366） |
| IDDD | ISO通年の日にち番号（001-371：通年 第１日は最初のISO周の月曜日） |
| DD | ひと月通算の日にち番号（01〜31） |
| D | 1週通算の曜日番号、日曜日（1）から土曜日（7）まで |
| ID | ISO1週通算の曜日番号、月曜日（1）から日曜日（7）まで |
| W | 月中の週番号（1〜5）（その月の初日がある週が第1週） |
| WW | 年間を通じた週番号（1〜53）（元旦のある週が第1週） |
| IW | 年間を通じたISO週番号（1 - 53：新年の最初の木曜日がある週が第1週） |
| CC | 世紀（2桁。21世紀は2001-01-01から開始） |
| J | ユリウス日（紀元前4714年11月24日午前零時からの通算経過日） |
| Q | クウォータ（四半期） |
| RM | ローマ数字による月（I〜XII：I=1月）（大文字） |
| rm | ローマ数字による月（i〜xii：i=1月）（小文字） |
| TZ | 時間帯名（大文字） |
| tz | 時間帯名（小文字） |
ある種の修飾子はどのようなテンプレートパターンに対しても、その振舞いを変更するために適用することができます。例えば、FMMonthはFM修飾子の付いたMonthパターンです。表9-22に、日付/時刻書式の修飾子パターンを示します。
表 9-22. 日付/時刻書式用のテンプレートパターン修飾子
| 修飾子 | 説明 | 例 |
|---|---|---|
| FM接頭辞 | 字詰めモード（空白およびゼロのパディングを無効） | FMMonth |
| TH接尾辞 | 大文字の序数を追加 | DDTH |
| th suffix | 小文字の序数を追加 | DDth |
| FX prefix | 固定書式のグローバルオプション（使用上の注意事項を参照） | FX Month DD Day |
| TM接頭辞 | 翻訳モード（lc_messagesに基付き、翻訳された日付、付を表示します。） | TMMonth |
| SP接尾辞 | スペルモード（未実装） | DDSP |
日付/時刻型書式の使用上の注意事項は次のとおりです。
FMはパターンの出力を固定長にするため、先頭にはゼロ、末尾には空白を追加してしまう機能を無効にします。
TMには末尾の空白は含まれません。
FXオプションがテンプレートが使用されていない場合には、to_timestampとto_dateは入力文字列の複数の空白スペースを無視します。FXはテンプレートの第1項目として指定される必要があります。例えば、to_timestampにはたった1つのスペースがあることになっているので、to_timestamp('2000 JUN', 'YYYY MON')が正しく、to_timestamp('2000 JUN','FXYYYY MON')はエラーを返します。
to_charテンプレートでは、通常のテキストが許され、そのまま出力されます。部分文字列を二重引用符で括ることで、部分文字列にパターン用のキーワードがあったとしても、強制的にリテラルテキストとして解釈させることができます。例えば、'"Hello Year "YYYY'ではYYYYは年データに置換されてしまいますが、Year内のYは置換されません。
出力に二重引用符を付けたい場合、E'\\"YYYY Month\\"'のようにその前にバックスラッシュを付けなければなりません（エスケープ文字列構文を使用する場合、バックスラッシュは既に特別な意味を持つため、2つのバックスラッシュが必要です）。
文字列を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と共に使用されると、年は(CC-1)*100+YYのように計算されます。
ISO週番号と週の曜日番号（グレゴリオ暦の日付とは異なって）は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週番号とグレゴリアン暦日のフィールドを混在して使用して日付を構築する試みは無意味なことで、予想の付かない結果をもたらします。ISO年の文脈によると、「月」あるいは「月中日付番号」は意味を持ちません。グレゴリオ暦の年の文脈では、ISO週番号は意味を持ちません。グレゴリアンとISOの日付の仕様を分離して使用するよう注意してください。
文字列型から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', ...)関数にマッチしますが、to_char(..., 'D')の曜日番号付けはextract('dow', ...)の曜日番号付けにマッチしません。
to_char(interval)関数は一日の時間をHHと
HH12のようにフォーマットします。一方HH24は一日を越える時間を >24 のように出力します。
表9-23に、数値型の値の書式設定に使用可能なテンプレートパターンを示します。
表 9-23. 数値書式用のテンプレートパターン
| パターン | 説明 |
|---|---|
| 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, 'S9999')は' -12'となる一方、to_char(-12, 'MI9999')は'- 12'となります。 Oracleの実装では9に先行してMIが置かれてはならず、9の後にMIが置かれることを要求しています。
9は9が並んでいる数と同じ桁数の値を出力します。 桁が使用可能でない場合、スペースを出力します。
THはゼロ未満の値と小数は変換しません
PL、SG、およびTHはPostgreSQLの拡張です。
Vは入力値を有効に10^n乗します。
ここでnはVに続く桁数です。
to_char関数は小数点を含む数値とVとの混在をサポートしません（例えば、99.9V99 は許可されません）。
表9-24に、to_char関数を使用した例をいくつか示します。
表 9-24. to_char Examples
| Expression | Result |
|---|---|
| to_char(current_timestamp, 'Day, DD HH12:MI:SS') | 'Tuesday , 06 05:39:18' |
| to_char(current_timestamp, 'FMDay, FMDD HH12:MI:SS') | 'Tuesday, 6 05:39:18' |
| to_char(-0.1, '99.99') | ' -.10' |
| to_char(-0.1, 'FM9.99') | '-.1' |
| to_char(0.1, '0.9') | ' 0.1' |
| to_char(12, '9990999.9') | ' 0012.0' |
| to_char(12, 'FM9990999.9') | '0012.' |
| to_char(485, '999') | ' 485' |
| to_char(-485, '999') | '-485' |
| to_char(485, '9 9 9') | ' 4 8 5' |
| to_char(1485, '9,999') | ' 1,485' |
| to_char(1485, '9G999') | ' 1 485' |
| to_char(148.5, '999.999') | ' 148.500' |
| to_char(148.5, 'FM999.999') | '148.5' |
| to_char(148.5, 'FM999.990') | '148.500' |
| to_char(148.5, '999D999') | ' 148,500' |
| to_char(3148.5, '9G999D999') | ' 3 148,500' |
| to_char(-485, '999S') | '485-' |
| to_char(-485, '999MI') | '485-' |
| to_char(485, '999MI') | '485 ' |
| to_char(485, 'FM999MI') | '485' |
| to_char(485, 'PL999') | '+485' |
| to_char(485, 'SG999') | '+485' |
| to_char(-485, 'SG999') | '-485' |
| to_char(-485, '9SG99') | '4-85' |
| to_char(-485, '999PR') | '<485>' |
| to_char(485, 'L999') | 'DM 485 |
| to_char(485, 'RN') | ' CDLXXXV' |
| to_char(485, 'FMRN') | 'CDLXXXV' |
| to_char(5.2, 'FMRN') | 'V' |
| to_char(482, '999th') | ' 482nd' |
| to_char(485, '"Good number:"999') | 'Good number: 485' |
| to_char(485.8, '"Pre:"999" Post:" .999') | 'Pre: 485 Post: .800' |
| to_char(12, '99V999') | ' 12000' |
| to_char(12.4, '99V999') | ' 12400' |
| to_char(12.45, '99V9') | ' 125' |