结构体

struct DateTime

public struct DateTime <: ToString & Hashable & Comparable<DateTime>

功能:DateTime 表示日期时间,是一个描述某一时间点的时间类型,提供了基于时区的日期时间读取、计算、比较、转换,以及序列化和反序列化等功能。

  • DateTime 是不可变的类型,包含了日期,时间和时区信息。可表示的时间区间为 [-999,999,999-01-01T00:00:00.000000000, 999,999,999-12-31T23:59:59.999999999],该区间适用于任何合法的时区。

  • 以下为 DateTimenownowUTC 函数获取当前时间使用的系统调用函数:

    系统系统调用函数时钟类型
    Linuxclock_gettimeCLOCK_REALTIME
    Windowsclock_gettimeCLOCK_REALTIME
    macOSclock_gettimeCLOCK_REALTIME

父类型:

static prop UnixEpoch

public static prop UnixEpoch: DateTime

功能:获取 Unix 时间纪元,即表示零时区 1970年1月1日0时0分0秒0纳秒DateTime 实例。

类型:DateTime

prop dayOfMonth

public prop dayOfMonth: Int64

功能:获取 DateTime 实例基于当前月第几日。

类型:Int64

prop dayOfWeek

public prop dayOfWeek: DayOfWeek

功能:获取 DateTime 实例基于当前周的第几日。

类型:DayOfWeek

prop dayOfYear

public prop dayOfYear: Int64

功能:获取 DateTime 实例基于当前年份的第几日。

类型:Int64

prop hour

public prop hour: Int64

功能:获取 DateTime 实例的小时。

类型:Int64

prop isoWeek

public prop isoWeek: (Int64, Int64)

功能:获取 DateTime 实例基于 ISO8601 标准的年份和基于年的周数。

类型:(Int64, Int64)

prop minute

public prop minute: Int64

功能:获取 DateTime 实例的分钟。

类型:Int64

prop month

public prop month: Month

功能:获取 DateTime 实例的月份。

类型:Month

prop monthValue

public prop monthValue: Int64

功能:获取 DateTime 实例以数字形式表示的月份。

类型:Int64

prop nanosecond

public prop nanosecond: Int64

功能:获取 DateTime 实例的纳秒。

类型:Int64

prop second

public prop second: Int64

功能:获取 DateTime 实例的秒。

类型:Int64

prop year

public prop year: Int64

功能:获取 DateTime 实例的年份。

类型:Int64

prop zone

public prop zone: TimeZone

功能:获取 DateTime 实例所关联的时区。

类型:TimeZone

prop zoneId

public prop zoneId: String

功能:获取 DateTime 实例所关联的 TimeZone 实例的时区 ID。

类型:String

prop zoneOffset

public prop zoneOffset: Duration

功能:获取 DateTime 实例所关联的 TimeZone 实例的时间偏移。

类型:Duration

static func fromUnixTimeStamp(Duration)

public static func fromUnixTimeStamp(d: Duration): DateTime

功能:获取自 UnixEpoch 开始,参数 d 指定时间间隔后的日期时间。

参数:

返回值:

异常:

static func now(TimeZone)

public static func now(timeZone!: TimeZone = TimeZone.Local): DateTime

功能:获取参数 timeZone 指定时区的当前时间。该方法获取的当前时间受系统时间影响,如存在使用不受系统时间影响的计时场景,可使用 MonoTime.now() 替代。

参数:

  • timeZone!: TimeZone - 时区,默认为本地时区。

返回值:

  • DateTime - 返回指定时区当前时间。

static func nowUTC()

public static func nowUTC(): DateTime

功能:获取 UTC 时区的当前时间。该方法获取的当前时间受系统时间影响,如存在使用不受系统时间影响的计时场景,可使用 MonoTime.now() 替代。

返回值:

static func of(Int64, Int64, Int64, Int64, Int64, Int64, Int64, TimeZone)

public static func of(
    year!: Int64,
    month!: Int64,
    dayOfMonth!: Int64,
    hour!: Int64 = 0,
    minute!: Int64 = 0,
    second!: Int64 = 0,
    nanosecond!: Int64 = 0,
    timeZone!: TimeZone = TimeZone.Local
): DateTime

