# 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. convert!("days", "hours")(numDays)). 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:**

Boost License 1.0.

**Authors:**

Jonathan M Davis and Kato Shoichi

**Source:**

core/time.d

- 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 core.Thread.sleep.
In std.datetime, it is also used as the result of various arithmetic
operations on time points.
Use the dur function or on of its non-generic aliases to create
__Duration__s. You cannot create a duration of months or years because the variable number of days in a month or a year makes it so that you cannot convert between months or years and smaller units without a specific date. Any type or function which handles months or years has other functions for handling those rather than using durations. For instance, std.datetime.Date has addYears and addMonths for adding years and months, rather than creating a duration of years or months and adding that to a std.datetime.Date. If you're dealing with weeks or smaller, however, durations are what you use.**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));

- A Duration of 0. It's shorter than doing something like dur!"seconds"(0) and more explicit than Duration.init.
- Compares this Duration with the given Duration.
**Returns:**this < *rhs*< 0 this == *rhs*0 this > *rhs*> 0 this < *rhs*< 0 this == *rhs*0 this > *rhs*> 0 - Adds or subtracts two durations.
The legal types of arithmetic for Duration using this operator are
Duration + Duration --> Duration Duration - Duration --> Duration Duration + TickDuration --> Duration Duration - TickDuration --> Duration Duration + Duration --> Duration Duration - Duration --> Duration Duration + TickDuration --> Duration Duration - TickDuration --> Duration **Parameters:**rhs The duration to add to or subtract from this Duration. - Adds or subtracts two durations.
The legal types of arithmetic for Duration using this operator are
TickDuration + Duration --> Duration TickDuration - Duration --> Duration TickDuration + Duration --> Duration TickDuration - Duration --> Duration **Parameters:**lhs The TickDuration to add to this Duration or to subtract this Duration from. - Adds or subtracts two durations as well as assigning the result to this
Duration.
The legal types of arithmetic for Duration using this operator are
Duration + Duration --> Duration Duration - Duration --> Duration Duration + TickDuration --> Duration Duration - TickDuration --> Duration Duration + Duration --> Duration Duration - Duration --> Duration Duration + TickDuration --> Duration Duration - TickDuration --> Duration **Parameters:**rhs The duration to add to or subtract from this Duration. - The legal types of arithmetic for Duration using this operator
overload are
Duration * long --> Duration Duration * long --> Duration **Parameters:**value The value to multiply this Duration by. - The legal types of arithmetic for Duration using this operator
overload are
Duration * long --> Duration Duration * long --> Duration **Parameters:**value The value to multiply this Duration by. - The legal types of arithmetic for Duration using this operator
overload are
Duration / long --> Duration Duration / long --> Duration **Parameters:**value The value to divide from this duration. **Throws:**

TimeException if an attempt to divide by 0 is made. - The legal types of arithmetic for Duration using this operator
overload are
Duration / long --> Duration Duration / long --> Duration **Parameters:**value The value to divide from this Duration. **Throws:**

TimeException if an attempt to divide by 0 is made. - Multiplies an integral value and a Duration.
The legal types of arithmetic for Duration using this operator
overload are
long * Duration --> Duration long * Duration --> Duration **Parameters:**value The number of units to multiply this Duration by. - Returns the negation of this Duration.
- Returns a TickDuration with the same number of hnsecs as this Duration.
- Returns the number of the given units in this Duration
(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);

- Returns the number of
__weeks__in this Duration (minus the larger units).**Examples:**assert(dur!"weeks"(12).weeks == 12); assert(dur!"days"(13).weeks == 1);

- Returns the number of
__days__in this Duration (minus the larger units).**Examples:**assert(dur!"weeks"(12).days == 0); assert(dur!"days"(13).days == 6); assert(dur!"hours"(49).days == 2);

- Returns the number of
__hours__in this Duration (minus the larger units).**Examples:**assert(dur!"days"(8).hours == 0); assert(dur!"hours"(49).hours == 1); assert(dur!"minutes"(121).hours == 2);

