core.time

Module containing core time functionality, such as Duration (which represents a duration of time).

Various functions take a string (or strings) to represent a unit of time (e.g. ). The valid strings to use with such functions are "years", "months", "weeks", "days", "hours", "minutes", "seconds", "msecs" (milliseconds), "usecs" (microseconds), "hnsecs" (hecto-nanoseconds - i.e. 100 ns) or some subset thereof. There are a few functions that also allow "nsecs", but very little actually has precision greater than hnsecs.

License:
.

Authors:
Jonathan M Davis and Kato Shoichi

Source:


struct Duration;
Represents a duration of time of weeks or less (kept internally as hnsecs). (e.g. 22 days or 700 seconds).

It is used when representing a duration of time - such as how long to sleep with .

In std.datetime, it is also used as the result of various arithmetic operations on time points.

Use the function or on of its non-generic aliases to create s.

It's not possible to create a Duration of months or years, because the variable number of days in a month or year makes it impossible to convert between months or years and smaller units without a specific date. So, nothing uses s when dealing with months or years. Rather, functions specific to months and years are defined. For instance, has and for adding years and months rather than creating a Duration of years or months and adding that to a . But Duration is used when dealing with weeks or smaller.

Examples:
assert(dur!"days"(12) == Duration(10_368_000_000_000L));
assert(dur!"hnsecs"(27) == Duration(27));
assert(std.datetime.Date(2010, 9, 7) + dur!"days"(5) ==
       std.datetime.Date(2010, 9, 12));

assert(days(-12) == Duration(-10_368_000_000_000L));
assert(hnsecs(-27) == Duration(-27));
assert(std.datetime.Date(2010, 9, 7) - std.datetime.Date(2010, 10, 3) ==
       days(-26));


static pure nothrow @property @safe Duration zero();
A of . It's shorter than doing something like and more explicit than .

static pure nothrow @property @safe Duration max();
Largest possible.

static pure nothrow @property @safe Duration min();
Most negative possible.

const pure nothrow @safe int opCmp(Duration rhs);
Compares this with the given .

Returns:
this < rhs < 0
this == rhs 0
this > rhs > 0


const pure nothrow @safe Duration opBinary(string op, D)(D rhs);
Adds or subtracts two durations.

The legal types of arithmetic for using this operator are

Duration + Duration --> Duration
Duration - Duration --> Duration
Duration + TickDuration --> Duration
Duration - TickDuration --> Duration


Params:
rhs The duration to add to or subtract from this .

const pure nothrow @safe Duration opBinaryRight(string op, D)(D lhs);
Adds or subtracts two durations.

The legal types of arithmetic for using this operator are

TickDuration + Duration --> Duration
TickDuration - Duration --> Duration


Params:
lhs The to add to this or to subtract this from.

pure nothrow @safe Duration opOpAssign(string op, D)(in D rhs);
Adds or subtracts two durations as well as assigning the result to this .

The legal types of arithmetic for using this operator are

Duration + Duration --> Duration
Duration - Duration --> Duration
Duration + TickDuration --> Duration
Duration - TickDuration --> Duration


Params:
rhs The duration to add to or subtract from this .

const pure nothrow @safe Duration opBinary(string op)(long value);
The legal types of arithmetic for using this operator overload are

Duration * long --> Duration


Params:
value The value to multiply this by.

pure nothrow @safe Duration opOpAssign(string op)(long value);
The legal types of arithmetic for using this operator overload are

Duration * long --> Duration


Params:
value The value to multiply this by.

const pure @safe Duration opBinary(string op)(long value);
The legal types of arithmetic for using this operator overload are

Duration / long --> Duration


Params:
value The value to divide from this duration.

Throws:
if an attempt to divide by is made.

pure @safe Duration opOpAssign(string op)(long value);
The legal types of arithmetic for using this operator overload are

Duration / long --> Duration


Params:
value The value to divide from this .

Throws:
if an attempt to divide by is made.

const pure nothrow @safe Duration opBinaryRight(string op)(long value);
Multiplies an integral value and a .

The legal types of arithmetic for using this operator overload are

long * Duration --> Duration


Params:
value The number of units to multiply this by.

const pure nothrow @safe Duration opUnary(string op)();
Returns the negation of this .

const pure nothrow @safe TickDuration opCast(T)();
Returns a with the same number of hnsecs as this .

const pure nothrow @safe long get(string units)();
Returns the number of the given units in this (minus the larger units).

Examples:
assert(dur!"weeks"(12).get!"weeks"() == 12);
assert(dur!"weeks"(12).get!"days"() == 0);

