Time

概述

该分类下的函数通常都支持使用date、time、datetime、datetimezone作为时间计算。

时间、日期、时区运算为了保持本地和远程结果一致性，应该尽可能的显式传入如时区、周几作为开始等信息。

时间的精度为100ns，即一天中的时间范围是00:00:00到23:59:59.9999999。

时间值#time(24, 0, 0)是一个特殊的值，应尽可能避免使用该值。它可能会被当做一整天看待，也可能当做#time(0, 0, 0)看待。具体参见值-时间中的介绍。

#time

#time(hour as number, minute as number, second as number) as time

根据输入值返回time类型的值。

取值范围：

• 0≤ hour ≤ 23
• 0≤ minute ≤ 59
• 0≤ second < 60

除second之外，其他参数都必须是整数。

参数hour可以为24，但是此时minute和second必须为0。

#time(24, 0, 0)是一个特殊的时间值，在没搞清楚使用规则时应该避免使用。

#time(2, 3, 4.33333)

Time.EndOfHour

Time.EndOfHour(dateTime as any) as any

返回dateTime在前小时的最后一个时刻的时间（返回类型和参数dateTime类型一致）。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，所以结果始终是本身。

Time.EndOfHour(#time(2, 3, 4))

Time.EndOfHour(#date(2022, 1, 1))

Time.EndOfHour(#datetime(2022, 1, 1, 2, 3, 4))

Time.EndOfHour(#datetimezone(2022, 1, 1, 2, 3, 4, 8, 0))

Time.From

Time.From(
    value as any, 
    optional culture as nullable text
) as nullable time

根据给定的值value和可选的区域culture返回日期。

value为不同类型时：

• null，返回null。
• text，文本形式的时间使用Time.FromText计算。
• datetime，返回时间部分。
• datetimezone，返回等效的时间部分（根据value和culture的时区信息计算出新的时间）。
• number，表示OLE自动化的日期等效的时间部分。

Time.FromText

Time.FromText(
    text as nullable text, 
    optional options as any
) as nullable time

根据提供的文本text和可选的参数options返回日期时间。

options可以是不同类型：

• 记录类型，字段名可以是
  • Format，一个文本值，指示如何解析文本日期时间，具体参见标准日期时间格式字符串和自定义日期时间格式字符串。
  • Culture，可为空的文本值，指定文本日期时间的区域。默认使用本机区域（Culture.Current）。
• 文本类型，指示国家地区。

经过测试，**Time.FromText**并不支持自定义格式字符串。

如果有缺失值：

• 日期全部或部分缺失时，时、分、秒使用0。

// error 无法使用指定格式将文本值转换为 time。该格式包括 日期 组件。
Time.FromText("9.15T2:3:4", [Format = "M/ddTH:m:s"])

// 2:03:04，结果不符合预期
Time.FromText("2:3:4", [Format="s:h:m"])

// 2:00:00
Time.FromText("02")
// error
Time.FromText("2")

// 2:05:00
Time.FromText("2:5")

// 02:03:04.6660000
Time.FromText("2:3:4.666")

Time.Hour

Time.Hour(dateTime as any) as nullable number

返回dateTime的小时部分（整数0-23）。

参数dateTime可以设置的类型是datetime、datetimezone、time。

Time.Hour(#time(2, 3, 4))

Time.Hour(#datetime(2022, 12, 1, 4, 5, 6))

Time.Minute

Time.Minute(dateTime as any) as nullable number

返回dateTime的分钟部分（整数0-59）。

参数dateTime可以设置的类型是datetime、datetimezone、time。

Time.Minute(#time(2, 3, 4))

Time.Minute(#datetime(2022, 12, 1, 4, 5, 6))

Time.Second

Time.Second(dateTime as any) as nullable number

返回dateTime的秒部分（浮点数0-59.9999999）。

参数dateTime可以设置的类型是datetime、datetimezone、time。

Time.Minute(#time(2, 3, 4))

Time.Minute(#datetime(2022, 12, 1, 4, 5, 6))

Time.StartOfHour

Time.StartOfHour(dateTime as any) as any

返回dateTime在前小时的第一个时刻的时间（返回类型和参数dateTime类型一致）。

参数dateTime可以设置的类型是datetime、datetimezone、date、time。

• date：因为缺失时间部分，因此时间部分为#time(0, 0, 0)，但因为需要返回date类型的值，所以结果始终是本身。

Time.StartOfHour(#time(2, 3, 4))

Time.StartOfHour(#date(2022, 1, 1))

Time.StartOfHour(#datetime(2022, 1, 1, 2, 3, 4))

Time.StartOfHour(#datetimezone(2022, 1, 1, 2, 3, 4, 8, 0))

Time.ToRecord

Time.ToRecord(time as time) as record

将时间值time的转换成记录，记录的字段名是时间的各部分。

Time.ToText

Time.ToText(
    time as nullable time, 
    optional options as any, 
    optional culture as nullable text
) as nullable text

根据日期time返回日期的文本，文本结果会考虑参数options和culture。

options可以是不同类型：

• 记录类型，字段名可以是
  • Format，一个文本值，格式化文本字符串，具体参见标准日期时间格式字符串和自定义日期时间格式字符串。
  • Culture，可为空的文本值，指定文本日期的区域。默认使用本机区域（Culture.Current）。
• 文本类型，一个文本值，指示如何解析文本日期。等同Format字段的意思。

culture用于指定区域，默认为本机区域。该参数仅可用于传统工作流。如果options为记录，将会忽略culture参数。
如果输出的部分不存在，则按照默认值输出：日期为0001-01-01；时区不会使用设置的区域，而是使用本机区域的时区。
当options为记录时，无法使用时区格式字符串。

// 15:09:56+08:00
Time.ToText(#time(15, 9, 56.3333), "HH:mm:sszzz", "en-US")
// 0001-01-01+08:00
Time.ToText(#time(15, 9, 56.3333), "yyyy-MM-ddzzz", "en-US")

// error 无法使用指定格式将文本值转换为 time。该格式包括 日期 组件。
Time.ToText(#time(15, 9, 56.3333), [Format="yyyy-MM-ddzzz", Culture="en-US"])