- Returns the number of
__minutes__in this Duration (minus the larger units).**Examples:**assert(dur!"hours"(47).minutes == 0); assert(dur!"minutes"(127).minutes == 7); assert(dur!"seconds"(121).minutes == 2);

- Returns the number of
__seconds__in this Duration (minus the larger units).**Examples:**assert(dur!"minutes"(47).seconds == 0); assert(dur!"seconds"(127).seconds == 7); assert(dur!"msecs"(1217).seconds == 1);

- Returns the fractional seconds passed the second in this Duration.
**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));

- Returns the
__total__number of the given units in this Duration. So, unlike get, 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);

- Converts this Duration to a string.
- Returns whether this Duration is negative.

- pure nothrow @safe Duration
__dur__(string units)(long*length*);

alias dur!("__weeks__").dur__weeks__;

alias dur!("__days__").dur__days__;

alias dur!("__hours__").dur__hours__;

alias dur!("__minutes__").dur__minutes__;

alias dur!("__seconds__").dur__seconds__;

alias dur!("__msecs__").dur__msecs__;

alias dur!("__usecs__").dur__usecs__;

alias dur!("__hnsecs__").dur__hnsecs__;

alias dur!("__nsecs__").dur__nsecs__; - These allow you to construct a Duration from the given time units
with the given length.
You can either use the generic function
__dur__and give it the units as a string or use the named aliases. The possible values for units are "weeks", "days", "hours", "minutes", "seconds", "msecs" (milliseconds), "usecs", (microseconds), "hnsecs" (hecto-nanoseconds, i.e. 100 ns), and "nsecs".**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);

**Parameters:**units The time units of the Duration (e.g. "days"). length The number of units in the Duration. - 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.
- The number of ticks that the system clock has in one second.
If
__ticksPerSec__is 0, then then TickDuration failed to get the value of__ticksPerSec__on the current system, and TickDuration is not going to work. That would be highly abnormal though. - The tick of the system clock (as a TickDuration) when the application started.
- It's the same as TickDuration(0), but it's provided to be
consistent with Duration and FracSec, which provide
__zero__properties. - The number of system ticks in this TickDuration.
You can convert this
__length__into the number of seconds by dividing it by ticksPerSec (or using one the appropriate property function to do it). - Converts this TickDuration
__to__the given units as either an integral value or a floating point value.**Parameters:**units The units __to__convert__to__. Accepts "seconds" and smaller only.T The type __to__convert__to__(either an integral type or a floating point type). - Returns the total number of
__seconds__in this TickDuration. - Returns the total number of milliseconds in this TickDuration.
- Returns the total number of microseconds in this TickDuration.
- Returns the total number of hecto-nanoseconds in this TickDuration.
- Returns the total number of nanoseconds in this TickDuration.
- This allows you to construct a TickDuration
__from__the given time units with the given length.**Parameters:**units The time units of the TickDuration (e.g. "msecs"). length The number of units in the TickDuration. - Returns a Duration with the same number of hnsecs as this TickDuration.
- Adds or subtracts two TickDurations as well as assigning the result
to this TickDuration.
The legal types of arithmetic for TickDuration using this operator
are
TickDuration += TickDuration --> TickDuration TickDuration -= TickDuration --> TickDuration TickDuration += TickDuration --> TickDuration TickDuration -= TickDuration --> TickDuration **Parameters:**rhs The TickDuration to add to or subtract from this TickDuration. - Adds or subtracts two TickDurations.
The legal types of arithmetic for TickDuration using this operator
are
TickDuration + TickDuration --> TickDuration TickDuration - TickDuration --> TickDuration TickDuration + TickDuration --> TickDuration TickDuration - TickDuration --> TickDuration **Parameters:**rhs The TickDuration to add to or subtract from this TickDuration. - Returns the negation of this TickDuration.
- operator overloading "<, >, <=, >="
- The legal types of arithmetic for TickDuration using this operator
overload are
TickDuration * long --> TickDuration TickDuration * floating point --> TickDuration TickDuration * long --> TickDuration TickDuration * floating point --> TickDuration **Parameters:**value The value to divide from this duration. - The legal types of arithmetic for TickDuration using this operator
overload are
TickDuration / long --> TickDuration TickDuration / floating point --> TickDuration TickDuration / long --> TickDuration TickDuration / floating point --> TickDuration **Parameters:**value The value to divide from this TickDuration. **Throws:**