assert(dur!"days"(13).get!"weeks"() == 1);
assert(dur!"days"(13).get!"days"() == 6);

assert(dur!"hours"(49).get!"days"() == 2);
assert(dur!"hours"(49).get!"hours"() == 1);


const pure nothrow @property @safe long weeks();
Returns the number of weeks in this (minus the larger units).

Examples:
assert(dur!"weeks"(12).weeks == 12);
assert(dur!"days"(13).weeks == 1);


const pure nothrow @property @safe long days();
Returns the number of days in this (minus the larger units).

Examples:
assert(dur!"weeks"(12).days == 0);
assert(dur!"days"(13).days == 6);
assert(dur!"hours"(49).days == 2);


const pure nothrow @property @safe long hours();
Returns the number of hours in this (minus the larger units).

Examples:
assert(dur!"days"(8).hours == 0);
assert(dur!"hours"(49).hours == 1);
assert(dur!"minutes"(121).hours == 2);


const pure nothrow @property @safe long minutes();
Returns the number of minutes in this (minus the larger units).

Examples:
assert(dur!"hours"(47).minutes == 0);
assert(dur!"minutes"(127).minutes == 7);
assert(dur!"seconds"(121).minutes == 2);


const pure nothrow @property @safe long seconds();
Returns the number of seconds in this (minus the larger units).

Examples:
assert(dur!"minutes"(47).seconds == 0);
assert(dur!"seconds"(127).seconds == 7);
assert(dur!"msecs"(1217).seconds == 1);


const pure nothrow @property @safe FracSec fracSec();
Returns the fractional seconds passed the second in this .

Examples:
assert(dur!"msecs"(1000).fracSec == FracSec.from!"msecs"(0));
assert(dur!"msecs"(1217).fracSec == FracSec.from!"msecs"(217));
assert(dur!"usecs"(43).fracSec == FracSec.from!"usecs"(43));
assert(dur!"hnsecs"(50_007).fracSec == FracSec.from!"hnsecs"(50_007));
assert(dur!"nsecs"(62_127).fracSec == FracSec.from!"nsecs"(62_100));

assert(dur!"msecs"(-1000).fracSec == FracSec.from!"msecs"(-0));
assert(dur!"msecs"(-1217).fracSec == FracSec.from!"msecs"(-217));
assert(dur!"usecs"(-43).fracSec == FracSec.from!"usecs"(-43));
assert(dur!"hnsecs"(-50_007).fracSec == FracSec.from!"hnsecs"(-50_007));
assert(dur!"nsecs"(-62_127).fracSec == FracSec.from!"nsecs"(-62_100));


const pure nothrow @safe long total(string units)();
Returns the total number of the given units in this . So, unlike , it does not strip out the larger units.

Examples:
assert(dur!"weeks"(12).total!"weeks" == 12);
assert(dur!"weeks"(12).total!"days" == 84);

assert(dur!"days"(13).total!"weeks" == 1);
assert(dur!"days"(13).total!"days" == 13);

assert(dur!"hours"(49).total!"days" == 2);
assert(dur!"hours"(49).total!"hours" == 49);

assert(dur!"nsecs"(2007).total!"hnsecs" == 20);
assert(dur!"nsecs"(2007).total!"nsecs" == 2000);


const pure nothrow @safe string toString();
Converts this to a .

const pure nothrow @property @safe bool isNegative();
Returns whether this is negative.

pure nothrow @safe Duration dur(string units)(long length);
alias weeks = dur!("weeks").dur;
alias days = dur!("days").dur;
alias hours = dur!("hours").dur;
alias minutes = dur!("minutes").dur;
alias seconds = dur!("seconds").dur;
alias msecs = dur!("msecs").dur;
alias usecs = dur!("usecs").dur;
alias hnsecs = dur!("hnsecs").dur;
alias nsecs = dur!("nsecs").dur;
These allow you to construct a from the given time units with the given length.

You can either use the generic function and give it the units as a or use the named aliases.

The possible values for units are , , , , , (milliseconds), , (microseconds), (hecto-nanoseconds, i.e. 100 ns), and .

Examples:
// Generic
assert(dur!"weeks"(142).total!"weeks" == 142);
assert(dur!"days"(142).total!"days" == 142);
assert(dur!"hours"(142).total!"hours" == 142);
assert(dur!"minutes"(142).total!"minutes" == 142);
assert(dur!"seconds"(142).total!"seconds" == 142);
assert(dur!"msecs"(142).total!"msecs" == 142);
assert(dur!"usecs"(142).total!"usecs" == 142);
assert(dur!"hnsecs"(142).total!"hnsecs" == 142);
assert(dur!"nsecs"(142).total!"nsecs" == 100);

