Note: This website is archived. For up-to-date information about D projects and development, please visit wiki.dlang.org.

Time Library

This library contains some functions for timing purposes, as well as for getting the system time.

Members

  1. time.microTime()
  2. `time.dateString(format: string = "G", time: null|table = null [, …
  3. time.dateTime([useGMT: bool = false][, output: table]])
  4. time.compare(t1: table, t2: table):int
  5. time.culture([new: string])
  6. time.timestamp()
  7. time.timex(f: function, vararg)
  8. time.sleep(duration: float)
  9. class Timer
    1. start()
    2. stop()
    3. seconds(), millisecs(), and microsecs()

time.microTime()

Gets a microsecond-precise timing value. The value itself is not particularly useful, but you can get the value, do some stuff, then get a second value and find the difference to time a piece of code fairly accurately.

time.dateString(format: string = "G", time: null|table = null [, culture: string])

Format a time into a localized string.

format indicates the format of the output. It can be one of the following string values (examples are for the "en-US" culture for Friday November 2nd 2007, 8:01:44 AM):

  • "d": Short date. Example: "11/2/2007"
  • "D": Long date. Example: "Friday, November 02, 2007"
  • "t": Short time. Example: "8:01 AM"
  • "T": Long time. Example: "8:01:44 AM"
  • "g": Short general form. Example: "11/2/2007 8:01 AM"
  • "G": Long general form (default). Example: "11/2/2007 8:01:44 AM"
  • "M": Month form. Example: "November 02"
  • "R": RFC1123 form. Example: "Fri, 02 Nov 2007 8:01:44 GMT"
  • "s": Sortable form. Example: "2007-11-02T08:01:44"
  • "Y": Year form. Example: "November, 2007"

The default is "G", which shows the date and time.

time defaults to 'null', which makes it format the current time. If you use the "R" format and leave out the time, it uses GMT; otherwise it uses the current local time. If you do pass a time to this parameter, you should pass a table. The table must have 'year', 'month', and 'day' fields, all integers. It can optionally have 'hour' (interpreted as a 24-hour hour, so 8 PM is hour 20), 'min', and 'sec' fields, also all integers. If you want the time, you must provide all three fields, or else they will be ignored.

culture is optional. It should be a string in the "<language>-<REGION>" form used by Tango's underlying Culture class (examples: "en-US" for English, US. "ja-JP" for Japanese. "fr-FR" for French in France.). If you don't pass a culture, the date will be formatted according to the current culture's rules (usually determined automatically by Tango, but you can change it with time.culture()).

Because all parameters are optional, calling time.dateString() will yield a reasonable string representation of the current date and time formatted according to the current culture's rules.

time.dateTime([useGMT: bool = false][, output: table]])

Puts the current date and time into a table. The first parameter is optional and is a boolean indicating whether to get GMT (if you pass true), or if it should get the current local time (the default).

If you pass nothing for the output parameter, the date and time are placed into a new table and returned. If you pass something for the output parameter, it must be a table. It will have its 'year', 'month', 'day', 'hour', 'min', and 'sec' fields set to the current time, using opIndexAssign metamethods if necessary. The return value will then become the table that you passed in. The option to pass in a table to take the output is to make it faster if you need to keep getting the time over and over, instead of requiring a memory allocation each time.

time.compare(t1: table, t2: table):int

Compares two time tables and returns a three-way comparison value: less than 0 if t1 comes before t2, greater than 0 if t1 comes after t2, or 0 if t1 and t2 are the same time.

time.culture([new: string])

If called without parameters, returns the current culture as a string in the "<language>-<REGION>" format. If called with a parameter, it should be a string in the same format indicating the new culture to switch to. In that case, the old culture is returned. This affects, for example, how dates are formatted with the time.dateString() function.

time.timestamp()

Returns the number of seconds, GMT, since the Unix epoch (12:00 AM, January 1, 1970). Let's not think about the Y2038 bug right now.

time.timex(f: function, vararg)

Time a piece of code. This runs the function f and returns the number of seconds, as a float, that it took to run it. If you pass any extra arguments to this function, they are passed as arguments to f. f is always called with a null this.

time.sleep(duration: float)

Causes execution of this OS thread to pause for somewhere around duration seconds. Since it's a float, you can specify sub-second durations with fractional values.

class Timer

A class that's useful for measuring the performance of code. You can think of it as a stopwatch of sorts. Note that while it's precise, it's not good for timing very long durations.

start()

Clears any previous time and starts the timer.

stop()

Stops the timer. After calling this, you can call the following three methods to get how long the interval was.

seconds(), millisecs(), and microsecs()

Returns the length of the duration between the previous calls to start() and stop() in seconds, milliseconds, or microseconds, as a float. Calling these before calling stop() won't get you anything useful.