功能:根据参数指定的年、月、日、时、分、秒、纳秒、时区构造 DateTime 实例。

参数:

  • year!: Int64 - 年,范围[-999,999,999, 999,999,999]。
  • month!: Int64 - 月,范围[1, 12]。
  • dayOfMonth!: Int64 - 日,范围[1, 31],最大取值需要跟 month 匹配,可能是 28、29、30、31。
  • hour!: Int64 - 时,范围[0, 23]。
  • minute!: Int64 - 分,范围[0, 59]。
  • second!: Int64 - 秒,范围[0, 59]。
  • nanosecond!: Int64 - 纳秒,范围[0, 999,999,999]。
  • timeZone!: TimeZone - 时区。

返回值:

异常:

static func of(Int64, Month, Int64, Int64, Int64, Int64, Int64, TimeZone)

public static func of(
    year!: Int64,
    month!: Month,
    dayOfMonth!: Int64,
    hour!: Int64 = 0,
    minute!: Int64 = 0,
    second!: Int64 = 0,
    nanosecond!: Int64 = 0,
    timeZone!: TimeZone = TimeZone.Local
): DateTime

功能:根据参数指定的年、月、日、时、分、秒、纳秒、时区构造 DateTime 实例。

参数:

  • year!: Int64 - 年,范围[-999,999,999, 999,999,999]。
  • month!: Month - 月,Month 类型。
  • dayOfMonth!: Int64 - 日,范围[1, 31],最大取值需要跟 month 匹配,可能是 28、29、30、31。
  • hour!: Int64 - 时,范围[0, 23]。
  • minute!: Int64 - 分,范围[0, 59]。
  • second!: Int64 - 秒,范围[0, 59]。
  • nanosecond!: Int64 - 纳秒,范围[0, 999,999,999]。
  • timeZone!: TimeZone - 时区。

返回值:

异常:

static func ofEpoch(Int64, Int64)

public static func ofEpoch(second!: Int64, nanosecond!: Int64): DateTime

功能:根据入参 secondnanosecond 构造 DateTime 实例。入参 second 表示 unix 时间的秒部分,nanosecond 表示 unix 时间的纳秒部分。unix 时间以 UnixEpoch 开始计算,nanosecond 的范围不可以超过[0, 999,999,999],否则抛出异常。

参数:

  • second!: Int64 - unix 时间的秒部分。
  • nanosecond!: Int64 - unix 时间的纳秒部分,范围不可以超过[0, 999,999,999]。

返回值:

异常:

static func ofUTC(Int64, Int64, Int64, Int64, Int64, Int64, Int64, TimeZone)

public static func ofUTC(
    year!: Int64,
    month!: Int64,
    dayOfMonth!: Int64,
    hour!: Int64 = 0,
    minute!: Int64 = 0,
    second!: Int64 = 0,
    nanosecond!: Int64 = 0
): DateTime

功能:根据参数指定的年、月、日、时、分、秒、纳秒构造 UTC 时区 DateTime 实例。

参数:

  • year!: Int64 - 年,范围[-999,999,999, 999,999,999]。
  • month!: Int64 - 月,范围[1, 12]。
  • dayOfMonth!: Int64 - 日,范围[1, 31],最大取值需要跟 month 匹配,可能是 28、29、30、31。
  • hour!: Int64 - 时,范围[0, 23]。
  • minute!: Int64 - 分,范围[0, 59]。
  • second!: Int64 - 秒,范围[0, 59]。
  • nanosecond!: Int64 - 纳秒,范围[0, 999,999,999]。

返回值:

异常:

static func ofUTC(Int64, Month, Int64, Int64, Int64, Int64, Int64, TimeZone)

public static func ofUTC(
    year!: Int64,
    month!: Month,
    dayOfMonth!: Int64,
    hour!: Int64 = 0,
    minute!: Int64 = 0,
    second!: Int64 = 0,
    nanosecond!: Int64 = 0
): DateTime

功能:根据参数指定的年、月、日、时、分、秒、纳秒构造 UTC 时区 DateTime 实例。

