Time

Type-safe wrappers to distinguish durations (an amount of time) from instants (a point in time), and the valid ways to reason about those types.

Example usage:

constant myGoldMine = createGoldMine()
var nextIncomeTime = 30..secondsFromNow()
var incomeMessage = CreateTextTag()..setPos(myGoldMine.getPos3Real())
init
	doPeriodically(ANIMATION_PERIOD) ->
		if nextIncomeTime.durationUntil().lessThan(0..seconds())
			myGoldMine.getOwner().addGold(100)
			nextIncomeTime += 30..seconds()

		incomeMessage..setText("Next income in " + nextIncomeTime.durationUntil().displayVerbose(), 10.)

Details:

• Durations and instants are directly related, but can’t be used interchangeably.
  • Example: it doesn’t make sense to set a timer for “tomorrow” seconds.
• Sometimes durations and instants can be combined to produce a new value.
  • Example: “Now” plus “30 seconds” gives you an instant 30 seconds from now.
• Not every combination of instants and durations makes sense.
  • Example: “30 seconds” plus “30 seconds” is 60 seconds, but “Now” plus “Now” doesn’t make sense.

This library helps you write safe code by making it possible to add instant + duration, subtract instant - instant, but fails to compile the addition of instant + instant.

Source on GitHub

Tuples

instant

public tuple instant(real timestamp_seconds)

An instant in time. Use instantNow() to produce an instant from the current game time.

duration

public tuple duration(real seconds)

A duration of time. Use constructors like 6..seconds() or 15..minutes()` for convenience.

Functions

instantNow

public function instantNow() returns instant

Instant constructor. Uses the elapsed game time.

instantToIndex

public function instantToIndex(instant inst) returns int

instantFromIndex

public function instantFromIndex(int index) returns instant

durationToIndex

public function durationToIndex(duration dur) returns int

durationFromIndex

public function durationFromIndex(int index) returns duration

Extension Functions

real.seconds

public function real.seconds() returns duration

Duration constructor.

real.minutes

public function real.minutes() returns duration

Duration constructor.

real.hours

public function real.hours() returns duration

Duration constructor.

int.seconds

public function int.seconds() returns duration

Duration constructor.

int.minutes

public function int.minutes() returns duration

Duration constructor.

int.hours

public function int.hours() returns duration

Duration constructor.

real.secondsAgo

public function real.secondsAgo() returns instant

Instant constructor.

real.minutesAgo

public function real.minutesAgo() returns instant

Instant constructor.

real.hoursAgo

public function real.hoursAgo() returns instant

Instant constructor.

int.secondsAgo

public function int.secondsAgo() returns instant

Instant constructor.

int.minutesAgo

public function int.minutesAgo() returns instant

Instant constructor.

int.hoursAgo

public function int.hoursAgo() returns instant

Instant constructor.

duration.ago

public function duration.ago() returns instant

Instant constructor.

duration.fromNow

public function duration.fromNow() returns instant

Instant constructor.

real.secondsFromNow

public function real.secondsFromNow() returns instant

Instant constructor.

real.minutesFromNow

public function real.minutesFromNow() returns instant

Instant constructor.

real.hoursFromNow

public function real.hoursFromNow() returns instant

Instant constructor.

int.secondsFromNow

public function int.secondsFromNow() returns instant

Instant constructor.

int.minutesFromNow

public function int.minutesFromNow() returns instant

Instant constructor.

int.hoursFromNow

public function int.hoursFromNow() returns instant

Instant constructor.

instant.op_plus

public function instant.op_plus(duration dur) returns instant

Compute an instant plus a duration. (Now plus 5 minutes = an instant 5 minutes in the future).

instant.op_minus

public function instant.op_minus(duration dur) returns instant

Compute an instant minus a duration. (Now minus 5 minutes = an instant 5 minutes in the past).

instant.op_minus

public function instant.op_minus(instant other) returns duration

Compute an instant minus an instant. (Now minus 5 minutes ago = 5 minutes).

duration.op_plus

public function duration.op_plus(duration other) returns duration

Compute a duration plus a duration. (5 minutes plus 5 minutes = 10 minutes).

duration.op_minus

public function duration.op_minus(duration other) returns duration

Compute a duration minus a duration. (5 minutes minus 2 minutes = 3 minutes).

duration.op_plus

public function duration.op_plus(instant when) returns instant

Compute a duration plus an instant. (5 minutes plus now = 5 minutes in the future).

instant.durationSince

public function instant.durationSince() returns duration

Provides duration since an instant. Equivalent to Now - instant.

instant.durationUntil

public function instant.durationUntil() returns duration

Provides duration until an instant. Convenience for the negative of durationSince.

instant.isOlderThan

public function instant.isOlderThan(instant other) returns bool

Instant > instant ?

instant.isNewerThan

public function instant.isNewerThan(instant other) returns bool

Instant < instant ?

duration.greaterThan

public function duration.greaterThan(duration other) returns bool

Duration > duration ?

duration.lessThan

public function duration.lessThan(duration other) returns bool

Duration < duration ?

instant.isInTheFuture

public function instant.isInTheFuture() returns bool

Convenience for checking if an instant comes after instantNow.

instant.isInThePast

public function instant.isInThePast() returns bool

Convenience for checking if an instant comes before instantNow.

duration.displayVerbose

public function duration.displayVerbose() returns string

Tranform a duration to a verbose string. Example:

61..seconds().displayVerbose()

"1 minutes, and 1 seconds"

duration.display

public function duration.display(string prefix) returns string

Tranform a duration to a short string. Example:

61..minutes().display(“T-“)

"T-1H1M0S"

duration.display

public function duration.display() returns string

ISO-8601 compatible duration representation. Example:

61..minutes().display()

"PT1H1M0S"

instant.displayVerbose

public function instant.displayVerbose(string suffix) returns string

Transform an instant to a verbose string. Example: instantNow().displayVerbose(“ passed before the zombies killed you”)

"5 minutes, and 0 seconds passed before the zombies killed you"

instant.displayVerbose

public function instant.displayVerbose() returns string

Transform an instant to a verbose string. Example: “Time elapsed: “ + instantNow().displayVerbose()

"Time elapsed: 5 minutes, and 0 seconds game time"