@supertypes
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()
@desc Construct a Time object representing the current clock time
(time passed since midnight).
@end
@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)
@desc 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.
@end
@class Time(seconds as Int)
@class Time(seconds as Float)
@desc Construct a Time instance from a number of seconds. This is
a shorthand for Time(0, 0, 0, seconds).
@end
@class Time(string as Str[, format as Str])
@desc 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.
@end
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.
@var day as Int
@desc Number of days (integer)
@end
@var hour as Int
@desc Number of hours (integer in the range from -23 to 23, inclusive)
@end
@var minute as Int
@desc Number of minutes (integer in the range from -59 to 59, inclusive)
@end
@var second as Float
@desc Number of seconds (float, -60 < seconds < 60)
@end
@fun format(template as Str) as Str
@desc
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.
@end
@fun toSeconds() as Float
@desc 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.
@end
@end
@fun toNanoSeconds() as Int
@desc Return the total number of nanoseconds represented by a time object
as an integer. The return value may be negative.
@end
Operations
@op time1 + time2 @optype{Time + Time -> Time}
@op time1 - time2 @optype{Time - Time -> Time}
@desc Time objects can be added and subtracted.
@end
@op -time @optype{-Time -> Time}
@desc Negate a time object. The sign of all components is reversed.
@end
@op time * 3.2 @optype{Time * Float -> Time}
@op time * 2 @optype{Time * Int -> Time}
@desc Time objects support multiplication with a number.
@end
@op time / 3.2 @optype{Time / Float -> Time}
@op time / 2 @optype{Time / Int -> Time}
@desc Time objects support division by a number.
@end
@op Str(time) @optype{Str(Time) -> Str}
@desc Convert a time to a string of the
form "01:02:03.4" or "5d 01:02:03.4" (if day != 0).
@end
@op Time("01:00:00") < Time("01:00:01") @optype{Time < Time -> Boolean}
@desc Times can be compared for equality and order.
@end
@op Hash(time) @optype{Hash(Time) -> Int}
@desc Return the hash value of a Time object.
@end
@op Float(time) @optype{Float(Time) -> Float}
@desc @deprecated
This is equivalent to time.toSeconds().
@end
Examples
This example uses both 12-hour and 24-hour time formats:
@example
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"
@end