# 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 库使用指南](https://www.aardio.com/zh-cn/docs/library-guide/builtin/time/time.html) 创建时间对象，返回对象可传入其他线程使用。时间对象可作为调用 tonumber 的参数转换为自UTC时间1970年1月1日 00:00:00 到 3000年12月31日23:59:59 之间的秒数也可以作为调用tostring函数的参数转换为字符串 ### time() # 获取当前时间。不指定参数、或者格式化以前都是默认初始化为当前时间。不指定参数@1 在 milliseconds 字段返回毫秒数，且 dayofyear 字段无效, 参数@1指定其他参数时 milliseconds 字段总是为 0 [返回对象:timeObject](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#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](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#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](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#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](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#timeObject) ### time.istime() # 判断对象是否与 time 对象兼容的结构体。传入 time,time.ole 对象会返回 true。此函数仅检测结构体的类型声明不考虑对象的元表指向。 ### time.now # 获取当前时间并返回 time 对象。在 milliseconds 字段返回毫秒数，且 dayofyear 字段无效 ### time.now() # [返回对象:timeObject](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#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](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#timeObject) ## timeObject 成员列表 # ```aardio 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](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#timeObject) ### timeObject.addDays(输入数值) # 增加天数,可以为负数,返回自身 ### timeObject.addHours() # [返回对象:timeObject](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#timeObject) ### timeObject.addHours(输入数值) # 增加小时数,可以为负数,返回自身 ### timeObject.addMinutes() # [返回对象:timeObject](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#timeObject) ### timeObject.addMinutes(输入数值) # 增加分钟数,可以为负数,返回自身 ### timeObject.addMonths() # [返回对象:timeObject](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#timeObject) ### timeObject.addMonths(输入数值) # 增加月份数,返回自身 ### timeObject.addSeconds() # [返回对象:timeObject](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#timeObject) ### timeObject.addSeconds(输入数值) # 增加秒数,可以为负数,返回自身 ### timeObject.addYears() # [返回对象:timeObject](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#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(格式化串,区域代码) # ```aardio 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](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#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](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#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](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#timeObject) ### timeObject.toFileTime() # 转换并返回 ::FILETIME 结构体 ### timeObject.update() # 重新计算时间并更新dayOfWeek字段. [返回对象:timeObject](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#timeObject) ### timeObject.utc() # 将本地时间转换为 UTC 时间，修改并返回对象自身。如果已经是 UTC 时间直接返回。对象的格式化串（format 属性）首字符为`!`表示UTF时间。 [返回对象:timeObject](https://www.aardio.com/zh-cn/docs/library-reference/time/_.html#timeObject) ### timeObject.utc(true) # 将本地时间转换为 UTC 时间。参数为 true 则不修改自身而是返回新对象。如果已经是 UTC 时间则复制并返回复制的新对象。 ### timeObject.year # 年