Structs

struct DateTime

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

Description: Indicates a date-time, which is a time type describing a point of time. It provides functionality such as time zone-based date-time reading, calculation, comparison, and conversion, as well as serialization and deserialization.

  • DateTime is an immutable type that contains date, time, and time zone information. It represents a time range of [-999,999,999-01-01T00:00:00.000000000, 999,999,999-12-31T23:59:59.999999999], which is applicable to any valid time zone.

  • The following lists the system call functions used by the now and nowUTC functions in DateTime to obtain the current time.

    SystemSystem Call FunctionClock Type
    Linuxclock_gettimeCLOCK_REALTIME
    Windowsclock_gettimeCLOCK_REALTIME
    macOSclock_gettimeCLOCK_REALTIME

Parent Type:

static prop UnixEpoch

public static prop UnixEpoch: DateTime

Description: Obtains the Unix epoch, that is, the DateTime instance that indicates 1970-01-01 00:00:00 in the zero time zone.

Type: DateTime

prop dayOfMonth

public prop dayOfMonth: Int64

Description: Obtains the day of the current month in the DateTime instance.

Type: Int64

prop dayOfWeek

public prop dayOfWeek: DayOfWeek

Description: Obtains the day of the current week in the DateTime instance.

Type: DayOfWeek

prop dayOfYear

public prop dayOfYear: Int64

Description: Obtains the day of the current year in the DateTime instance.

Type: Int64

prop date

public prop date: (Int64, Month, Int64)

Description: Obtains the day of the current month and the year and month in the DateTime instance.

Type: (Int64,Month, Int64)

prop hour

public prop hour: Int64

Description: Obtains the hour information in the DateTime instance.

Type: Int64

prop isoWeek

public prop isoWeek: (Int64, Int64)

Description: Obtains the ISO 8601-compliant year and the number of weeks in the year in the DateTime instance.

Type: (Int64, Int64)

prop minute

public prop minute: Int64

Description: Obtains the minute information in the DateTime instance.

Type: Int64

prop month

public prop month: Month

Description: Obtains the month in the DateTime instance.

Type: Month

prop monthValue (deprecated)

public prop monthValue: Int64

Description: Obtains the month represented by a number in the DateTime instance.

Type: Int64

NOTE

This property will be deprecated in future releases.

prop nanosecond

public prop nanosecond: Int64

Description: Obtains the nanosecond information in the DateTime instance.

Type: Int64

prop second

public prop second: Int64

Description: Obtains the second information in the DateTime instance.

Type: Int64

prop year

public prop year: Int64

Description: Obtains the year in the DateTime instance.

Type: Int64

prop time

public prop time: (Int64, Int64, Int64)

Description: Obtain the hour, minute, and second in the DateTime instance.

Type: (Int64,Int64, Int64)

prop zone

public prop zone: TimeZone

Description: Obtains the time zone associated with the DateTime instance.

Type: TimeZone

prop zoneId

public prop zoneId: String

Description: Obtains the time zone ID in the TimeZone instance associated with the DateTime instance.

Type: String

prop zoneOffset

public prop zoneOffset: Duration

Description: Obtains the time offset in the TimeZone instance associated with the DateTime instance.

Type: Duration

static func fromUnixTimeStamp(Duration)

public static func fromUnixTimeStamp(d: Duration): DateTime

Description: Obtains the date-time after the time interval specified by the parameter d since UnixEpoch.

Parameters:

Returns:

Throws:

static func now(TimeZone)

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

Description: Obtains the current time of the time zone specified by the parameter timeZone. The current time obtained using this method is affected by the system time. If timing is not affected by the system time, MonoTime.now() can be used instead.

Parameters:

  • timeZone!: TimeZone: time zone, which is the local time zone by default.

Returns:

  • DateTime: current time of the specified time zone

static func nowUTC()

public static func nowUTC(): DateTime

Description: Obtains the current time of the UTC time zone. The current time obtained using this method is affected by the system time. If timing is not affected by the system time, MonoTime.now() can be used instead.

Returns:

  • DateTime: current time of the UTC time zone

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

