time 库模块帮助文档

time 成员列表 #

日期时间,这是自动导入的内核类库,
字符串格式化支持从 1900 年 1 月 1 日 到 9999 年 12 月 31 日 的时间
可用 tonumber 转换为自 UTC 时间 1970 年 1 月 1 日 00:00:00 到 3000 年 12 月 31 日 23:59:59 间的秒数
需要更宽的运算范围请使用继承自 time 的 time.ole 类库。

time 库使用指南

创建时间对象，返回对象可传入其他线程使用。

时间对象可作为调用 tonumber 的参数转换为
自UTC时间1970年1月1日 00:00:00 到 3000年12月31日23:59:59 之间的秒数

也可以作为调用tostring函数的参数转换为字符串

time() #

获取当前时间。
不指定参数、或者格式化以前都是默认初始化为当前时间。

不指定参数@1 在 milliseconds 字段返回毫秒数，且 dayofyear 字段无效,
参数@1指定其他参数时 milliseconds 字段总是为 0

返回对象:timeObject

time(dateTime,format,local,lax) #

• 参数 @dateTime 可指定表示时间的数值、字符串或需要复制的 time、time.ole 对象。
  也可以用参数 @dateTime 指定指定包含部分时间对象字段的参数表，不指定参数 @dateTime 则初始化为当前时间。
  
• 可选用参数 @format 指定默认格式化串,首字符为 ! 表示 UTC 时间。
  格式化串可用于自文本解析时间，也可将时间格式化为文本。
  也可修改返回时间对象的 format 属性以单独变更输出格式。
  省略格式串时则默认设为 %Y/%m/%d %H:%M:%S，可兼容解析 ISO8601 格式的时间。
  参数 @dateTime 为文本时，则依据参数 @format 指定的格式化串解析时间。
  自文本解析时间使用尽可能宽松的规则，格式串中非 % 前导的字符、分隔符都不要求精确匹配。
  兼容宽松的无百分号风格格式化串（自动转为百分号格式），例如 "yyyy-mm-dd HH:MM:SS"。
  如果输入文本中的时间数值超出日期范围，或者输入文本提前结束，都会返回 null 。
  如果出现当月不存在的日期且小于 31 号时会顺推为下月时间。
  
• 可选用参数 @local 指定对象的 locale 属性，即格式化时间使用的区域语言。
  locale 支持的区域语言 与 setlocale 函数相同,英文 "enu",中文 "chs"。
  
• 参数 @lax 用于指定自文本解析时间是否允许缺少格式串已指定的时分秒部分（年月日不可省略）。
  仅参数 @1,@2 都是字符串有效，指定参数 @format 则默认为 false，否则为 true

time.date #

创建短日期格式时间。
返回的时间对象总是会将格式串（format 属性）默认设为 %Y-%m-%d 。
时分秒都默认设为 0 。

此函数总是返回本地时间，可通过 utc 方法转为 UTC 时间。

time.date() #

返回对象:timeObject

time.date(dateTime,format,local) #

支持 time 构造函数函数的所有参数用法。

• 参数 @dateTime 可指定表示时间的数值、字符串或需要复制的 time、time.ole 对象。
  也可以指定指定包含部分时间对象字段的参数表，省略此参数则初始化为当前时间。
  
• 可选的参数 @format 用于指定解析文本时间的格式串。
  其默认值仍为 %Y/%m/%d %H:%M:%S（解析时不允许省略时间部分）。
  但 time.date 在使用默认格式串失败后会改用短日期格式串 %Y-%m-%d 解析时间。
  无论使用什么格式串，始终会宽松匹配不同的分隔符。
  返回时间对象的格式串（format 属性）总是默认设为 %Y-%m-%d 。

time.date(year,month,day) #

创建短日期对象。
年月日分别由参数 @year,@month,@day 指定，所有参数不可省略。
如果 @month 不是1~12的数值，或 @day 不是 1~31 范围的数值则会抛出异常。
返回时间的格式串（format 属性）默认设为 %Y-%m-%d 。

time.format(format,local) #

取当前时间并返回格式化后的字符串。
所有参数可选，参数用法请参考 time 构造函数与 time 库使用指南。
格式化串使用百分号风格，例如："!%Y年%m月%d日 %H时%M分%S秒"。
兼容不带百分号风格的时间格式串，例如 "!yyyy-mm-dd HH:MM:SS"（Y D S 忽略大小写）。
locale 参数支持的区域语言 与 setlocale 函数相同,英文 "enu",中文 "chs"

time.format(timeObject,format,local) #

格式化 timeObject 参数指定的 time 或 time.ole 对象，并返回字符串。
所有参数可选，参数用法请参考 time 构造函数与 time 库使用指南。
提供这个函数只是因为命名的原因比较好找到，改用 tostring 可支持以与这里相同的参数用法格式化时间，还可以少打几个字符。
也可以直接调用 timeObject.format 方法，作用相同。

time.gmt() #

返回 RFC1123 格式 GMT 时间，HTTP 协议使用该格式。
JavaScript 的 toUTCString 或 toGMTString 方法也使用这种格式。

