9.4.1. format

9.4.1. format

9.4.1. format

The function format produces output formatted according to a format string, in a style similar to the C function sprintf.

函數format產生的輸出根據格式字符串格式化，格式類似於C函數sprintf。

 

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

 

formatstr is a format string that specifies how the result should be formatted. Text in the format string is copied directly to the result, except where format specifiers are used. Format specifiers act as placeholders in the string, defining how subsequent function arguments should be formatted and inserted into the result. Each formatarg argument is converted to text according to the usual output rules for its data type, and then formatted and inserted into the result string according to the format specifier(s).

formatstr是一個格式字符串，用於指定結果的格式。 格式字符串中的文本直接複製到結果中，除非使用了格式說明符。 格式說明符充當字符串中的佔位符，定義應如何格式化後續函數參數並將其插入結果中。 每個formatarg參數根據其數據類型的常規輸出規則轉換爲文本，然後根據格式說明符進行格式化並插入到結果字符串中。

 

Format specifiers are introduced by a % character and have the form

格式說明符由％字符引入，格式爲：

 

%[position][flags][width]type

 

where the component fields are:

組成字段解釋：

 

position (optional)

position（可選）

A string of the form n$ where n is the index of the argument to print. Index 1 means the first argument after formatstr. If the position is omitted, the default is to use the next argument in sequence.

n$形式的字符串，其中n是要打印的參數的索引。索引1表示formatstr之後的第一個參數。如果省略位置，則默認爲依次使用下一個參數。

 

flags (optional)

flags（可選）

Additional options controlling how the format specifier's output is formatted. Currently the only supported flag is a minus sign (-) which will cause the format specifier's output to be left-justified. This has no effect unless the width field is also specified.

其他選項，用於控制格式說明符輸出的格式。當前唯一支持的標誌是減號（-），這 使得格式說明符的輸出左對齊。除非也指定width字段，否則無效。

 

width (optional)

width（可選）

Specifies the minimum number of characters to use to display the format specifier's output. The output is padded on the left or right (depending on the - flag) with spaces as needed to fill the width. A too-small width does not cause truncation of the output, but is simply ignored. The width may be specified using any of the following: a positive integer; an asterisk (*) to use the next function argument as the width; or a string of the form *n$ to use the nth function argument as the width.

指定用於顯示格式說明符輸出的最小字符數。根據需要，在左側或右側（取決於-標誌）填充輸出，以填充寬度。太小的寬度不會導致輸出被截斷，而只會被忽略。可以使用以下任意一種方式指定寬度：正整數；星號（*）以用於指定將下一個函數參數用作寬度；或*n$形式的字符串，以將第n個函數參數用作寬度。

 

If the width comes from a function argument, that argument is consumed before the argument that is used for the format specifier's value. If the width argument is negative, the result is left aligned (as if the - flag had been specified) within a field of length abs(width).

如果寬度來自函數的參數，則該參數將在用於格式說明符值的參數之前使用。如果width參數爲負，則結果在abs（width）長度的字段內保持對齊（就像已指定-標誌）。

 

type (required)

type（必填）

The type of format conversion to use to produce the format specifier's output. The following types are supported:

用於產生格式說明符輸出的格式轉換類型。 支持以下類型：

• s formats the argument value as a simple string. A null value is treated as an empty string.

• s：將參數值格式化爲簡單字符串。 空值將被視爲空字符串。

• I treats the argument value as an SQL identifier, double-quoting it if necessary. It is an error for the value to be null (equivalent to quote_ident).

•I： 將參數值視爲SQL標識符，必要時將其使用雙引號引起來。 該值爲null（等效於quote_ident）是錯誤的。

• L quotes the argument value as an SQL literal. A null value is displayed as the string NULL,without quotes (equivalent to quote_nullable).

•L： 以SQL文字形式引用參數值。 空值顯示爲字符串NULL，不帶引號（等效於quote_nullable）。

 

In addition to the format specifiers described above, the special sequence %% may be used to output a literal % character.

除上述格式說明符外，特殊序列%%可用於輸出文字％字符。

 

Here are some examples of the basic format conversions:

以下是一些基本格式轉換的示例：

 

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', 'C:\Program Files');

Result: INSERT INTO locations VALUES('C:\Program Files')

 

Here are examples using width fields and the - 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 |

 

These examples show use of position fields:

以下是使用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|

 

Unlike the standard C function sprintf, PostgreSQL's format function allows format specifiers with and without position fields to be mixed in the same format string. A format specifier without a position field always uses the next argument after the last argument consumed. In addition, the format function does not require all function arguments to be used in the format string. For example:

與標準C函數sprintf不同，PostgreSQL的format函數允許帶有和不帶有位置字段的格式說明符混合在同一格式字符串中。 沒有位置字段的格式說明符始終使用最後一個參數之後的下一個參數。 另外，format函數不需要在格式字符串中使用所有函數參數。 例如：

 

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

Result: Testing three, two, three

 

The %I and %L format specifiers are particularly useful for safely constructing dynamic SQL statements.See Example 43.1.

％I和％L格式說明符對於安全構造動態SQL語句特別有用。請參見示例43.1。