Description: Constructs a DateTimeinstance based on the year, month, day, hour, minute, second, nanosecond, and time zone specified by parameters.

Parameters:

  • year!: Int64: year, in the value range of [-999,999,999, 999,999,999]
  • month!: Int64: month, in the value range of [1, 12]
  • dayOfMonth!: Int64: day, in the value range of [1, 31]. The maximum value depends on month, which can be 28, 29, 30, or 31.
  • hour!: Int64: hour, in the value range of [0, 23]
  • minute!: Int64: minute, in the value range of [0, 59]
  • second!: Int64: second, in the value range of [0, 59]
  • nanosecond!: Int64: nanosecond, in the value range of [0, 999,999,999]
  • timeZone!: TimeZone: time zone

Returns:

Throws:

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

Description: Constructs a DateTimeinstance based on the year, month, day, hour, minute, second, nanosecond, and time zone specified by parameters.

Parameters:

  • year!: Int64: year, in the value range of [-999,999,999, 999,999,999]
  • month!: Month: month of the Month type
  • dayOfMonth!: Int64: day, in the value range of [1, 31]. The maximum value depends on month, which can be 28, 29, 30, or 31.
  • hour!: Int64: hour, in the value range of [0, 23]
  • minute!: Int64: minute, in the value range of [0, 59]
  • second!: Int64: second, in the value range of [0, 59]
  • nanosecond!: Int64: nanosecond, in the value range of [0, 999,999,999]
  • timeZone!: TimeZone: time zone

Returns:

Throws:

static func ofEpoch(Int64, Int64)

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

Description: Constructs a DateTimeinstance based on the input parameters second and nanosecond. The input parameter second indicates the second part of the Unix time, and nanosecond indicates the nanosecond part of the Unix time. The Unix time counts from UnixEpoch. The value range of nanosecond cannot exceed [0, 999,999,999]. Otherwise, an exception is thrown.

Parameters:

  • second!: Int64: second part of the Unix time
  • nanosecond!: Int64: nanosecond part of the Unix time. The value range is [0, 999,999,999].

Returns:

Throws:

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

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

Description: Constructs a DateTimeinstance of the UTC time zone based on the year, month, day, hour, minute, second, nanosecond, and time zone specified by parameters.

Parameters:

  • year!: Int64: year, in the value range of [-999,999,999, 999,999,999]
  • month!: Int64: month, in the value range of [1, 12]
  • dayOfMonth!: Int64: day, in the value range of [1, 31]. The maximum value depends on month, which can be 28, 29, 30, or 31.
  • hour!: Int64: hour, in the value range of [0, 23]
  • minute!: Int64: minute, in the value range of [0, 59]
  • second!: Int64: second, in the value range of [0, 59]
  • nanosecond!: Int64: nanosecond, in the value range of [0, 999,999,999]

Returns:

  • DateTime: DateTime instance of the UTC time zone constructed based on specified parameters

Throws:

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

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

Description: Constructs a DateTimeinstance of the UTC time zone based on the year, month, day, hour, minute, second, nanosecond, and time zone specified by parameters.

Parameters:

  • year!: Int64: year, in the value range of [-999,999,999, 999,999,999]
  • month!: Month: month of the Month type
  • dayOfMonth!: Int64: day, in the value range of [1, 31]. The maximum value depends on month, which can be 28, 29, 30, or 31.
  • hour!: Int64: hour, in the value range of [0, 23]
  • minute!: Int64: minute, in the value range of [0, 59]
  • second!: Int64: second, in the value range of [0, 59]
  • nanosecond!: Int64: nanosecond, in the value range of [0, 999,999,999]

Returns:

  • DateTime: DateTime instance of the UTC time zone constructed based on specified parameters

Throws:

static func parse(String)

public static func parse(str: String): DateTime

Description: Parses the parameter str to acquire a time. If the parsing is successful, the DateTime instance is returned.

Parameters:

  • str: String: time string, in the format of date-time in RFC3339. It may contain fractional seconds, for example, "2023-04-10T08:00:00[.123456]+08:00" (content in [] is optional).

Returns:

Throws:

static func parse(String, String)

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

