著者: 2000-01-24、Karel Zak (<zakkr@zf.jcu.cz>) によって書かれました。
PostgreSQL のフォーマッティング関数は多彩なデータ型 (日付/時刻データ型、整数データ型、浮動小数点数データ型、数値データ型)をフォーマットされた文字列変換したり、フォーマットされた文字列を特定のデータ型に変換する強力なツールの一式を提供しています。これら関数は共通の呼び出し規約を踏襲しています。最初の引数はフォーマットされる値で二番目の引数は入力フォーマットまたは出力フォーマットを定義するテンプレートです。
Table 4-11. フォーマッティング関数
| 関数 | 返り値 | 説明 | 例 |
|---|---|---|---|
| to_char(timestamp, text) | text | timestamp 型を文字列型に変換 | to_char(timestamp 'now','HH12:MI:SS') |
| to_char(interval, text) | text | 時間間隔型を文字列型に変換 | to_char(interval '15h 2m 12s','HH24:MI:SS') |
| to_char(int, text) | text | int4/int8 型を文字列型に変換 | to_char(125, '999') |
| to_char(double precision, text) | text | 実数、倍精度数を文字列型に変換 | to_char(125.8, '999D9') |
| to_char(numeric, text) | text | 数値型を文字列型に変換 | to_char(numeric '-125.8', '999D99S') |
| to_date(text, text) | date | 文字列型を日付型に変換 | to_date('05 Dec 2000', 'DD Mon YYYY') |
| to_timestamp(text, text) | timestamp | 文字列型を timestamp 型に変換 | to_timestamp('05 Dec 2000', 'DD Mon YYYY') |
| to_number(text, text) | numeric | 文字列型を数値型に変換 | to_number('12,454.8-', '99G999D9S') |
出力テンプレート文字列には、それが認識され、フォーマットされる値から適切にフォーマットされたデータで置き換えられるパターンがあります。テンプレートパターンですべてのテキストは単にそのままコピーされます。同様に、入力テンプレート文字列では、テンプレートパターンは入力されたデータ文字列の捜し出される部分と、そこで見つけ出される値を特定します。
Table 4-12. 日付/時刻型のテンプレートパターン
| パターン | 説明 |
|---|---|
| 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 桁 |
| 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 | 1 年通算の日にち (001-366) |
| DD | 1 月通算の日にち (01-31) |
| D | 1 週通算の日にち (1-7： 日曜日=1) |
| W | 月中の週番号 (1-5) でその月の初日がある週が第 1 週 |
| WW | 年間を通じた週番号 (1-53) で元旦のある週が第 1 週 |
| IW | ISO 週番号 (新年の最初の木曜日がある週が第 1 週) |
| CC | 世紀 (2 桁) |
| J | ユリウス日 (紀元前 4712 年 1 月 1 日からの通算経過日) |
| Q | 四半期 |
| RM | ローマ数字による月 (I-XII： I=月曜日) - 大文字 |
| rm | ローマ数字による月 (I-XII： I=月曜日) - 小文字 |
| TZ | 時間帯名称 - 大文字 |
| tz | 時間帯名称 - 小文字 |
どのようなテンプレートパターンに対しても、その振舞いを変更するためにある種の修飾子を適用することができます。例えば、"FMMonth" は "FM" の付いた "Month" パターンです。
Table 4-13. 日付/時刻変換のテンプレートパターン修飾子
| 修飾子 | 説明 | 例 |
|---|---|---|
| FM 接頭辞 | 字詰めモード (空白およびゼロのパディングを無効) | FMMonth |
| TH 接尾辞 | 大文字の序数を追加 | DDTH |
| th 接尾辞 | 小文字の序数を追加 | DDth |
| FX 接頭辞 | 固定フォーマットのグローバルオプション (下記参照) | FX Month DD Day |
| SP 接尾辞 | スペルモード (未実装) | DDSP |
使用上の注意事項：
FM はパターンの出力を固定長にするため、先頭にはゼロ、後尾には空白を追加してしまう機能を無効にします。
FX オプションが使用されていない場合には、 to_timestamp と to_date は入力文字列の複数の空白スペースを無視します。 FX は必ずテンプレートの第一項目として指定される必要があります。例えば、 to_timestamp にはたった一つの空白スペースがあることになっているので、 to_timestamp('2000 JUN','YYYY MON') が正しく to_timestamp('2000 JUN','FXYYYY MON') はエラーを返します。
文字列定数の中に逆スラッシュが必要な場合には、例えば '\\HH\\MI\\SS' のように逆スラッシュを重複させます。PostgreSQL ではいかなる文字列定数に対しても共通です。
to_char テンプレートで通常のテキストを使うことができ、そのまま出力されます。たとえパターンキーワードを含んでいるとしても強制的にリテラルテキストとして解釈させるように部分文字列を二重引用符で括ることが可能です。例えば、'"Hello Year: "YYYY' において YYYY は年データで置き換えられます。但し単一の Y は置き換わりません。
出力に二重引用符を付けたい場合、'\\"YYYY Month\\"' のようにその前に逆スラッシュを付けなければなりません。
文字列を timestamp 型もしくは date 型にする YYYY 変換は、年の値として 4 桁以上の数字を使用していると制限が加えられます。このような場合、数字以外の文字または YYYY の後にテンプレートを使わなければなりません。そうしないと年は常に 4 桁と解釈されます。例えば (20000 年として)、 to_date('200001131', 'YYYYMMDD') は 4 桁の年と解釈されるので、 to_date('20000-1131', 'YYYY-MMDD') または to_date('20000Nov31', 'YYYYMonDD') のように数字でない区切り符号の使用をお勧めします。
文字列型から 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 秒です。
Table 4-14. 数値変換のテンプレートパターン
| パターン | 説明 |
|---|---|
| 9 | 指定された桁数での値 |
| 0 | 前にゼロが付いた値 |
| . (終止符) | 小数点 |
| , (コンマ) | グループ (3 桁) 区切り符号 |
| 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 は許可されません。)
Table 4-15. to_char の例
| 入力 | 出力 |
|---|---|
| to_char(now(),'Day, DD HH12:MI:SS') | 'Tuesday , 06 05:39:18' |
| to_char(now(),'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,'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,'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' |