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。