Class `time::Time`

Implements Comparable<Time>, Addable<Time, Time>, Addable<DateTime, DateTime>, Multipliable<Int, Time>, Multipliable<Float, Time>

The Time class represents elapsed time or the time difference between two points in time. Time instances are immutable. Time values can be negative, zero or positive.

There is no upper or lower bound for the values that Time can represent. Time objects always have nanosecond precision, and this is independent of the magnitude of the value.

class Time()

Construct a Time object representing the current clock time (time passed since midnight).

class Time(days as Int, hours as Int, minutes as Int, seconds as Int)

class Time(days as Int, hours as Int, minutes as Int, seconds as Float)

Construct a Time object representing a specific duration. Seconds must be a float or an integer and all other arguments must be integers. None of the values are restricted to any specific range. If they are outside the valid range of values, they are normalized and the excess is moved to the larger units. So if seconds is 64, the actual second value becomes 4 and minutes are incremented by one, etc.

class Time(seconds as Int)

class Time(seconds as Float)

Construct a Time instance from a number of seconds. This is a shorthand for Time(0, 0, 0, seconds).

class Time(string as Str[, format as Str])

Construct a Time object from a string. The format argument specifies the format of the string. If the format is omitted, the accepted formats are "-h:mm:ss.s" and "-d\d h:mm:ss.s".

The format must contain format sequences for some time components (day, hour, minute, second). A format sequence matches a time component in the string. The following list contains all the available format sequences and examples of valid values:

s	seconds (1, 30)
ss	seconds, at least 2 digits (01, 30)
s.s	seconds with an optional fraction (5, 5.0, 5.12, ...)
ss.s	seconds with an optional fraction, at least 2 digits in the integer part (05, 05.0, 05.12, ...)
m	minutes (1, 30)
mm	minutes, at least 2 digits (01, 30)
h	hours (1, 13)
hh	hours, at least 2 digits (01, 30)
d	days (1, 1234)
dd, ddd, ...	days; at least n digits, where n is the number of d's (01, 023, ...)
-	sign of the value (empty or "-")
[am/pm]	specifier for a.m. or p.m. (all h and hh sequences in the same format string will also follow 12-hour clock conventions; "am" and "pm" in the formatting sequence may be replaced with arbitrary strings, and the matched string must contain one of these strings)

Any other characters in the format must be matched by the same character in the string. As an exception, a backslash \ followed by a character c must be matched by c.

Members

The members day, hour, minute and second of Time are all constants. Either all these members are non-negative or all the members are non-positive, depending on the sign of the Time value.

day as Int

Number of days (integer)

hour as Int

Number of hours (integer in the range from -23 to 23, inclusive)

minute as Int

Number of minutes (integer in the range from -59 to 59, inclusive)

second as Float

Number of seconds (float, -60 < seconds < 60)

format(template as Str) as Str

Format the time as a string. The template string defines the format of the result. The following formatting sequences in the template are replaced with formatted Time components (examples within parentheses):

s	seconds as an integer (5)
ss	seconds as an integer, at least 2 digits (05)
s.s, s.ss, ...	seconds as a fraction (5.0, 5.12, ...)
ss.s, ss.ss, ...	seconds as a fraction, at least 2 digits in the integer part (05.0, 05.12, ...)
h	hours (6)
hh	hours, at least 2 digits (06)
m	minutes (4)
mm	minutes, at least 2 digits (04)
d	days (3)
dd, ddd, ...	days, at least n digits (03, 003, ...)
-	sign of the time (empty or "-")
[am/pm]	a.m. or p.m. according 12-hour clock; all h and hh sequences in the same format string will also follow 12-hour clock conventions ("am" and "pm" may be replaced with arbitrary strings, and one of these is substituted in the result string)

Other characters in the template are copied as such to the result. As an exception, a backslash \ followed by a character c is replaced with c.

toSeconds() as Float

Return the total number of seconds represented by a time object as a Float. The return value may be negative.

Note: The return value may be imprecise due to the properties of floating-point numbers. Use toNanoSeconds to get a precise (integer) representation of the total number of seconds.

toNanoSeconds() as Int

Return the total number of nanoseconds represented by a time object as an integer. The return value may be negative.

Operations

time1 + time2 (Time + Time ⇒ Time)
time1 - time2 (Time - Time ⇒ Time): Time objects can be added and subtracted.
-time (-Time ⇒ Time): Negate a time object. The sign of all components is reversed.
time * 3.2 (Time * Float ⇒ Time)
time * 2 (Time * Int ⇒ Time): Time objects support multiplication with a number.
time / 3.2 (Time / Float ⇒ Time)
time / 2 (Time / Int ⇒ Time): Time objects support division by a number.
Str(time) (Str(Time) ⇒ Str): Convert a time to a string of the form "01:02:03.4" or "5d 01:02:03.4" (if day != 0).
Time("01:00:00") < Time("01:00:01") (Time < Time ⇒ Boolean): Times can be compared for equality and order.
Hash(time) (Hash(Time) ⇒ Int): Return the hash value of a Time object.
Float(time) (Float(Time) ⇒ Float): Deprecated (this feature will be removed in a future Alore version). This is equivalent to time.toSeconds().

Examples

This example uses both 12-hour and 24-hour time formats:

var t = Time("2:13 PM", "h:mm [AM/PM]")
Str(t)                           -- "14:13:00.0" (24-hour clock)
t.hour                           -- 14
t.format("h:mm [a.m./p.m.]")     -- "2:13 p.m."
f.format("hh:mm")                -- "14:13"

Class time::Time

Members

Operations

Examples

Class `time::Time`