Sharp表达式 - 日期时间操作

在开发中时间类型应用非常多，PQL 在 Sharp 表达式中实现了各种各样的时间处理方法，下面均以变量$datetime为例进行分组介绍。

日期时间格式化

FORMAT 'format' 按指定的格式对日期时间进行格式化，返回字符串。下面说明一下格式中各个字母的意义：
- y 表示年，2位返回19，4位返回2019
- Q或q 表示季度，1 位返回3，2 位返回03，3 位返回Q3，4 位返回3rd quarter。中文环境下返回中文，如3季、第3季度。
- M 表示月，1位返回4，2位返回04，3位返回Apr，4位返回 April。中文环境下返回中文，如四月。
- d 表示天，1位和2位都返回15，1位时小于10才返回1位数字
- H 表示24小时制小时，1位和2位都返回13，1位时小于10返回1位数字
- h 表示12小时制小时，1位返回1，2位返回01
- m 表示分钟，1位和2位都返回27，1位时分钟小于10时返回1位数字。
- s 表示秒，1位返回5，两位返回05
- S 表示毫秒，一般为3位
- e或E 表示星期，1位返回1，2位返回01，3位返回Mon，4 位返回Monday。中文环境下返回中文，如星期一。
- a 表示上下午，返回AM或PM。中文环境下返回上午或下午。

获取日期时间的某一部分

以下操作的返回值为整数。

GET YEAR 返回年份，结果为2019。
GET QUARTER 返回年份，结果为2019。
GET MONTH 返回月份，结果为4。
GET DAY 返回日期，结果为15。
GET HOUR 返回小时，结果为13。
GET MINUTE 返回分钟，结果为27。
GET SECOND 返回秒，结果为 5。
GET MILLI 返回毫秒，秒后 3 位。
GET MICRO 返回微秒，秒后 6 位。
GET NANO 返回纳秒，秒后 9 位。
GET WEEK 返回星期，结果为1。星期二返回2，星期日返回7。
GET WEEK OF YEAR 返回日期时间所在周是一年内的第几周，参数为星期简称或全称或数字1~7，表示星期几为一周的开始。如@NOW GET WEEK OF YEAR 'MONDAY'，不传参数默认“周一”。

以下操作的返回值为字符串：

GET QUARTER NAME 返回三位的星期名称字符串，同FORMAT 'eee'。
GET MONTH NAME 返回三位的星期名称字符串，同FORMAT 'eee'。
GET WEEK NAME 返回三位的星期名称字符串，同FORMAT 'eee'。
GET FULL QUARTER NAME 返回三位的星期名称字符串，同FORMAT 'eee'。
GET FULL MONTH NAME 返回三位的星期名称字符串，同FORMAT 'eee'。
GET FULL WEEK NAME 返回三位的星期名称字符串，同FORMAT 'eee'。

设置日期时间的某一部分

以下操作的参数均为整数，返回值均为新的日期时间。

SET YEAR n 设置年份，接受4位整数。
SET MONTH n 设置月份，接受1到12之间的整数。
SET DAY n 设置日期，接受1到31之间的整数，但不能设置不存在的日期，比如2月30日。
SET HOUR n 设置小时，接受0到23之间的整数。
SET MINUTE n 设置分钟，接受0到59之间的整数。
SET SECOND n 设置秒，接受0到59之间的整数。
SET MILLI n 毫秒，秒后3位
SET MICRO n 微秒，秒后6位
SET NANO n 纳秒，秒后9位
SET WEEK n 接受1到7之间的整数，分别代表星期一到星期日。

增加或减少日期时间的某一单位

以下操作的参数均为整数，且均支持负值，返回值均为新的日期时间。