参数:

  • year!: Int64 - 年,范围[-999,999,999, 999,999,999]。
  • month!: Month - 月,Month 类型
  • dayOfMonth!: Int64 - 日, 范围[1, 31],最大取值需要跟 month 匹配,可能是 28、29、30、31。
  • hour!: Int64 - 时,范围[0, 23]。
  • minute!: Int64 - 分,范围[0, 59]。
  • second!: Int64 - 秒,范围[0, 59]。
  • nanosecond!: Int64 - 纳秒,范围[0, 999,999,999]。

返回值:

异常:

static func parse(String)

public static func parse(str: String): DateTime

功能:从参数 str 中解析得到时间,解析成功时返回 DateTime 实例。

参数:

  • str: String - 时间字符串,格式为 RFC3339date-time 格式,可包含小数秒,如 "2023-04-10T08:00:00[.123456]+08:00"([] 中的内容表示可选项)。

返回值:

异常:

static func parse(String, String)

public static func parse(str: String, format: String): DateTime

功能:根据 format 指定的时间格式,从字符串 str 中解析得到时间,解析成功时返回 DateTime 实例,解析具体规格可见下文“从字符串中解析得到时间”模块。

参数:

  • str: String - 时间字符串,例如:"2023/04/10 08:00:00 +08:00"。
  • format: String - 时间字符串的格式,例如:"yyyy/MM/dd HH:mm:ss OOOO"。格式说明详见时间字符串格式

返回值:

  • DateTime - 根据参数 format 指定的时间格式,从参数 str 中解析出的 DateTime 实例。

异常:

static func parse(String, DateTimeFormat)

public static func parse(str: String, format: DateTimeFormat): DateTime

功能:根据 format 指定的时间格式,从字符串 str 中解析得到时间,解析成功时返回 DateTime 实例,解析具体规格可见下文“从字符串中解析得到时间”模块。

参数:

  • str: String - 时间字符串,例如:"2023/04/10 08:00:00 +08:00"。
  • format: DateTimeFormat - 时间格式,例如:"yyyy/MM/dd HH:mm:ss OOOO"对应的时间格式。格式说明详见时间字符串格式

返回值:

  • DateTime - 根据参数 format 指定的时间格式,从参数 str 中解析出的 DateTime 实例。

异常:

func addDays(Int64)

public func addDays(n: Int64): DateTime

功能:获取 DateTime 实例 n 天之后的时间,返回新的 DateTime 实例。

参数:

返回值:

异常:

func addHours(Int64)

public func addHours(n: Int64): DateTime

功能:获取 DateTime 实例 n 小时之后的时间,返回新的 DateTime 实例。

参数:

返回值:

异常:

func addMinutes(Int64)

public func addMinutes(n: Int64): DateTime

功能:获取 DateTime 实例 n 分钟之后的时间,返回新的 DateTime 实例。

参数:

返回值:

异常:

func addMonths(Int64)

public func addMonths(n: Int64): DateTime

功能:获取 DateTime 实例 n 月之后的时间,返回新的 DateTime 实例。

注意:

由于月的间隔不固定,若设 dt 表示 “2020年3月30日”,dt.addMonths(1) 不会返回非法日期“2020年3月31日”。为了尽量返回有效的日期,会偏移到当月最后一天,返回“2020年4月30日”。

参数:

返回值:

异常:

func addNanoseconds(Int64)

public func addNanoseconds(n: Int64): DateTime

功能:获取 DateTime 实例 n 纳秒之后的时间,返回新的 DateTime 实例。

参数:

返回值:

异常:

func addSeconds(Int64)

public func addSeconds(n: Int64): DateTime

功能:获取 DateTime 实例 n 秒之后的时间,返回新的 DateTime 实例。

参数:

返回值:

异常:

func addWeeks(Int64)

public func addWeeks(n: Int64): DateTime

功能:获取 DateTime 实例 n 周之后的时间,返回新的 DateTime 实例。

参数:

返回值:

异常:

功能:获取入参 n 周之后的时间,返回新的 DateTime 实例。

func addYears(Int64)

public func addYears(n: Int64): DateTime

功能:获取 DateTime 实例 n 年之后的时间,返回新的 DateTime 实例。

注意:

由于年的间隔不固定,若设 dt 表示 “2020年2月29日”,dt.addYears(1) 不会返回非法日期“2021年2月29日”。为了尽量返回有效的日期,会偏移到当月最后一天,返回 “2021年2月28日”。

参数:

返回值:

异常:

func compare(DateTime)

public func compare(rhs: DateTime): Ordering

功能:判断一个 DateTime 实例与参数 rhs 的大小关系。如果大于,返回 Ordering.GT;如果等于,返回 Ordering.EQ;如果小于,返回 Ordering.LT。

参数:

返回值:

func hashCode()

public func hashCode(): Int64

功能:获取 DateTime 实例的哈希值。

返回值:

func inLocal()

public func inLocal(): DateTime

功能:获取 DateTime 实例在本地时区的时间。

返回值:

异常:

func inTimeZone(TimeZone)

public func inTimeZone(timeZone: TimeZone): DateTime

功能:获取 DateTime 实例在参数 timeZone 指定时区的时间。

参数:

返回值:

异常:

func inUTC()

public func inUTC(): DateTime

功能:获取 DateTime 实例在 UTC 时区的时间。

返回值:

异常:

func toString()

public func toString(): String

功能:返回一个表示 DateTime 实例的字符串,其格式为 RFC3339date-time 格式,如果时间包含纳秒信息(不为零),会打印出小数秒。

返回值:

func toString(String)

public func toString(format: String): String

功能:返回一个表示 DateTime 实例的字符串,其格式由参数 format 指定。格式说明详见时间字符串格式

参数:

  • format: String - 返回字符串的格式,其格式可为 "yyyy/MM/dd HH:mm:ss OOOO"。

返回值:

异常:

func toString(DateTimeFormat)

public func toString(format: DateTimeFormat): String

功能:返回一个表示 DateTime 实例的字符串,其格式由参数 format 指定。格式说明详见时间字符串格式

参数:

  • format: DateTimeFormat - 时间格式,其格式可为 "yyyy/MM/dd HH:mm:ss OOOO"。

返回值:

异常:

func toUnixTimeStamp()

public func toUnixTimeStamp(): Duration

功能:获取当前实例自 UnixEpoch 的时间间隔。

返回值:

operator func !=(DateTime)

public operator func !=(r: DateTime): Bool

功能:判断当前 DateTime 实例是否不等于 r

若两个 DateTime 不相等,那么它们指向的不是同一 UTC 时间。

参数:

返回值:

  • Bool - truefalse。当前 DateTime 实例不等于 r 时,返回 true;否则,返回 false

operator func +(Duration)

public operator func +(r: Duration): DateTime

功能:实现 DateTime 类型和 Duration 类型加法,即 DateTime + Duration 运算。

参数:

  • r: Duration - 加法的右操作数。

返回值:

异常:

operator func -(DateTime)

public operator func -(r: DateTime): Duration

功能:实现 DateTime 类型之间的减法,即 DateTime - DateTime 运算。

参数:

  • r: DateTime - 减法的右操作数。

返回值:

operator func -(Duration)

public operator func -(r: Duration): DateTime

功能:实现 DateTime 类型和 Duration 类型减法,即 DateTime - Duration 运算。

参数:

  • r: Duration - 减法的右操作数。

返回值:

异常:

operator func <(DateTime)

public operator func <(r: DateTime): Bool

功能:判断当前 DateTime 实例是否早于 r(指向更早的 UTC 时间的 DateTime 更小)。

参数:

返回值:

  • Bool - truefalse。当前 DateTime 实例早于 r 时,返回 true;否则,返回 false

operator func <=(DateTime)

public operator func <=(r: DateTime): Bool

功能:判断当前 DateTime 实例是否早于或等于 r(指向更早的 UTC 时间的 DateTime 更小)。

参数:

返回值:

  • Bool - truefalse。当前 DateTime 实例早于或等于 r 时,返回 true;否则,返回 false

operator func ==(DateTime)

public operator func ==(r: DateTime): Bool

功能:判断当前 DateTime 实例是否等于 r

若两个 DateTime 相等,那么它们指向同一 UTC 时间。

参数:

返回值:

  • Bool - truefalse。当前 DateTime 实例等于 r 时,返回 true;否则,返回 false

operator func >(DateTime)

public operator func >(r: DateTime): Bool

功能:判断当前 DateTime 实例是否晚于 r(指向更晚的 UTC 时间的 DateTime 更大)。

参数:

返回值:

  • Bool - truefalse。当前 DateTime 实例晚于 r 时,返回 true;否则,返回 false