TimeException if an attempt to divide by 0 is made. - The legal types of arithmetic for TickDuration using this operator
overload are
TickDuration * long --> TickDuration TickDuration * floating point --> TickDuration TickDuration * long --> TickDuration TickDuration * floating point --> TickDuration **Parameters:**value The value to divide from this TickDuration. - The legal types of arithmetic for TickDuration using this operator
overload are
TickDuration / long --> TickDuration TickDuration / floating point --> TickDuration TickDuration / long --> TickDuration TickDuration / floating point --> TickDuration **Parameters:**value The value to divide from this TickDuration. **Throws:**

TimeException if an attempt to divide by 0 is made. **Parameters:**long *ticks*The number of *ticks*in the TickDuration.- The current system tick. The number of ticks per second varies from
system to system.
__currSystemTick__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, QueryPerformanceCounter is used. On Mac OS X, mach_absolute_time is used, while on other Posix systems, clock_gettime is used. If mach_absolute_time or clock_gettime is unavailable, then Posix systems use gettimeofday (the decision is made when TickDuration is compiled), which unfortunately, is not monotonic, but if mach_absolute_time and clock_gettime aren't available, then gettimeofday 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:**

TimeException if it fails to get the time.

- 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).
**Parameters:**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);

- 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 Duration or a
std.datetime.SysTime without having to worry about whether you're
dealing with milliseconds, microseconds, or hnsecs.
__FracSec__'s functions which take time unit strings do accept "nsecs", but because the resolution of Duration and std.datetime.SysTime is hnsecs, you don't actually get precision higher than hnsecs. "nsecs" is accepted merely for convenience. Any values given as nsecs will be converted to hnsecs using convert (which uses truncating division when converting to smaller units).- A FracSec of 0. It's shorter than doing something like FracSec.from!"msecs"(0) and more explicit than FracSec.init.
- Create a FracSec
__from__the given units ("msecs", "usecs", or "hnsecs").**Parameters:**units The units to create a FracSec __from__.value The number of the given units passed the second. **Throws:**

TimeException if the given value would result in a FracSec greater than or equal to 1 second or less than or equal to -1 seconds. - Returns the negation of this FracSec.
- The value of this FracSec as milliseconds.
- The value of this FracSec as
*milliseconds*.**Parameters:**int *milliseconds*The number of *milliseconds*passed the second.**Throws:**

TimeException if the given value is not less than 1 second and greater than a -1 seconds. - The value of this FracSec as microseconds.
- The value of this FracSec as
*microseconds*.**Parameters:**int *microseconds*The number of *microseconds*passed the second.**Throws:**

TimeException if the given value is not less than 1 second and greater than a -1 seconds. - The value of this FracSec as
__hnsecs__. - The value of this FracSec as
__hnsecs__.**Parameters:**int __hnsecs__The number of __hnsecs__passed the second.**Throws:**

TimeException if the given value is not less than 1 second and greater than a -1 seconds. - The value of this FracSec as
__nsecs__. Note that this does not give you any greater precision than getting the value of this FracSec as hnsecs. - The value of this FracSec as
__nsecs__. Note that this does not give you any greater precision than setting the value of this FracSec as hnsecs.**Parameters:**long __nsecs__The number of __nsecs__passed the second.**Throws:**

TimeException if the given value is not less than 1 second and greater than a -1 seconds. - Converts this TickDuration to a string.

- Exception type used by core.time.
**Parameters:**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.

- Returns the absolute value of a
*duration*.