TO_CHAR 函数

返回的字符串表示第一个参数指定的数据值，使用第二个参数在 format_string 中定义的格式掩码，可包括特殊的格式符号和文字字符。

此函数的第一个参数必须为 DATE、DATETIME 或内建的数值数据类型，或可转换为这些数据类型之一的字符串。如果初始的 DATE、DATETIME 或数值参数的值为 NULL，则该函数返回 NULL 值。
此函数的第二个参数是指定格式掩码的字符串。哪些特殊的字符适合于格式掩码，主要依赖于 TO_CHAR 函数的第一个参数是表示时间点还是数值。

格式化 DATE 和 DATETIME 表达式

format_string 参数不需要隐含与 TO_CHAR 函数的第一个参数中的值相同的时间单位。当 format_string 中隐含的精度与第一个参数中的 DATETIME 限定符不同时，TO_CHAR 函数扩展 DATETIME 值，就如同它已调用了 EXTEND 函数。

在下列示例中，用户想要将 tab1 表的 begin_date 列转换为字符串。begin_date 列定义为 DATETIME YEAR TO SECOND 数据类型。用户使用带有 TO_CHAR 函数的 SELECT 语句来执行此转换：

SELECT TO_CHAR(begin_date, '%A %B %d, %Y %R') FROM tab1;

此示例的 format_string 中的符号有下列含义。

符号: 含义
%A: 完整的星期名称，如在语言环境中定义的那样
%B: 完整的月份名称，如在语言环境中定义的那样
%d: 以整数（01 至 31）表示的该月的日期。在单一位的值之前添零（0）。
%Y: 4 位十进制数值的年份
%R: 24 小时表示法的时间（等同于 %H:%M 格式，如下面定义的那样）。

请注意，在上例中紧跟在 %d 格式规范之后的逗号（,）是文字字符，而不是 TO_CHAR 函数的参数的分隔符。第二个参数是引号括起的字符串 '%A %B %d, %Y %R'，定义 TO_CHAR 返回的值中表示第一个参数的格式掩码。

将此 format_string 应用于 begin_date 列值，返回此结果：

Wednesday July 25, 2013 18:45

下例中的查询调用 TO_CHAR 来将同一格式字符串应用于 ADD_MONTHS 表达式，并展示该查询的结果：

SELECT ship_date, TO_CHAR(ADD_MONTHS(ship_date, 1), '%A %B %d, %Y')
          AS survey_date FROM orders;
          
          
          ship_date    03/12/2013
          survey_date  Thursday April 12, 2013

在以上的查询输出中，

根据 DB_DATE 环境变量设置格式化 ship_date 值，
并根据 TO_CHAR 函数的 '%A %B %d, %Y %R' 格式字符串参数格式化 survey_date 值。

对于 DATE 或 DATETIME 值，在 TO_CHAR 函数的 format_string 参数中附加的有效字符包括下列。

符号: 含义
%a: 缩写的星期名称，如在语言环境中定义的那样
%b: 缩写的月份名称，如在语言环境中定义的那样
%C: 表示为整数（00 至 99）的世纪数值（年份除以 100 并截断为整数）
%D: 与 %m/%d/%y 格式相同
%e: 数值表示的该月的日期（1 至 31）。单一位值之前添加一空格。
%Fn: 秒的小数部分的值，由无符号的整数 n 指定精度。n 的缺省值为 2；n 的范围为 0 ≤ n ≤ 5。此值覆盖在 % 与 F 字符之间指定的任何宽度或精度。
%h: 与 %b 格式相同：缩写的月份名称，如在语言环境中定义的那样
%H: 2 位整数表示的小时（00 至 23）（24 小时时钟）
%I: 2 为整数表示的小时（00 至 11）（12 小时时钟）
%m: 整数表示的月份（01 至 12）。任何单一位值之前添加零（0）。
%M: 2 位整数表示的分钟（00 至 59）
%S: 2 位整数表示的秒（00 至 61）。秒值可达到 61（而不是 59），以允许偶然的跳跃秒或双跳跃秒。
%T: %H:%M:%S 格式的时间
%w: 数值表示的星期（0 至 6）；0 表示等同于星期日的语言环境。
%y: 2 位十进制数值表示的年份。

例如，假设在 2013 年 8 月 23 日，DB-Access 实用程序发出了下列查询：

SELECT TO_CHAR(CURRENT YEAR TO FRACTION(5), "%Y-%m-%d %H:%M:%S.%F")
          FROM sysmaster:sysdual;

在此示例中，格式字符串参数以下列文字字符作为 DATETIME 字段值之间的分隔符指定用户格式：

ASCII 45 ( - ) 连字符分隔年、月和日值
ASCII 32 ( ) 空格分隔开日期与小时
ASCII 58 ( : ) 冒号分隔时、分和秒
ASCII 46 ( . ) 句号分隔秒与秒的小数部分。

这是以指定的 DATETIME 用户格式返回的值：

(expression)   2013-08-23 13:15:53.00