operator func >=(DateTime)

public operator func >=(r: DateTime): Bool

功能:判断当前 DateTime 实例是否晚于或等于 r(指向更晚的 UTC 时间的 DateTime 更大)。

参数:

返回值:

  • Bool - truefalse。当前 DateTime 实例晚于或等于 r 时,返回 true;否则,返回 false

struct MonoTime

public struct MonoTime <: Hashable & Comparable<MonoTime>

功能:MonoTime 表示单调时间,是一个用来衡量经过时间的时间类型,类似于一直运行的秒表,提供了获取当前时间,计算和比较等功能。

  • MonoTime 可表示的范围为 Duration.ZeroDuration.Max,数值表示为 [0, 263)(单位为秒),精度为纳秒。通过 now 方法创建的 MonoTime 总是晚于先使用该方式创建的 MonoTime,常用于性能测试和时间优先的任务队列。

  • 以下为 MonoTimenow 函数获取当前时间使用的系统调用函数:

    系统系统调用函数时钟类型
    Linuxclock_gettimeCLOCK_MONOTONIC
    Windowsclock_gettimeCLOCK_MONOTONIC
    macOSclock_gettimeCLOCK_MONOTONIC

父类型:

static func now()

public static func now(): MonoTime

功能:获取与当前时间对应的 MonoTime

返回值:

func compare(MonoTime)

public func compare(rhs: MonoTime): Ordering

功能:判断一个 MonoTime 实例与参数 rhs 的大小关系。如果大于,返回 Ordering.GT;如果等于,返回 Ordering.EQ;如果小于,返回 Ordering.LT。

参数:

返回值:

func hashCode()

public func hashCode(): Int64

功能:获取当前 MonoTime 实例的哈希值。

返回值:

operator func !=(MonoTime)

public operator func !=(r: MonoTime): Bool

功能:判断当前 MonoTime 实例是否不等于 r

参数:

返回值:

  • Bool - truefalse。当前 MonoTime 实例不等于 r 时,返回 true;否则,返回 false

operator func +(Duration)

public operator func +(r: Duration): MonoTime

功能:实现 MonoTime 类型和 Duration 类型加法,即 MonoTime + Duration 运算。

参数:

返回值:

  • MonoTime - 参数 r 表示时间间隔后的单调时间。

异常:

operator func -(Duration)

public operator func -(r: Duration): MonoTime

功能:实现 MonoTime 类型和 Duration 类型减法,即 MonoTime - Duration 运算。

参数:

返回值:

  • MonoTime - 参数 r 表示时间间隔前的单调时间。

异常:

operator func -(MonoTime)

public operator func -(r: MonoTime): Duration

功能:实现 MonoTime 类型之间的减法,即 MonoTime - MonoTime 运算。

参数:

返回值:

  • Duration - 当前实例距 r 经过的时间间隔。

operator func <(MonoTime)

public operator func <(r: MonoTime): Bool

功能:判断当前 MonoTime 实例是否早于 r

参数:

返回值:

  • Bool - truefalse。当前 MonoTime 实例早于 r 时,返回 true;否则,返回 false

operator func <=(MonoTime)

public operator func <=(r: MonoTime): Bool

功能:判断当前 MonoTime 实例是否早于或等于 r

参数:

返回值:

  • Bool - truefalse。当前 MonoTime 实例早于或等于 r 时,返回 true;否则,返回 false

operator func ==(MonoTime)

public operator func ==(r: MonoTime): Bool

功能:判断当前 MonoTime 实例是否等于 r

参数:

返回值:

  • Bool - truefalse。当前 MonoTime 实例等于 r 时,返回 true;否则,返回 false

operator func >(MonoTime)

public operator func >(r: MonoTime): Bool

功能:判断当前 MonoTime 实例是否晚于 r

参数:

返回值:

  • Bool - truefalse。当前 MonoTime 实例晚于 r 时,返回 true;否则,返回 false

operator func >=(MonoTime)

public operator func >=(r: MonoTime): Bool

功能:判断当前 MonoTime 实例是否晚于或等于 r

参数:

返回值:

  • Bool - truefalse。当前 MonoTime 实例晚于或等于 r 时,返回 true;否则,返回 false