124 lines
4.2 KiB
Markdown
124 lines
4.2 KiB
Markdown
# Lyng time functions
|
|
|
|
Lyng date and time support requires importing `lyng.time` packages. Lyng uses simple yet modern time object models:
|
|
|
|
- `Instant` class for time stamps with platform-dependent resolution
|
|
- `Duration` to represent amount of time not depending on the calendar, e.g. in absolute units (milliseconds, seconds, hours, days)
|
|
|
|
## Time instant: `Instant`
|
|
|
|
Represent some moment of time not depending on the calendar (calendar for example may b e changed, daylight saving time can be for example introduced or dropped). It is similar to `TIMESTAMP` in SQL or `Instant` in Kotlin. Some moment of time; not the calendar date.
|
|
|
|
Instant is comparable to other Instant. Subtracting instants produce `Duration`, period in time that is not dependent on the calendar, e.g. absolute time period.
|
|
|
|
It is possible to add or subtract `Duration` to and from `Instant`, that gives another `Instant`.
|
|
|
|
Instants are converted to and from `Real` number of seconds before or after Unix Epoch, 01.01.1970. Constructor with single number parameter constructs from such number of seconds,
|
|
and any instance provide `.epochSeconds` member:
|
|
|
|
import lyng.time
|
|
|
|
// default constructor returns time now:
|
|
val t1 = Instant()
|
|
val t2 = Instant()
|
|
assert( t2 - t1 < 1.millisecond )
|
|
assert( t2.epochSeconds - t1.epochSeconds < 0.001 )
|
|
>>> void
|
|
|
|
## Constructing
|
|
|
|
import lyng.time
|
|
|
|
// empty constructor gives current time instant using system clock:
|
|
val now = Instant()
|
|
|
|
// constructor with Instant instance makes a copy:
|
|
assertEquals( now, Instant(now) )
|
|
|
|
// constructing from a number is trated as seconds since unix epoch:
|
|
val copyOfNow = Instant( now.epochSeconds )
|
|
|
|
// note that instant resolution is higher that Real can hold
|
|
// so reconstructed from real slightly differs:
|
|
assert( abs( (copyOfNow - now).milliseconds ) < 0.01 )
|
|
>>> void
|
|
|
|
The resolution of system clock could be more precise and double precision real number of `Real`, keep it in mind.
|
|
|
|
## Comparing and calculating periods
|
|
|
|
import lyng.time
|
|
|
|
val now = Instant()
|
|
|
|
// you cam add or subtract periods, and compare
|
|
assert( now - 5.minutes < now )
|
|
val oneHourAgo = now - 1.hour
|
|
assertEquals( now, oneHourAgo + 1.hour)
|
|
|
|
>>> void
|
|
|
|
## Instant members
|
|
|
|
| member | description |
|
|
|-----------------------|---------------------------------------------------------|
|
|
| epochSeconds: Real | positive or negative offset in seconds since Unix epoch |
|
|
| isDistantFuture: Bool | true if it `Instant.distantFuture` |
|
|
| isDistantPast: Bool | true if it `Instant.distantPast` |
|
|
|
|
## Class members
|
|
|
|
| member | description |
|
|
|--------------------------------|---------------------------------------------------------|
|
|
| Instant.distantPast: Instant | most distant instant in past |
|
|
| Instant.distantFuture: Instant | most distant instant in future |
|
|
|
|
# `Duraion` class
|
|
|
|
Represent absolute time distance between two `Instant`.
|
|
|
|
import lyng.time
|
|
val t1 = Instant()
|
|
|
|
// yes we can delay to period, and it is not blocking. is suspends!
|
|
delay(1.millisecond)
|
|
|
|
val t2 = Instant()
|
|
// be suspend, so actual time may vary:
|
|
assert( t2 - t1 >= 1.millisecond)
|
|
assert( t2 - t1 < 100.millisecond)
|
|
>>> void
|
|
|
|
Duration can be converted from numbers, like `5.minutes` and so on. Extensions are created for
|
|
`Int` and `Real`, so for n as Real or Int it is possible to create durations::
|
|
|
|
- `n.millisecond`, `n.milliseconds`
|
|
- `n.second`, `n.seconds`
|
|
- `n.minute`, `n.minutes`
|
|
- `n.hour`, `n.hours`
|
|
- `n.day`, `n.days`
|
|
|
|
The bigger time units like months or years are calendar-dependent and can't be used with `Duration`.
|
|
|
|
Each duration instance can be converted to number of any of these time units, as `Real` number, if `d` is a `Duration` instance:
|
|
|
|
- `d.milliseconds`
|
|
- `d.seconds`
|
|
- `d.minutes`
|
|
- `d.hours`
|
|
- `d.days`
|
|
|
|
for example
|
|
|
|
import lyng.time
|
|
assertEquals( 60, 1.minute.seconds )
|
|
>>> void
|
|
|
|
# Utility functions
|
|
|
|
## delay(duration: Duration)
|
|
|
|
Suspends current coroutine for at least the specified duration.
|
|
|
|
|