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
Durations.
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));
static pure nothrow @property @safe Duration
zero();
- A Duration of 0. It's shorter than doing something like
dur!"seconds"(0) and more explicit than Duration.init.
const pure nothrow @safe int
opCmp(Duration
rhs);
- 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 |
const pure nothrow @safe Duration
opBinary(string op, D)(D
rhs);
- 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. |
const pure nothrow @safe Duration
opBinaryRight(string op, D)(D
lhs);
- 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. |
pure nothrow @safe Duration
opOpAssign(string op, D)(in D
rhs);
- 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. |
const pure nothrow @safe Duration
opBinary(string op)(long
value);
- 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. |
pure nothrow @safe Duration
opOpAssign(string op)(long
value);
- 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. |
const pure @safe Duration
opBinary(string op)(long
value);
- 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.
pure @safe Duration
opOpAssign(string op)(long
value);
- 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.
const pure nothrow @safe Duration
opBinaryRight(string op)(long
value);
- 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. |
const pure nothrow @safe Duration
opUnary(string op)();
- Returns the negation of this Duration.
const pure nothrow @safe TickDuration
opCast(T)();
- Returns a TickDuration with the same number of hnsecs as this
Duration.
const pure nothrow @safe long
get(string units)();
- 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);
const pure nothrow @property @safe long
weeks();
- 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);
const pure nothrow @property @safe long
days();
- 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);
const pure nothrow @property @safe long
hours();
- 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);
const pure nothrow @property @safe long
minutes();
- 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);
const pure nothrow @property @safe long
seconds();
- 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);
const pure nothrow @property @safe FracSec
fracSec();
- 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));
const pure nothrow @safe long
total(string units)();
- 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);
const pure nothrow @safe string
toString();
- Converts this Duration to a string.
const pure nothrow @property @safe bool
isNegative();
- 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:
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);
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.
static immutable long
ticksPerSec;
- 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.
static immutable TickDuration
appOrigin;
- The tick of the system clock (as a TickDuration) when the
application started.
static pure nothrow @property @safe TickDuration
zero();
- 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).
const pure nothrow @safe T
to(string units, T)();
- 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). |
const pure nothrow @property @safe long
seconds();
- Returns the total number of seconds in this TickDuration.
const pure nothrow @property @safe long
msecs();
- Returns the total number of milliseconds in this TickDuration.
const pure nothrow @property @safe long
usecs();
- Returns the total number of microseconds in this TickDuration.
const pure nothrow @property @safe long
hnsecs();
- Returns the total number of hecto-nanoseconds in this TickDuration.
const pure nothrow @property @safe long
nsecs();
- Returns the total number of nanoseconds in this TickDuration.
pure nothrow @safe TickDuration
from(string units)(long
length);
- 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. |
const pure nothrow @safe Duration
opCast(T)();
- Returns a Duration with the same number of hnsecs as this
TickDuration.
pure nothrow @safe TickDuration
opOpAssign(string op)(TickDuration
rhs);
- 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. |
const pure nothrow @safe TickDuration
opBinary(string op)(TickDuration
rhs);
- 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. |
const pure nothrow @safe TickDuration
opUnary(string op)();
- Returns the negation of this TickDuration.
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 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. |
pure @safe void
opOpAssign(string op, T)(T
value);
- 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.
const pure nothrow @safe TickDuration
opBinary(string op, T)(T
value);
- 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. |
const pure @safe TickDuration
opBinary(string op, T)(T
value);
- 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. |
static @property @trusted TickDuration
currSystemTick();
- 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.
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).
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).
static pure nothrow @property @safe FracSec
zero();
- A FracSec of 0. It's shorter than doing something like
FracSec.from!"msecs"(0) and more explicit than FracSec.init.
pure @safe FracSec
from(string units)(long
value);
- 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.
const pure nothrow @safe FracSec
opUnary(string op)();
- Returns the negation of this FracSec.
const pure nothrow @property @safe int
msecs();
- The value of this FracSec as milliseconds.
pure @property @safe void
msecs(int
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.
const pure nothrow @property @safe int
usecs();
- The value of this FracSec as microseconds.
pure @property @safe void
usecs(int
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.
const pure nothrow @property @safe int
hnsecs();
- The value of this FracSec as hnsecs.
pure @property @safe void
hnsecs(int
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.
const pure nothrow @property @safe int
nsecs();
- 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.
pure @property @safe void
nsecs(long
nsecs);
- 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.
const pure nothrow @safe string
toString();
- Converts this TickDuration 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);
- 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. |
Duration
abs(Duration
duration);
TickDuration
abs(TickDuration
duration);
- Returns the absolute value of a duration.