Description: Parses the string str based on the time format specified by format to acquire a time. If the parsing is successful, the DateTime instance is returned.

Parameters:

  • str: String: time string, for example, 2023/04/10 08:00:00 +08:00
  • format: String: time string format, for example, yyyy/MM/dd HH:mm:ss OOOO. For details about the formats, see Time String Formats.

Returns:

  • DateTime: DateTime instance parsed from the parameter str based on time format specified by the parameter format

Throws:

static func parse(String, DateTimeFormat) (deprecated)

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

Description: Parses the string str based on the time format specified by format to acquire a time. If the parsing is successful, the DateTime instance is returned. For details about the parsing specifications, see "Parsing time from a string."

NOTE

This function will be deprecated in future releases and parse(String, String) will be used instead.

Parameters:

  • str: String: time string, for example, 2023/04/10 08:00:00 +08:00
  • format: DateTimeFormat: time format, for example, a time format corresponding to yyyy/MM/dd HH:mm:ss OOOO. For details about the formats, see Time String Formats.

Returns:

  • DateTime: DateTime instance parsed from the parameter str based on time format specified by the parameter format

Throws:

static func tryParse(String)

public static func tryParse(str: String): Option<DateTime>

Description: Parses the time from the str parameter. If the parsing is successful, the option<DateTime> instance is returned.

Parameters:

  • str: String: time string. The format is the date-time format specified in RFC3339. The value can contain fractional seconds, for example, 2023-04-10T08:00:00[.123456]+08:00 (the content in [] is optional).

Returns:

func addDays(Int64)

public func addDays(n: Int64): DateTime

Description: Obtains the time n days after the DateTime instance, and returns a new DateTime instance.

Parameters:

Returns:

Throws:

func addHours(Int64)

public func addHours(n: Int64): DateTime

Description: Obtains the time n hours after the DateTime instance, and returns a new DateTime instance.

Parameters:

Returns:

Throws:

func addMinutes(Int64)

public func addMinutes(n: Int64): DateTime

Description: Obtains the time n minutes after the DateTime instance, and returns a new DateTime instance.

Parameters:

Returns:

Throws:

func addMonths(Int64)

public func addMonths(n: Int64): DateTime

Description: Obtains the time n months after the DateTime instance, and returns a new DateTime instance.

NOTE

The interval between months is not fixed. If dt is set to March 30, 2020, dt.addMonths(1) does not return an invalid date March 31, 2020. To ensure that a valid date is returned, the last day of the current month is used, and April 30, 2020 is returned.

Parameters:

Returns:

Throws:

func addNanoseconds(Int64)

public func addNanoseconds(n: Int64): DateTime

Description: Obtains the time n nanoseconds after the DateTime instance, and returns a new DateTime instance.

Parameters:

Returns:

Throws:

func addSeconds(Int64)

public func addSeconds(n: Int64): DateTime

Description: Obtains the time n seconds after the DateTime instance, and returns a new DateTime instance.

Parameters:

Returns:

Throws:

func addWeeks(Int64)

public func addWeeks(n: Int64): DateTime

Description: Obtains the time n weeks after the DateTime instance, and returns a new DateTime instance.

Parameters:

Returns:

Throws:

Description: Obtains the time n weeks later, and returns a new DateTime instance.

func addYears(Int64)

public func addYears(n: Int64): DateTime

Description: Obtains the time n years after the DateTime instance, and returns a new DateTime instance.

NOTE

The interval between years is not fixed. If dt is set to February 29, 2020, dt.addYears(1) does not return an invalid date February 29, 2021. To ensure that a valid date is returned, the last day of the current month is used, and February 28, 2021 is returned.

Parameters:

Returns:

Throws:

func compare(DateTime)

public func compare(rhs: DateTime): Ordering

Description: Compares the value of a DateTime instance with that of the parameter rhs. If the value of the instance is greater, Ordering.GT is returned. If they are equal, Ordering.EQ is returned. If the value of the instance is smaller, Ordering.LT is returned.

Parameters:

Returns:

func hashCode()

public func hashCode(): Int64

Description: Obtains the hash value of a DateTime instance.

Returns:

func inLocal()

public func inLocal(): DateTime