PLUS n 在当前日期时间上增加n毫秒。
PLUS n [UNIT] 在当前日期时间上增加n个时间单位。[UNIT]代表时间单位，可选值见下面的说明。
PLUS YEARS n ** 在当前日期时间上增加n年。
PLUS MONTHS n 在当前日期时间上增加n月。
PLUS DAYS n 在当前日期时间上增加n天。
PLUS HOURS n 在当前日期时间上增加n小时。
PLUS MINUTES n 在当前日期时间上增加n分钟。
PLUS SECONDS n 在当前日期时间上增加n秒。
PLUS MILLIS n 在当前日期时间上增加n毫秒。
PLUS MICROS n 在当前日期时间上增加n微秒。
PLUS NANOS n 在当前日期时间上增加n纳秒。
MINUS n 在当前日期时间上减去n毫秒。
MINUS n [UNIT] 在当前日期时间上增加n个时间单位。[UNIT]代表时间单位，可选值见下面的说明。
MINUS YEARS n 在当前日期时间上减去n年。
MINUS MONTHS n 在当前日期时间上减去n月。
MINUS DAYS n 在当前日期时间上减去n天。
MINUS HOURS n 在当前日期时间上减去n小时。
MINUS MINUTES n 在当前日期时间上减去n分钟。
MINUS SECONDS n 在当前日期时间上减去n秒。
MINUS MILLIS n 在当前日期时间上减去n毫秒。
MINUS MICROS n 在当前日期时间上减去n微秒。
MINUS NANOS n 在当前日期时间上减去n纳秒。

上面有两个操作用到了时间单位，时间单位也属于 Sharp 表达式的操作，作用是将整数的时间单位转成毫秒值，如$datetime PLUS 20 MINUTES或$datetime MINUS 1 HOUR。所有支持的单位如下：

YEAR 或 YEARS 年
MONTH 或 MONTHS 月
DAY 或 DAYS 天
HOUR 或 HOURS 小时
MINUTE 或 MINUTES 分钟
SECOND 或 SECONDS 秒
MILLI 或 MILLIS 毫秒
MICRO 或 MICROS 微秒
NANO 或 NANOS 纳秒

下例中 4 个 Sharp 表达式的结果相同，可根据个人习惯选择不同的操作。

快速编辑日期时间

除上面提供了 PLUS 和 MINUS 外，Sharp 表达式中还提供了额外的设置日期时间的方法。

EXPRESS 'expression' 通过时间表达式快速设置日期时间。举个例子，使用上面介绍的方法将日期设置到本月最后一天的0点0分0秒： $datetime PLUS MONTHS 1 SET DAY 1 MINUS DAYS 1 SET HOUR 0 SET MINUTE 0 SET SECOND 0 SET NANO 0
用EXPRESS可以简写为：
$datetime EXPRESS 'MONTH+1#DAY=1#DAY-1#HOUR=0#MINUTE=0#SECOND=0#NANO=0' 或 $datetime EXPRESS 'DAY=L#HOUR=0#MINUTE=0#SECOND=0#NANO=0'
- EXPRESS由一个或多个时间表达式构成，时间表达式之间用井号#隔开。
- 每个时间表达式由“时间单位”+“操作符”+“值”构成。
- 支持的时间单位有：YEAR,MONTH,DAY,WEEK,MINUTE,SECOND,MILLI,MICRO,NANO。时间单位不区分大小写。
- 支持的操作符有：=表示设置，+表示增加，-表示减去。
- 值部分除了支持各时间单位允许的整数值。
- 设置DAY时支持L，表示最后一天。
- 设置WEEK时支持三位的星期名称：Mon,Tue, Wed, Thu, Fri, Sat, Sun
SET ZERO OF DAY 设置时间为当天的0点0分0秒。
SET BEGINNING OF MONTH 设置时间为当月的每1天的0点0分0秒。

日期时间比较、转换和其他

日期时间比较和数字的比较类似，一般比较两个时间的早晚或者差值。

AFTER 'otherTime' 判断指定的日期时间是否晚于另一个日期时间，基本等效于>。
AFTER OR EQUALS 'otherTime' 判断指定的日期时间是否晚于或等于另一个日期时间，基本等效于>=。
**BEFORE 'otherTime' 判断指定的日期时间是否早于另一个日期时间，基本等效于<。
**BEFORE OR EQUALS 'otherTime' 判断指定的日期时间是否早于或等于另一个日期时间，基本等效于<=。
EQUALS 'otherTime' 判断指定的日期时间是否等于另一个日期时间，基本等效于=或==。