// Non-generic
assert(weeks(142).total!"weeks" == 142);
assert(days(142).total!"days" == 142);
assert(hours(142).total!"hours" == 142);
assert(minutes(142).total!"minutes" == 142);
assert(seconds(142).total!"seconds" == 142);
assert(msecs(142).total!"msecs" == 142);
assert(usecs(142).total!"usecs" == 142);
assert(hnsecs(142).total!"hnsecs" == 142);
assert(nsecs(142).total!"nsecs" == 100);


Params:
units The time units of the (e.g. ).
length The number of units in the .

struct TickDuration;
Represents a duration of time in system clock ticks.

The system clock ticks are the ticks of the system clock at the highest precision that the system provides.

static immutable long ticksPerSec;
The number of ticks that the system clock has in one second.

If is , then then failed to get the value of on the current system, and is not going to work. That would be highly abnormal though.

static immutable TickDuration appOrigin;
The tick of the system clock (as a ) when the application started.

static pure nothrow @property @safe TickDuration zero();
It's the same as , but it's provided to be consistent with and , which provide properties.

static pure nothrow @property @safe TickDuration max();
Largest possible.

static pure nothrow @property @safe TickDuration min();
Most negative possible.

long length;
The number of system ticks in this .

You can convert this into the number of seconds by dividing it by (or using one the appropriate property function to do it).

const pure nothrow @safe T to(string units, T)();
Converts this to the given units as either an integral value or a floating point value.

Params:
units The units to convert to. Accepts and smaller only.
T The type to convert to (either an integral type or a floating point type).

const pure nothrow @property @safe long seconds();
Returns the total number of seconds in this .

const pure nothrow @property @safe long msecs();
Returns the total number of milliseconds in this .

const pure nothrow @property @safe long usecs();
Returns the total number of microseconds in this .

const pure nothrow @property @safe long hnsecs();
Returns the total number of hecto-nanoseconds in this .

const pure nothrow @property @safe long nsecs();
Returns the total number of nanoseconds in this .

pure nothrow @safe TickDuration from(string units)(long length);
This allows you to construct a from the given time units with the given length.

Params:
units The time units of the (e.g. ).
length The number of units in the .

const pure nothrow @safe Duration opCast(T)();
Returns a with the same number of hnsecs as this .

pure nothrow @safe TickDuration opOpAssign(string op)(TickDuration rhs);
Adds or subtracts two s as well as assigning the result to this .

The legal types of arithmetic for using this operator are

TickDuration += TickDuration --> TickDuration
TickDuration -= TickDuration --> TickDuration


Params:
rhs The to add to or subtract from this .

const pure nothrow @safe TickDuration opBinary(string op)(TickDuration rhs);
Adds or subtracts two s.

The legal types of arithmetic for using this operator are

TickDuration + TickDuration --> TickDuration
TickDuration - TickDuration --> TickDuration


Params:
rhs The to add to or subtract from this .

const pure nothrow @safe TickDuration opUnary(string op)();
Returns the negation of this .

const pure nothrow @safe int opCmp(TickDuration rhs);
operator overloading "<, >, <=, >="

pure nothrow @safe void opOpAssign(string op, T)(T value);
The legal types of arithmetic for using this operator overload are

TickDuration * long --> TickDuration
TickDuration * floating point --> TickDuration


Params:
value The value to divide from this duration.

pure @safe void opOpAssign(string op, T)(T value);
The legal types of arithmetic for using this operator overload are

TickDuration / long --> TickDuration
TickDuration / floating point --> TickDuration


Params:
value The value to divide from this .

Throws:
if an attempt to divide by is made.

const pure nothrow @safe TickDuration opBinary(string op, T)(T value);
The legal types of arithmetic for using this operator overload are

TickDuration * long --> TickDuration
TickDuration * floating point --> TickDuration


Params:
value The value to divide from this .

const pure @safe TickDuration opBinary(string op, T)(T value);
The legal types of arithmetic for using this operator overload are

TickDuration / long --> TickDuration
TickDuration / floating point --> TickDuration


Params:
value The value to divide from this .

Throws:
if an attempt to divide by is made.

this(long ticks);
Params:
long ticks The number of ticks in the TickDuration.

static @property @trusted TickDuration currSystemTick();
The current system tick. The number of ticks per second varies from system to system. uses a monotonic clock, so it's intended for precision timing by comparing relative time values, not for getting the current system time.