当 DATETIME 或 DATE 表达式是第一个参数时，如果您省略 format_string 参数，则 TO_CHAR 函数使用 DBTIME 或 DBDATE 环境变量的设置作为缺省值，来格式化在第一个参数中表示的值。在非缺省的语言环境中，通过诸如 GL_DATETIME 和 GL_DATE 这样的环境变量指定 DATETIME 和 DATE 值的缺省格式。

重要：对于其精度包括 SECOND 和 FRACTION 数据值的 DATETIME 用户格式，连接那些字段，除非在 %S 与 %F 格式伪指令之间显式地定义分隔符字符。在版本 11.70.xC7 以及更早的 GBase 8s 产品中，在缺省情况下， %F 伪指令在 SECOND 与 FRACTION 字段值之间插入了 ASCII 46 字符（.）。然而，在此产品中，%F 伪指令为隐含缺省的分隔符。

要了解那些可为内建的按时间顺序排列的数据类型指定显示和数据条目格式的 GBase 8s 环境变量之中的优先顺序，请参阅主题 DATE 和 DATETIME 格式规范的优先顺序。

格式化数值的和 MONEY 表达式

TO_CHAR 函数的 format_string 参数支持与 ESQL 函数使用的相同的数值格式掩码，比如 rfmtdec( )、rfmtdouble( ) 和 rfmtlong( )。在 GBase 8s ESQL/C 程序员手册中，是对数值值（当将数值表达式格式化为字符串时）的 GBase 8s 数值格式掩码的详尽描述。以下是数值格式掩码的简短总结描述。

当将数值表达式格式化为字符串时，数值格式掩码指定应用于某数值值的格式。此掩码是下列格式化字符的组合：

符号: 含义
*: 此字符以星号填充本来为空的显示字段中的任何位置
&: 此字符以零填充本来为空的显示字段中的任何位置
#: 此字符将开始的零更改为空格。使用此字符来指定字段向左边的最大扩展。
<: 此字符对显示字段总的数值进行左调整。它将开始的零更改为 NULL 字符串。
,: 此字符表明在值的整数部分按三位一组（从单位位置向左数）分隔的符号。在缺省情况下，此符号为逗号。您可以 DBMONEY 环境变量设置该符号。在格式化了的数值中，仅当该值的整数部分有四位或更多位时才出现此符号。
.: 此字符表明将货币值的整数部分与小数部分分隔的符号。在缺省情况下，此符号为句号。您可以 DBMONEY 环境变量设置该符号。在格式字符串中，您仅可有一个句号。
-: 此字符为文字字符。当 expr1 小于零时，它作为负号出现。当您将一行中的几个负号（-）分组时，单个负号浮动到它可占据的最右边的位置；它不影响数值及其币种符号。
+: 此字符为文字字符。当 expr1 大于或等于零时，它作为正号出现。当您在将一行中的几个正号分组时，单个加号或减号浮动到它可占据的最右边的位置；它不影响数值及其币种符号。
(: 此字符为文字字符。它作为负数值的左边的左圆括号（(）出现。它是替换负数的减号的一对会计圆括号之一。当您对一行中的几个分组时，单个左圆括号浮动到它可占据的最右边的位置；它不影响数值及其币种符号。
): 这是替换负值的减号的一对会计圆括号之一。
$: 此字符显示在数值值前面的币种符号。在缺省的语言环境中，币种符号是美元号（$）。您可以 DBMONEY 环境变量设置非缺省的币种符号。当您将一行中的几个美元号分组时，单个币种符号浮动到它可占据的最右边的位置；它不影响该数值。

在 TO_CHAR 函数返回的格式化的值中，按字面重新产生格式掩码中的任何其他字符。

在下面的三个示例中，TO_CHAR 的 d_int 列表达式参数的值为 -12344455。

此查询在 TO_CHAR 的调用中未指定格式掩码：

        SELECT TO_CHAR(d_int) FROM tab_numbers;

下列表格展示此 SELECT 语句的输出。

(expression)
`-12344455`

下列查询指定货币格式掩码：

SELECT TO_CHAR(d_int, "$*********.**") FROM tab_numbers;

下列表格展示此 SELECT 语句的输出。

(expression)
`$12344455.00`

        SELECT TO_CHAR(d_int, "-$*********.**") FROM tab_numbers;

该查询返回 - $12344455.00。

SELECT TO_CHAR(12344455,"-$*********.**") FROM tab_numbers;

下列表格展示此 SELECT 语句的输出。

(constant)
`$12344455.00`

应用来自格式掩码参数的币种（$）符号，但减号（-）不起作用，因为第一个参数的值大于零。

请注意，当 TO_CHAR 函数的第一个参数是 DATE 或 DATETIME 表达式时，它是时间表达式，或是可被格式化为 DATE 或 DATETIME 表达式的字符串。然而，当它的第一个参数是数值或货币值时，TO_CHAR 返回那个参数的值的字符串形式，但它不返回时间表达式。