CONVERT_TZ

  • 本文以CONVERT_TZ为例,说明函数文档的编写要求。
  • 如果文档中文字说明部分需要引用语法和示例,则建议使用代码块形式。

功能

将给定的时间转化为另一个时区的时间。

简要描述函数功能。如果有进一步的解释说明,也可以在这里补充。

语法

CONVERT_TZ(dt, from_tz, to_tz)

函数的语法结构,使用代码块包裹。

参数说明

  • dt :需要转化的时间。支持的数据类型为 DATETIME。
  • from_tz :源时区名称。支持的数据类型为 VARCHAR。时区可以使用两种格式:时区信息数据库(Time Zone Database,比如 Asia/Shanghai),或 UTC 偏移量(例如+08: 00)。
  • to_tz:目标时区名称。支持的数据类型为 VARCHAR。格式同参数 from_tz
  • 格式为 参数:描述+数据类型(请列出所支持的全部数据类型)。
  • 描述部分包括参数的含义、是否必选、取值格式、取值范围、不同数据类型下的取值和单位差异等。
  • 数据类型需要字母大写,比如DATETIME。

返回值说明

返回值的数据类型为 DATETIME。 返回DATETIME类型的值。

  • 数据类型需要字母全大写。
  • 如有必要,可以适当补充特殊说明,例如:
    • 如果输入值支持不同数据类型,当输入值为不同数据类型时,对应返回值的数据类型或格式。
    • 如果输入值不满足数据类型的要求,则其返回结果是什么,比如 NULL,报错。

注意事项 (可选)

各时区对应的时区信息数据库,请参见时区数据库(来源:维基百科)。

使用该函数时的注意事项或者限制(可选)。

示例

示例一:将上海时间转化为洛杉矶时间。

MySQL > select convert_tz('2019-08-01 13:21:03', 'Asia/Shanghai', 'America/Los_Angeles');
        -> 2019-07-31 22:21:03                                                       |

示例二:将东八区时间转化为洛杉矶时间。

MySQL > select convert_tz('2019-08-01 13:21:03', '+08:00', 'America/Los_Angeles');
+--------------------------------------------------------------------+
| convert_tz('2019-08-01 13:21:03', '+08:00', 'America/Los_Angeles') |
+--------------------------------------------------------------------+
| 2019-07-31 22:21:03                                                |
+--------------------------------------------------------------------+
  • 不同示例的代码需要放在不同的代码块里。
  • 需要说明各个示例的作用。
  • 如果一个示例中包含多个应用场景,可在示例中加上注解,便于用户快速区分场景。
  • 示例的返回结果如果较简单,则建议采用示例一的展现形式;如果较复杂,则建议采用示例二的展现形式。
  • *正文描述中参数和参数值使用code format (``)包裹。