Description: Obtains the time of the DateTime instance in the local time zone.

Returns:

Throws:

func inTimeZone(TimeZone)

public func inTimeZone(timeZone: TimeZone): DateTime

Description: Obtains the time of the DateTime instance in the time zone specified by the parameter timeZone.

Parameters:

Returns:

  • DateTime: time of the DateTime instance in the time zone specified by the parameter timezone

Throws:

func inUTC()

public func inUTC(): DateTime

Description: Obtains the time of the DateTime instance in the UTC time zone.

Returns:

Throws:

func toString()

public func toString(): String

Description: Returns a string indicating a DateTime instance. The string adopts the format of date-time in RFC3339. If the time contains nanosecond information (not zero), fractional seconds are returned.

Returns:

func format(String)

public func format(fmt: String): String

Description: Returns a string indicating a DateTime instance. The format is specified by the parameter fmt. For details about the formats, see Time String Formats.

Parameters:

  • fmt: String: format of the returned string, for example, yyyy/MM/dd HH:mm:ss OOOO

Returns:

  • String: string of the DateTime instance in the format specified by fmt. If the string cannot be parsed, the format specified by fmt is returned.

Throws:

func toString(DateTimeFormat) (deprecated)

public func toString(format: DateTimeFormat): String

Description: Returns a string indicating a DateTime instance. The format is specified by the parameter format. For details about the formats, see Time String Formats.

NOTE

This function will be deprecated in future releases.

Parameters:

  • format: DateTimeFormat: time format. The format can be yyyy/MM/dd HH:mm:ss OOOO.

Returns:

  • String: string of the DateTime instance in the format specified by format

Throws:

func toUnixTimeStamp()

public func toUnixTimeStamp(): Duration

Description: Obtains the time interval between the current instance and UnixEpoch.

Returns:

operator func !=(DateTime)

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

Description: Checks whether the current DateTime instance is not equal to r.

If two DateTime instances are not equal, they point to different UTC time.

Parameters:

Returns:

  • Bool: true or false. If the current DateTime instance is not equal to r, true is returned; otherwise, false is returned.

operator func +(Duration)

public operator func +(r: Duration): DateTime

Description: Implements an addition of the DateTime instance and the Duration instance, that is, DateTime + Duration.

Parameters:

  • r: Duration: right operand of the addition

Returns:

Throws:

operator func -(DateTime)

public operator func -(r: DateTime): Duration

Description: Implements a subtraction between DateTime types, that is, DateTime - DateTime.

Parameters:

  • r: DateTime: right operand of the subtraction

Returns:

operator func -(Duration)

public operator func -(r: Duration): DateTime

Description: Implements a subtraction between the DateTime type and the Duration type, that is, DateTime - Duration.

Parameters:

  • r: Duration: right operand of the subtraction

Returns:

Throws:

operator func <(DateTime)

public operator func <(r: DateTime): Bool

Description: Checks whether the current DateTime instance is earlier than r (the DateTime instance pointing to an earlier UTC time is smaller).

Parameters:

Returns:

  • Bool: true or false. If the current DateTime instance is earlier than r, true is returned; otherwise, false is returned.

operator func <=(DateTime)

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

Description: Checks whether the current DateTime instance is earlier than or equal to r (the DateTime instance pointing to an earlier UTC time is smaller).

Parameters:

Returns:

  • Bool: true or false. If the current DateTime instance is earlier than or equal to r, true is returned; otherwise, false is returned.

operator func ==(DateTime)

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

Description: Checks whether the current DateTime instance is equal to r.

If two DateTime instances are equal, they point to the same UTC time.

Parameters:

Returns:

  • Bool: true or false. If the current DateTime instance is equal to r, true is returned; otherwise, false is returned.

operator func >(DateTime)

public operator func >(r: DateTime): Bool

Description: Checks whether the current DateTime instance is later than r (the DateTime instance pointing to a later UTC time is greater).

Parameters:

Returns:

  • Bool: true or false. If the current DateTime instance is later than r, true is returned; otherwise, false is returned.

operator func >=(DateTime)

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