上面几个操作与比较操作符的区别为：比较操作符会优先转成数字做比较，AFTER和BEFORE会将两端的值转成日期时间再做比较；EQUALS如果两端有一个是日期时间，则两端都转成日期时间做比较，否则都转成字符串做比较。举个例子：2020-08-17 12:00:00转成纪元秒为1597636800，1597636800 AFTER '2020-08-07 12:00:00'结果为true，但是1597636800 > '2020-08-07 12:00:00'会报错。

LATER 'otherTime' 计算指定日期时间晚于另一个日期时间多少毫秒，负数表示早于另一个日期时间。
EARLIER 'oterTime' 计算指定日期时间早于另一个日期时间多少毫秒，负数表示晚于另一个日期时间。
SPAN 'otherTime' 计算指定日期日期和另一个日期时间之间的毫秒差，返回值均大于等于0。日期时间差为毫秒数，一般会转化为狗日的读的天或小时等数字，如$datetime SPAN $time2 TO DAYS。
TO EPOCH 将日期时间转化为纪元秒，10 位整数。
TO EPOCH SECOND 同上。
TO EPOCH MILLI 将时间转化为纪元毫秒，13 位整数。
TO DATETIME 可以将 10 位纪元秒整数或13位纪元毫秒整数转化为日期时间，也可以尝试将其他类型的数据比如日期时间字符串转成日期时间。一般情况下会自动判断，自动判断不正确时可以使用这个操作。可转换格式见本章最后一节。
TO DATETIME 'format' 将其他类型的值按给定格式转化为时间，一般情况下会自动判断，转换不了时可使用这个操作。如'2020年8月4日' TO DATETIME 'yyyy年M月d日'。
MATCHES CRON 'cron_exp' 判断日期时间是否匹配指定的Cron表达式，经常会和TICK BY配合使用。

其他与日期时间相关的表达式

这些操作要编辑的数据都不是日期时间，最后一个是字符串，其他是整数。但这些操作都与日期时间有关。

TO SECONDS 将毫秒数转化为秒，返回小数，一般与SPAN连用
TO MINUTES 将毫秒数转化为分钟，返回小数，一般与SPAN连用
TO HOURS 将毫秒数转化为小时，返回小数，一般与SPAN连用
TO DAYS 将毫秒数转化为天，返回小数，一般与SPAN连用
TO TIMESPAN 'units' 将毫秒数转化易读的字符串，一般与SPAN连用。如果不设置units参数，默认的单位为'd,h,m,s,ms'，返回值的格式为'1d2h'，最多只有两个时间单位。可以设置时间单位，如'天,小时,分钟,秒,毫秒'，前面的返回值就会变成'1天2小时'。
TICK BY 'datetime' 根据指定的时间datetime获取Cron表达式的下一次匹配。'0 0 * * * ? *' TICK BY '2020-08-08 12:28:35'结果是'2020-08-08 13:00:00'

日期时间的自动转化规则

Sharp 表达式在执行时会根据操作名称自动将要操作的值转成相应的类型，下面是可转成日期的格式列表。

'yyyyMMdd' 如'20200815'转成'2020-08-15 00:00:00'
'HH:mm:ss' 如'16:31:25'转成'2020-08-17 16:31:25'，即加上今天（如2020年8月17日）的日期。
'yyyy-MM-dd'
'yyyy/MM/dd'
'dd/MM/yyyy'
'yyyyMMddHHmm'
'yyyyMMddHHmmss'
'yyyyMMddHHmmss.S' 含1位毫秒
'yyyyMMddHHmmss.SS' 含2位毫秒
'yyyyMMddHHmmss.SSS' 含3位毫秒
'yyyy-MM-dd HH:mm:ss'
'yyyy-MM-dd HH:mm:ss.S' 含1位毫秒
'yyyy-MM-dd HH:mm:ss.SS' 含2位毫秒
'yyyy-MM-dd HH:mm:ss.SSS' 含3位毫秒
10位整数，按纪元秒转换
13位整数，按纪元毫秒转换

当要使用的日期时间不在上述格式中时，可用TO DATETIME 'format'进行转换。

参考链接