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

OS Library

This library contains some OS-dependent functionality.

os.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. Because the result is a signed 32-bit int, this counter will wrap around after about 71 minutes, and furthermore, if the length of time is longer than about half of that (35.5 minutes), you'll end up with negative differences, so you can't use this to time long intervals.

os.system([string])

Execute the command 'string' as if you typed it into a shell in the current working directory. Returns the status of the command. If called without arguments, returns a boolean indicating whether a command processor is available on this system.

os.getEnv([string])

If called with a string, gets the value of an environment variable from the process's execution environment. If no variable of that name exists, returns 'null'. If called without parameters, gets a table representing the execution environment, where keys are names and values are the variables' values.

os.dateString(format = "G", time = null [, culture])

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 os.culture()).

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

os.dateTime([useGMT = false], [output]])

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 heap allocation each time.

os.culture([new])

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 os.dateString() function.

class PerfCounter

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.