参数可以是数值，字符串，或其他time对象，用法参考time构造函数，
如果参数是使用本地时间的 time 对象，返回补偿时后的标准时间。
如果参数是字符串，可兼容解析 RFC 850，RFC1123 两种格式，
例如："Sun， 07 Feb 2016 01:11:22 GMT"，
字符串中如果使用数值格式指定了时区，将自动补偿时差转换为 GMT 时区
时区以正负号开始，支持省略冒号分隔符的1位，2位，3位，4位数字缩写

返回对象:timeObject

time.iso8601() #

ISO8601 格式 UTC 标准时间。
时间格式串为!%Y-%m-%dT%H:%M:%SZ（ RFC3339 格式 ）。
兼容 JavaScript 的 toISOString 返回格式。

参数 @1 可以是数值时间戳，字符串，或其他 time 对象，与 time 构造函数用法相同，
如果参数 @1 是使用本地时间的 time 对象，则返回补偿时差后的标准时间。
如果参数 @1 是字符串，兼容 ISO8601 省略分隔符的写法。
允许省略时间部分，允许从右侧开始依次省略秒、分、时（默认值为 0）。
但字符串的日期部分必须包含年月日。
如果未省略“秒”部分则可识别小数点后的毫秒数，但格式化为字符串时忽略毫秒数。
字符串中如果使用数值格式指定了时区，将自动补偿时差并转换为 UTC 时间，区别仅仅是默认格式化串不同。
时区以正负号开始，支持省略冒号分隔符的1位，2位，3位，4位数字缩写。

返回对象:timeObject

time.istime() #

判断对象是否与 time 对象兼容的结构体。
传入 time,time.ole 对象会返回 true。
此函数仅检测结构体的类型声明不考虑对象的元表指向。

time.now #

获取当前时间并返回 time 对象。
在 milliseconds 字段返回毫秒数，且 dayofyear 字段无效

time.now() #

返回对象:timeObject

time.now(format,local) #

取当前时间并返回 time 对象，等价于省略第一个参数调用 time 构造函数。
在 milliseconds 字段返回毫秒数，且 dayofyear 字段无效。
所有参数为可选参数。

可选用参数 @format 指定格式化串，首字符为 ! 表示 UTC 时间。
省略格式串时默认值为 %Y/%m/%d %H:%M:%S，可兼容解析 ISO8601 格式时间。
创建对象后可通过 format 属性单独修改输出时间格式。

可选用参数 @local 指定对象的 locale 属性，即格式化时间使用的区域语言。
locale 参数支持的区域语言 与 setlocale 函数相同,英文 "enu",中文 "chs"

time.stamp #

取 Unix 时间戳。
时间戳 0 表示 ISO8601 时间 1970-01-01T00:00:00Z

time.stamp(是否返回字符串,是否以秒为单位) #

所有参数可省略。
默认返回以毫秒为单位的时间戳数值，。
参数 @1 为 true 则返回文本，否则返回数值。
参数 @2 指定为 true 则返回值以秒为单位，否则以毫秒为单位。

time.tick() #

获取系统启动时间，单位毫秒。
XP 系统每 49.7 天重置为 0，之后的系统无此限制。
高精度高性能计时请参考 time.performance.tick 函数。

time.time(dateTime,format,lax) #

与 time 构造函数函数的所有参数用法相同。
区别是省略参数 @format 使用的默认值为 %H:%M:%S（匹配时分秒，无日期部分）。
日期部分的值初始化为当前日期，省略参数 @1 则初始化为当前时间。
如果参数 @lax 为 true 则允许自右向左省略时分秒部分（省略部分置为 0，可传空字符串）。

time.utc() #

返回 UTC 标准时间。
time.gmt,time.utc 返回相同的 UTC 时间，区别仅仅是默认格式化串不同。
参数可以是数值，字符串，或其他 time 对象，用法参考 time 构造函数，
如果参数是使用本地时间的 time 对象，返回补偿时后的标准时间。
格式化串默认指定为 "!%Y/%m/%d %H:%M:%S"
可兼容解析 ISO8601 格式（可省略分隔符）。
允许省略时间部分，允许从右侧开始依次省略秒、分、时（默认值为 0）。
但字符串的日期部分必须包含年月日。

返回对象:timeObject

timeObject 成员列表 #

class datetime{  
WORD year; //年  
WORD month; //月  
WORD dayofweek; //星期  
WORD day; //日期  
WORD hour; //小时  
WORD minute; //分钟  
WORD second; //秒  
WORD milliseconds; //这个字段正常情况下为0,只有在WINAPI函数中会起作用  
format; //时间格式字符串  
isdst //是否夏令时  
}

timeObject.addDays() #

返回对象:timeObject

timeObject.addDays(输入数值) #

增加天数,可以为负数,返回自身

timeObject.addHours() #

返回对象:timeObject

timeObject.addHours(输入数值) #

增加小时数,可以为负数,返回自身

timeObject.addMinutes() #

返回对象:timeObject

timeObject.addMinutes(输入数值) #

增加分钟数,可以为负数,返回自身

timeObject.addMonths() #

返回对象:timeObject

timeObject.addMonths(输入数值) #

增加月份数,返回自身

