`time::Time` class

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.

class Time()

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

class Time([[[days,] hours,] minutes,] seconds)

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(string[, format])

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

Number of days (integer)

hour

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

minute

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

second

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

format(template)

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.

Operations

Float(time): Return the total number of seconds represented by a time object as a Float.
time1 + time2
time1 - time2: Time objects can be added and subtracted.
-time: Negate a time object. The sign of all components is reversed.
time * 3.2
time / 2: Time objects support multiplication with and division by a number.
Str(time): 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"): Times can be compared for equality and order.
Hash(time): Return the hash value of a Time object.

Examples

This example uses both 12-hour and 24-hour clock:

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"

time::Time class

Members

Operations

Examples

`time::Time` class