On Windows, is used. On Mac OS X, is used, while on other Posix systems, is used. If or is unavailable, then Posix systems use (the decision is made when is compiled), which unfortunately, is not monotonic, but if and aren't available, then is the the best that there is.

Warning: On some systems, the monotonic clock may stop counting when the computer goes to sleep or hibernates. So, the monotonic clock could be off if that occurs. This is known to happen on Mac OS X. It has not been tested whether it occurs on either Windows or on Linux.

Throws:
if it fails to get the time.

pure nothrow @safe long convert(string from, string to)(long value);
Generic way of converting between two time units. Conversions to smaller units use truncating division. Years and months can be converted to each other, small units can be converted to each other, but years and months cannot be converted to or from smaller units (due to the varying number of days in a month or year).

Params:
tuFrom The units of time to covert from.
tuFrom The units of time to covert type.
value The value to convert.

Examples:
assert(convert!("years", "months")(1) == 12);
assert(convert!("months", "years")(12) == 1);

assert(convert!("weeks", "days")(1) == 7);
assert(convert!("hours", "seconds")(1) == 3600);
assert(convert!("seconds", "days")(1) == 0);
assert(convert!("seconds", "days")(86_400) == 1);

assert(convert!("nsecs", "nsecs")(1) == 1);
assert(convert!("nsecs", "hnsecs")(1) == 0);
assert(convert!("hnsecs", "nsecs")(1) == 100);
assert(convert!("nsecs", "seconds")(1) == 0);
assert(convert!("seconds", "nsecs")(1) == 1_000_000_000);


struct FracSec;
Represents fractional seconds.

This is the portion of the time which is smaller than a second and it cannot hold values which would be greater than or equal to a second (or less than or equal to a negative second).

It holds hnsecs internally, but you can create it using either milliseconds, microseconds, or hnsecs. What it does is allow for a simple way to set or adjust the fractional seconds portion of a or a without having to worry about whether you're dealing with milliseconds, microseconds, or hnsecs.

's functions which take time unit strings do accept , but because the resolution of and is hnsecs, you don't actually get precision higher than hnsecs. is accepted merely for convenience. Any values given as nsecs will be converted to hnsecs using (which uses truncating division when converting to smaller units).

static pure nothrow @property @safe FracSec zero();
A of . It's shorter than doing something like and more explicit than .

pure @safe FracSec from(string units)(long value);
Create a from the given units (, , or ).

Params:
units The units to create a FracSec from.
value The number of the given units passed the second.

Throws:
if the given value would result in a greater than or equal to second or less than or equal to seconds.

const pure nothrow @safe FracSec opUnary(string op)();
Returns the negation of this .

const pure nothrow @property @safe int msecs();
The value of this as milliseconds.

pure @property @safe void msecs(int milliseconds);
The value of this as milliseconds.

Params:
int milliseconds The number of milliseconds passed the second.

Throws:
if the given value is not less than second and greater than a seconds.

const pure nothrow @property @safe int usecs();
The value of this as microseconds.

pure @property @safe void usecs(int microseconds);
The value of this as microseconds.

Params:
int microseconds The number of microseconds passed the second.

Throws:
if the given value is not less than second and greater than a seconds.

const pure nothrow @property @safe int hnsecs();
The value of this as hnsecs.

pure @property @safe void hnsecs(int hnsecs);
The value of this as hnsecs.

Params:
int hnsecs The number of hnsecs passed the second.

Throws:
if the given value is not less than second and greater than a seconds.

const pure nothrow @property @safe int nsecs();
The value of this as nsecs.

Note that this does not give you any greater precision than getting the value of this as hnsecs.

pure @property @safe void nsecs(long nsecs);
The value of this as nsecs.

Note that this does not give you any greater precision than setting the value of this as hnsecs.

Params:
long nsecs The number of nsecs passed the second.

Throws:
if the given value is not less than second and greater than a seconds.

const pure nothrow @safe string toString();
Converts this to a string.

class TimeException: object.Exception;
Exception type used by core.time.

this(string msg, string file = __FILE__, size_t line = __LINE__, Throwable next = null);
Params:
string msg The message for the exception.
string file The file where the exception occurred.
size_t line The line number where the exception occurred.
Throwable next The previous exception in the chain of exceptions, if any.

Duration abs(Duration duration);
TickDuration abs(TickDuration duration);
Returns the absolute value of a duration.

Page generated by Ddoc. Copyright 2010 - 2012