timeObject.addSeconds() #

返回对象:timeObject

timeObject.addSeconds(输入数值) #

增加秒数,可以为负数,返回自身

timeObject.addYears() #

返回对象:timeObject

timeObject.addYears(输入数值) #

增加年份,返回自身

timeObject.day #

日

timeObject.dayofweek #

星期
星期一到星期六的值对应数值为1到6,星期日的值为 0,
注意修改这个字段不会更新时间值,

这个字段只有参与数值运算或调用 add*** 函数才会填充或更新,
例如调用 addDays(0) 会更新此字段

timeObject.dayofyear #

所在年份的天数,
注意修改这个字段不会更新时间值。
无参数调用 time 或 time.now 函数此字段无效。

这个字段只有参与数值运算或调用 add*** 函数才会填充或更新,
例如调用addSeconds(0)会更新此字段,

使用格式化标记%j %U %W前必须首先刷新此字段

timeObject.diffDays(指定time对象) #

用当前 time 对象减参数指定的 time 对象，
计算两个 time 对象相差天数，此函数返回整数

timeObject.diffHours(指定time对象) #

用当前 time 对象减参数指定的 time 对象，
计算两个 time 对象相差小时数，此函数返回整数

timeObject.diffMinutes(指定time对象) #

用当前 time 对象减参数指定的 time 对象，
计算两个 time 对象相差分钟数，此函数返回整数

timeObject.diffMonths(指定time对象) #

用当前 time 对象减参数指定的 time 对象，
计算两个 time 对象相差月份，此函数返回整数

timeObject.diffSeconds(指定time对象) #

用当前 time 对象减参数指定的 time 对象，
计算两个 time 对象相差秒数，此函数返回整数

timeObject.diffYears(指定time对象) #

用当前 time 对象减参数指定的 time 对象，
计算两个 time 对象相差年份，相差不是整数年份时此函数会返回小数。

timeObject.endstr #

文本解析为时间后，
最后一个格式化标记解析成功并跳过空白字符以后的剩余字符串。

timeObject.format #

作为属性可读写默认格式化串,首字符为!表示 UTC 时间。
例如："!%Y年%m月%d日 %H时%M分%S秒"。
兼容不带百分号风格的时间格式串，例如 "!yyyy-mm-dd HH:MM:SS"（Y D S 忽略大小写）。
关于格式化串详细说明请查看 time 库文档。
参数 @2 setlocale 函数支持相同的区域语言代码，例如：英文"enu",中文"chs"

timeObject.format(格式化串,区域代码) #

timeObject.format("%Y/%m/%d %H:%M:%S")/*作为方法调用（ owner.call 方式 ）时可格式化时间并返回字符串。  
所有参数可选，格式化串兼容百分号与无百分号风格，示例：  
 "%Y年%m月%d日 %H时%M分%S秒" 或 "yyyy-mm-dd HH:MM:SS" 。  
关于格式化串详细说明请查看 time 库使用指南。*/

timeObject.fromFileTime() #

返回对象:timeObject

timeObject.fromFileTime(/输入::FILETIME对象/) #

自参数 @1 指定的 ::FILETIME 结构体获取时间，返回自身。
参数 @1 也可以指定 fsys.time 对象。

timeObject.getMilliTime() #

返回自UTC时间 1970年1月1日 00:00:00 开始的毫秒数
最大值为UTC时间3000年12月31日23:59:59

timeObject.hour #

小时

timeObject.local() #

将 UTC 时间转换为本地时间，修改并返回对象自身。
如果已经是本地时间则直接返回对象自身。
对象的格式化串（format 属性）首字符为!表示 UTC 时间。

返回对象:timeObject

timeObject.local(true) #

将 UTC 时间转换为本地时间。
参数为 true 则不修改自身而是返回新对象。
如果已经是本地时间则直接复制并返回复制的新对象。

timeObject.locale #

格式化时间使用的语言代码
参数与setlocale相同,英文"enu",中文"chs",
该属性为空表示使用当前默认语言

timeObject.milliseconds #

毫秒。
构造 time 对象不指定参数 @1 或用 time.now 取当前时间，则设置此字段为当前毫秒数，否则此字段无效

timeObject.minute #

分钟

timeObject.month #

月

timeObject.second #

秒

timeObject.setMilliTime() #

参数为数值
设置自UTC时间 1970年1月1日 00:00:00 开始的毫秒数
最大值为UTC时间3000年12月31日23:59:59
此函数返回时间对象自身

返回对象:timeObject

timeObject.toFileTime() #

转换并返回 ::FILETIME 结构体

timeObject.update() #

重新计算时间并更新dayOfWeek字段.

返回对象:timeObject

timeObject.utc() #

将本地时间转换为 UTC 时间，修改并返回对象自身。
如果已经是 UTC 时间直接返回。

对象的格式化串（format 属性）首字符为!表示UTF时间。

返回对象:timeObject

timeObject.utc(true) #

将本地时间转换为 UTC 时间。
参数为 true 则不修改自身而是返回新对象。
如果已经是 UTC 时间则复制并返回复制的新对象。

timeObject.year #

年

Markdown 格式