9.4. 文字列関数と演算子

9.4.1. format

関数formatは、C関数のsprintf同様の形式で、format文字列に従ってフォーマットされた出力を生成します。

format(formatstr text [, formatarg "any" [, ...] ])

formatstrは結果がどのようにフォーマットされるかを指定するformat文字列です。 format specifiersが使用されている以外、format文字列のテキストは結果に直接コピーされます。 引き続く関数の引数がどのようにフォーマットされなければならないか、そして結果に挿入されるべきかを定義して、format指示子は文字列の中で代替物のように振舞います。 それぞれのformatarg引数はそのデータ型に対する通常の出力規定に従ってテキストに変換され、その後format指示子に従いフォーマットされ、結果文字列に挿入されます。

format指示子は%文字で導入され、以下の形式です。

%[position][flags][width]type

ここで要素フィールドとは以下になっています。

上記で説明したformat指示子に加え、特別の並びの%%がリテラル%文字を出力するために使用することもできます。

基本的なformat変換の例を幾つか下記に紹介します。

SELECT format('Hello %s', 'World');
Result: Hello World

SELECT format('Testing %s, %s, %s, %%', 'one', 'two', 'three');
Result: Testing one, two, three, %

SELECT format('INSERT INTO %I VALUES(%L)', 'Foo bar', E'O\'Reilly');
Result: INSERT INTO "Foo bar" VALUES('O''Reilly')

SELECT format('INSERT INTO %I VALUES(%L)', 'locations', E'C:\\Program Files');
Result: INSERT INTO locations VALUES(E'C:\\Program Files')

widthフィールドと- flagを使用した例は以下のようです。

SELECT format('|%10s|', 'foo');
Result: |       foo|

SELECT format('|%-10s|', 'foo');
Result: |foo       |

SELECT format('|%*s|', 10, 'foo');
Result: |       foo|

SELECT format('|%*s|', -10, 'foo');
Result: |foo       |

SELECT format('|%-*s|', 10, 'foo');
Result: |foo       |

SELECT format('|%-*s|', -10, 'foo');
Result: |foo       |

以下の例はpositionフィールドの使い方を示しています。

SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three');
Result: Testing three, two, one

SELECT format('|%*2$s|', 'foo', 10, 'bar');
Result: |       bar|

SELECT format('|%1$*2$s|', 'foo', 10, 'bar');
Result: |       foo|

標準C関数sprintfとは違って、PostgreSQLの format関数はformat指示子に対し、同一のformat文字列の中でpositionフィールドがあっても無くっても問題としません。 positionフィールドが無いformat指示子は常に最終の引数が消費された後に次の引数を使用します。 さらに、format関数はformat文字列で使用されるべき全ての関数引数を要求しません。 例を示します。

SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
Result: Testing three, two, three

%I および %Lのformat指示子は特に動的SQL命令を構築する場合に便利です。 例40-1を参照してください。