选择 打开 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。

受支持版本: 当前版本 (18) / 17 / 16 / 15 / 14
测试与开发版本: 19 / devel
不受支持的版本: 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0
历史版本PostgreSQL 9.1 已于 2016 年 10 月结束社区维护,本页译文保留供仍在使用旧版本的读者参考。新系统请看当前版本

9.8. 数据类型格式化函数 #

PostgreSQL格式化函数提供一套强大的工具用于把各种数据类型 (日期/时间、整数、浮点数、数值) 转换成格式化的字符串以及反过来从格式化的字符串转换成 指定的数据类型。表 9.21列出了这些函数。这些函数都遵循一个公共的调用规范: 第一个参数是待格式化的值,而第二个是一个定义输出或输入格式的模板。

还有一个单参数的to_timestamp函数;它接受一个 double precision参数,并把 Unix 纪元(自 1970-01-01 00:00:00+00 起的秒数) 转换为timestamp with time zone。 (Integer Unix 纪元会被隐式转换为double precision。)

表 9.21. 格式化函数

函数 返回类型 描述 示例
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 将 real/double precision 转换为字符串 to_char(125.8::real, '999D9')
to_char(numeric, text) text 将 numeric 转换为字符串 to_char(-125.8, '999D99S')
to_date(text, text) date 将字符串转换为日期 to_date('05 Dec 2000', 'DD Mon YYYY')
to_number(text, text) numeric 将字符串转换为 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(1284352323)

在一个to_char输出模板串中,一些特定的模式可以被识别并且被替换成基于给定值的被恰当地格式化的数据。任何不属于模板模式的文本都简单地照字面拷贝。同样,在一个输入 模板串里(对其他函数),模板模式标识由输入数据串提供的值。

表 9.22展示了可以用于格式化日期和时间值的模板模式。

表 9.22. 用于日期/时间格式化的模板模式

模式 描述
HH 一天中的小时(01-12)
HH12 一天中的小时(01-12)
HH24 一天中的小时(00-23)
MI 分钟(00-59)
SS 秒(00-59)
MS 毫秒(000-999)
US 微秒(000000-999999)
SSSS 自午夜起的秒数(0-86399)
AM, am, PMpm 上午/下午标记(不带句点)
A.M., a.m., P.M.p.m. 上午/下午标记(带句点)
Y,YYY 带逗号的年(4 位或者更多位)
YYYY 年(4 位或者更多位)
YYY 年的最后 3 位数字
YY 年的最后 2 位数字
Y 年的最后 1 位数字
IYYY ISO 8601 周编号方式的年(4 位或更多位)
IYY ISO 8601 周编号方式的年的最后 3 位数字
IY ISO 8601 周编号方式的年的最后 2 位数字
I ISO 8601 周编号方式的年的最后 1 位数字
BC, bc, ADad 纪元指示器(不带句号)
B.C., b.c., A.D.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 8601 周编号年中的第几天(001-371;一年的第 1 天是第一个 ISO 周的星期一)
DD 月内日序数(01-31)
D 星期几,周日 (1) 到周六 (7)
ID ISO 8601 星期几,周一 (1) 到周日 (7)
W 月内周序数(1-5)(第一周从该月第一天开始)
WW 一年中的第几周(1-53)(第一周从该年第一天开始)
IW ISO 8601 周编号年中的第几周(01-53;该年的第一个星期四位于第 1 周)
CC 世纪(2 位数)(21 世纪开始于 2001-01-01)
J 儒略日(从公元前 4714 年 11 月 24 日 UTC 午夜开始的整数日数)
Q 季度(被to_dateto_timestamp忽略)
RM 以大写罗马数字表示的月份(I-XII;I=一月)
rm 以小写罗马数字表示的月份(i-xii;i=一月)
TZ 大写时区名称
tz 小写时区名称

修饰符可以被应用于模板模式来修改它们的行为。例如,FMMonth就是带着FM修饰符的Month模式。表 9.23展示了可用于日期/时间格式化的修饰符模式。

表 9.23. 用于日期/时间格式化的模板模式修饰符

修饰符 描述 示例
FM 前缀 填充模式(抑制前导零和填充的空格) FMMonth
TH 后缀 大写形式的序数后缀 DDTH,例如, 12TH
th 后缀 小写形式的序数后缀 DDth,例如, 12th
FX 前缀 固定格式全局选项(见使用须知) FX Month DD Day
TM 前缀 翻译模式(根据 lc_time 输出本地化的星期名和月份名) TMMonth
SP 后缀 拼写模式(未实现) DDSP