Description: Checks whether the current DateTime instance is later than or equal to r (the DateTime instance pointing to a later UTC time is greater).

Parameters:

Returns:

  • Bool: true or false. If the current DateTime instance is later than or equal to r, true is returned; otherwise, false is returned.

struct MonoTime

public struct MonoTime <: Hashable & Comparable<MonoTime>

Description: Indicates monotonic time, which is a time type used to measure the elapsed time. Similar to an ever-running stopwatch, it provides functionality such as obtaining current time, calculation, and comparison.

  • MonoTime specifies a range from Duration.Zero to Duration.Max, numerically, [0, 263) in seconds. It is accurate to nanoseconds. MonoTime created using the now method is always later than MonoTime created earlier using this method. It is usually used for performance tests and time-prioritized task queues.

  • The following lists the system call functions used by the now function in MonoTime to obtain the current time.

    SystemSystem Call FunctionClock Type
    Linuxclock_gettimeCLOCK_MONOTONIC
    Windowsclock_gettimeCLOCK_MONOTONIC
    macOSclock_gettimeCLOCK_MONOTONIC

Parent Type:

static func now()

public static func now(): MonoTime

Description: Obtains MonoTime corresponding to the current time.

Returns:

func compare(MonoTime)

public func compare(rhs: MonoTime): Ordering

Description: Compares the value of a MonoTime instance with that of the parameter rhs. If the value of the instance is greater, Ordering.GT is returned. If they are equal, Ordering.EQ is returned. If the value of the instance is smaller, Ordering.LT is returned.

Parameters:

Returns:

func hashCode()

public func hashCode(): Int64

Description: Obtains the hash value of the current MonoTime instance.

Returns:

operator func !=(MonoTime)

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

Description: Checks whether the current MonoTime instance is not equal to r.

Parameters:

Returns:

  • Bool: true or false. If the current MonoTime instance is not equal to r, true is returned; otherwise, false is returned.

operator func +(Duration)

public operator func +(r: Duration): MonoTime

Description: Implements an addition of the MonoTime instance and the Duration instance, that is, MonoTime + Duration.

Parameters:

Returns:

  • MonoTime: monotonic time after the time interval specified by the parameter r

Throws:

  • ArithmeticException: If the result exceeds the monotonic time range, this exception is thrown.

operator func -(Duration)

public operator func -(r: Duration): MonoTime

Description: Implements a subtraction between the MonoTime instance and the Duration instance, that is, MonoTime - Duration.

Parameters:

Returns:

  • MonoTime: monotonic time before the time interval specified by the parameter r

Throws:

  • ArithmeticException: If the result exceeds the monotonic time range, this exception is thrown.

operator func -(MonoTime)

public operator func -(r: MonoTime): Duration

Description: Implements a subtraction between MonoTime instances, that is, MonoTime - MonoTime.

Parameters:

Returns:

  • Duration: time elapsed from the current instance to r

operator func <(MonoTime)

public operator func <(r: MonoTime): Bool

Description: Checks whether the current MonoTime instance is earlier than r.

Parameters:

Returns:

  • Bool: true or false. If the current MonoTime instance is earlier than r, true is returned; otherwise, false is returned.

operator func <=(MonoTime)

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

Description: Checks whether the current MonoTime instance is earlier than or equal to r.

Parameters:

Returns:

  • Bool: true or false. If the current MonoTime instance is earlier than or equal to r, true is returned; otherwise, false is returned.

operator func ==(MonoTime)

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

Description: Checks whether the current MonoTime instance is equal to r.

Parameters:

Returns:

  • Bool: true or false. If the current MonoTime instance is equal to r, true is returned; otherwise, false is returned.

operator func >(MonoTime)

public operator func >(r: MonoTime): Bool

Description: Checks whether the current MonoTime instance is later than r.

Parameters:

Returns:

  • Bool: true or false. If the current MonoTime instance is later than r, true is returned; otherwise, false is returned.

operator func >=(MonoTime)

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

Description: Checks whether the current MonoTime instance is later than or equal to r.

Parameters:

Returns:

  • Bool: true or false. If the current MonoTime instance is later than or equal to r, true is returned; otherwise, false is returned.