module time

This module covers two broad use cases: timing how long something takes, and getting the real (clock) time. These two cases are treated separately as different OSes offer differing levels of resolution and accuracy depending on how you want to deal with time.

This module doesn't go into complex things like dealing with timezones, calendars other than Gregorian, complex international time and date formatting etc. These things would be much better dealt with through an internationalization library.

global function microTime()

Returns:

an integer which is a microseond-accurate count of some kind. The values returned by this function can be used to accurately measure how long something takes, like so:

local start = time.microTime()
doSomethingThatTakesAWhile()
local end = time.microTime()
writefln("Took {} milliseconds", (end - start) / 1000.0)

The times returned by this function are not necessarily synchronized to any external time source. That is, don't assume the values returned mean something like "this many seconds since the computer turned on". You should only use values from this function to time things like shown above.

See:

Timer for a simple class that wraps this in a simpler interface.

global function timex(f)

Given any callable value f, calls f and measures how long it takes to complete.

Returns:

an integer representing the elapsed time in microseconds.

global function clockTime()

Returns:

an integer which is a count of the number of microseconds since the Unix epoch (1 Jan 1970). Important: just because this function returns microseconds does not mean it is actually accurate to the microsecond!

Since this time is relative to an external reference, it's good for things like timestamps or displaying the time to the user. These sorts of times rarely need true microsecond accuracy anyway.

To convert a raw clock time into separate date and time components (month, day, hours, minutes etc.) see timeToTableLocal and timeToTableUTC.

global function timeToTableUTC(time: int = null, ret: table = null)

Converts a clock time (such as returned from clockTime) into a table which holds the the date and time according to the Gregorian calendar. The time components given will be in UTC time. For local time, see timeToTableLocal.

Params:
time
is the time to convert. If you pass nothing or null for this parameter, the current clock time will be used instead.
ret
is an optional result table. If you pass a table for this parameter, the time components will be inserted into this table. Otherwise, a new table object will be allocated and returned.

Returns:

a table (or ret if it was passed) containing the following fields:

"year": the year.
"month": the month, 1-12.
"day": the day, 1-31.
"hour": the hour, 0-23.
"min": the minute, 0-59.
"sec": the second, 0-60. Yes, 60, because of leap seconds.
"msec": the milliseconds, 0-999.

global function timeToTableLocal(time: int = null, ret: table = null)

Just like timeToTableUTC, except the fields in the returned table will be calculated according to the local timezone instead of UTC.

global function timeFromTableUTC(tab: table)

The inverse of timeToTableUTC, converts a table with the appropriate fields into a integer clock time value. The time components of the table are interpreted as being in UTC.

Params:
tab
should contain the date and time to be converted, in a similar format as returned from timeToTableUTC. The table must have integer fields "year", "month", and "day". The other fields are optional, but if you give one of "hour", "min", or "sec", you must give them all.
These are the valid sets of fields tab may have, and how they are interpreted:
Just "year", "month", and "day": interpreted as 00:00:00.000 on the given date.
The above, plus "hour", "min", and "sec": interpreted as HH:MM:SS.000 on the given date.
The above, plus "msec": the full, millisecond-accurate time and date.

Returns:

an integer of the same kind returned from clockTime.

Throws:
ValueError
if tab is invalid in any way.

global function timeFromTableLocal(tab: table)

The inverse of timeToTableLocal. This works just like timeFromTableUTC except it interprets the time components of tab as local time instead of UTC.

class Timer

A small helper class which acts like a stopwatch. You can start it, and it will count time up from that point. When you stop it, it will add the elapsed time between the start and stop calls to its accumulated time. You can then start and stop it again as many times as you want.

This wraps the microTime function so it gives microsecond-precise timings.

Examples:

local t = time.Timer()
t.start()
somethingThatTakes100Microseconds()
t.stop()
writeln(t.time()) // prints 100
t.start()
somethingThatTakes300Microseconds()
t.stop()
writeln(t.time()) // prints 400
t.reset()
writeln(t.time()) // prints 0

function Timer.start()

Starts the timer, or if it's already running, does nothing.

function Timer.stop()

Stops the timer, or if it's not running, does nothing.

function Timer.reset()

Stops the timer and resets its accumulated time to 0.

function Timer.time()

Returns:

the total time elapsed on this timer. If this timer is running, returns the accumulated time plus any time since the last call to start. If this timer is stopped, just returns the total accumulated time.

HTML and JavaScript source derived from

by Victor Nakoryakov; Page generated on 15 Nov 2014 10:28:14

time	is the time to convert. If you pass nothing or null for this parameter, the current clock time will be used instead.
ret	is an optional result table. If you pass a table for this parameter, the time components will be inserted into this table. Otherwise, a new table object will be allocated and returned.