日期/时间格式化的使用注意事项:

  • FM抑制了在模式输出中添加前导零和尾随空格的行为,这些前导零和尾随空格 本来会被添加以使输出成为固定宽度。在PostgreSQL中, FM仅修改下一个格式说明,而在Oracle中FM影响所有后续 格式说明,并且重复的FM修饰符切换填充模式的开启和关闭。

  • TM不包含尾随空格。

  • to_timestampto_date 会跳过输入字符串中的多个空格,除非使用 FX 选项。例如,to_timestamp('2000    JUN', 'YYYY MON') 可以工作,但 to_timestamp('2000    JUN', 'FXYYYY MON') 会报错,因为 to_timestamp 只接受一个空格。FX 必须指定为模板中的第一项。

  • to_char 模板中允许普通文本,并会按字面输出。可以用双引号括起子串,使其即使包含模式关键字也强制按字面文本解释。例如,在 '"Hello Year "YYYY' 中,YYYY 会被年份数据替换,但 Year 中单独的 Y 不会被替换。在 to_dateto_numberto_timestamp 中,双引号字符串会跳过与该字符串所含字符数相同数量的输入字符,例如 "XX" 跳过两个输入字符。

  • 如果要在输出中包含双引号,必须在它前面加上反斜杠,例如 '\"YYYY Month\"'

  • 在从字符串到timestampdate的转换中, YYYY转换在处理超过4位数字的年份时有限制。您必须在YYYY后使用一些非数字字符或模板, 否则年份总是被解释为4位数字。例如(使用年份20000): to_date('200001131', 'YYYYMMDD')将被解释为4位年份;而应该在年份后使用非数字分隔符,如 to_date('20000-1131', 'YYYY-MMDD')to_date('20000Nov31', 'YYYYMonDD')

  • 在从字符串到timestampdate的转换中, 如果存在YYYYYYYY,YYY字段, 则忽略CC(世纪)字段。如果CCYYY一起使用,则年份按(CC-1)*100+YY计算。 如果指定了世纪但未指定年份,则假定为该世纪的第一年。

  • 可以向to_timestampto_date以下列两种方式之一指定 ISO 8601 周编号日期(与公历日期不同):

    • 年份、周编号和星期几:例如to_date('2006-42-4', 'IYYY-IW-ID')返回日期2006-10-19。如果省略星期几,则假定它为 1(星期一)。

    • 年份和年内日序数:例如to_date('2006-291', 'IYYY-IDDD')也返回2006-10-19

    尝试使用ISO 8601周编号字段和公历日期字段的混合输入日期是荒谬的,并将导致错误。 在ISO 8601周编号年的背景下,月份月内日序数的概念没有意义。 在公历年的背景下,ISO周没有意义。

    小心

    虽然to_date会拒绝混合使用公历和ISO周编号日期字段, 但to_char不会,因为输出格式规范如YYYY-MM-DD (IYYY-IDDD)可能很有用。 但要避免编写类似IYYY-MM-DD的内容;那会在年初附近产生令人惊讶的结果。 (有关更多信息,请参见第 9.9.1 节。)

  • 在从字符串到timestamp的转换中,毫秒(MS)或微秒(US)值被用作小数点后的秒数位。 例如to_timestamp('12:3', 'SS:MS')不是3毫秒,而是300,因为转换将其计为12 + 0.3秒。 这意味着对于格式SS:MS,输入值12:312:3012:300指定相同数量的毫秒。 要获得三毫秒,必须写成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 from ...)函数匹配, 但to_char(..., 'D')的不匹配extract(dow from ...)的星期几编号。

  • to_char(interval) 按照如12小时制时钟上显示的方式格式化HHHH12, 即零小时和36小时都输出为12, 而HH24输出完整的小时值,对于时间间隔它可以超过23。

表 9.24展示了可以用于格式化数值的模板模式。

表 9.24. 用于数值格式化的模板模式

模式 描述
9 数位(非有效位可以被省略)
0 数位(即便是非有效位也不会被省略)
.(句点) 小数点
,(逗号) 分组(千)分隔符
PR 尖括号内的负值
S 紧贴数值的正负号(使用区域设置)
L 货币符号(使用区域设置)
D 小数点(使用区域设置)
G 分组分隔符(使用区域设置)
MI 在指定位置的负号(如果数字 < 0)
PL 在指定位置的正号(如果数字 > 0)
SG 在指定位置的正/负号
RN 罗马数字(输入在 1 和 3999 之间)
THth 序数后缀
V 移动指定位数(参阅注解)
EEEE 科学记数的指数

数值格式化的使用注意事项:

  • 9产生一个位数与9的个数相同的值。如果没有可用的数字,则输出一个空格。

  • 使用SGPLMI格式化的正负号不紧贴数值; 例如,to_char(-12, 'MI9999')会产生'-  12', 但to_char(-12, 'S9999')会产生'  -12'。 (Oracle实现不允许在9之前使用MI,而是要求9MI之前。)

  • TH不会转换小于零的值,也不会转换小数。

  • PLSGTHPostgreSQL 的扩展。

  • V实际上将输入值乘以10^n, 其中n是跟在V后面的数字位数。 to_char不支持与小数点结合使用的V (例如,不允许使用99.9V99)。

  • EEEE(科学计数法)不能与任何其他格式模式或修饰符结合使用,除了数字和小数点模式之外,必须位于格式字符串的末尾(例如,9.99EEEE是一个有效模式)。

某些修饰符可以被应用到任何模板来改变其行为。例如,FM9999是带有FM修饰符的9999模式。表 9.25中展示了用于数值格式化的模式修饰符。

表 9.25. 用于数值格式化的模板模式修饰符

修饰符 描述 示例
FM 前缀 填充模式(抑制前导零和填充的空白) FM9999
TH 后缀 大写序数后缀 999TH
th 后缀 小写序数后缀 999th

表 9.26展示了一些使用to_char函数的示例。

表 9.26. to_char示例

表达式 结果
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'
to_char(0.0004859, '9.99EEEE') ' 4.86e-04'

提交更正

译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。