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:
std/datetime.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 Thread.sleep().
In std.datetime, it is also used as the result of various arithmetic
operations on time points.
Use the dur!() function 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));
const pure nothrow int
opCmp(in 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 |
Duration
opBinary(string op, D)(in 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:duration |
The duration to add to or subtract from this duration. |
Note:
TUnqual is just a local copy of std.traits' Unqual, since core does
not have access to std.traits, and naming it Unqual as well would
result in a name clash, so it's TUnqual.
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 DateTime. |
Note:
TUnqual is just a local copy of std.traits' Unqual, since core does
not have access to std.traits, and naming it Unqual as well would
result in a name clash, so it's TUnqual.
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. |
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. |
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.
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.
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. |
Duration
opUnary(string op)();
- Returns the negation of this Duration.
long
get(string units)();
- Returns the number of the given units in the 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 the duration.
Examples:
assert(dur!"weeks"(12).weeks == 12);
assert(dur!"days"(13).weeks == 1);
- Returns the number of days in the 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 the 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 the 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 the 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 FracSec
fracSec();
- Returns the fractional seconds passed the second.
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));
long
total(string units)();
- Returns the total number of the given units in the 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 string
toString();
- Converts this duration to a string.
Duration
dur(string units)(long
length);
- This allows you to construct a Duration from the given time units
with the given length.
The possible values for units are "weeks", "days", "hours", "minutes",
"seconds", "msecs" (milliseconds), "usecs", (microseconds),
"hnsecs" (hecto-nanoseconds, i.e. 100 ns), and "nsecs".
Parameters:
units |
The time units of the duration (e.g. "days"). |
length |
The number of units in the duration. |
- Duration in system clock ticks.
This type maintains the most high precision ticks of system clock in each
environment.
static immutable long
ticksPerSec;
- The number of ticks that the system clock has in one second.
Confirm that it is not 0, to examine whether you can use TickDuration.
static immutable TickDuration
appOrigin;
- TickDuration when application begins.
- The number of ticks.
You can convert this length into number of seconds by dividing it
by ticksPerSec.
- Converts TickDuration to the given units as an integral value.
Parameters:
units |
The units to convert to. "seconds" and smaller only. |
T |
The integral type to convert to. |
- Converts TickDuration to the given units as a floating point value.
Parameters:
units |
The units to convert to. "seconds" and smaller only. |
T |
The floating point type to convert to. |
- Alias for converting TickDuration to seconds.
- Alias for converting TickDuration to milliseconds.
- Alias for converting TickDuration to microseconds.
- Alias for converting TickDuration to hecto-nanoseconds (100 ns).
- Alias for converting TickDuration to nanoseconds.
TickDuration
from(string units)(long
value);
- Creates a TickDuration from the number of the given units.
Parameters:
units |
The units to convert from. "seconds" and smaller. |
value |
The number of the units to convert from. |
- Returns a Duration with the same number of hnsecs as this TickDuration.
void
opOpAssign(string op)(in TickDuration
rhs);
- operator overloading "-=, +="
BUG:
This should be return "ref TickDuration", but bug2460 prevents that.
TickDuration
opBinary(string op)(in TickDuration
rhs);
- operator overloading "-, +"
TickDuration
opUnary(string op)();
- Returns the negation of this TickDuration.
const pure nothrow bool
opEquals(ref const TickDuration
rhs);
- operator overloading "=="
const pure nothrow int
opCmp(ref const TickDuration
rhs);
- operator overloading "<, >, <=, >="
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. |
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. |
Throws:
TimeException if an attempt to divide by 0 is made.
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 duration. |
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 duration. |
Throws:
TimeException if an attempt to divide by 0 is made.
pure nothrow @safe this(long ticks);
- Parameters:
long ticks |
The number of ticks in the TickDuration. |
static TickDuration
currSystemTick();
- The current system tick. The number of ticks per second varies from
system to system. This 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(), which
unfortunately, is not monotonic, but without
mach_absolute_time()/clock_gettime() available, gettimeofday() is the
the best that you can do.
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.
long
convert(string from, string to)(long
value);
- Generic way of converting between two time units. Conversions to smaller
units use truncating division.
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);
long
convert(string from, string to)(long
value);
- Generic way of converting between two time units. Conversions to smaller
units use truncating division.
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!("weeks", "days")(1) == 7);
assert(convert!("hours", "seconds")(1) == 3600);
assert(convert!("seconds", "days")(1) == 0);
assert(convert!("seconds", "days")(86_400) == 1);
long
convert(string from, string to)(long
value);
- Generic way of converting between two time units. Conversions to smaller
units use truncating division.
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!("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 cannot
hold values which would equal or exceed a 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 the
because the resolution for 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 truncation when converting to smaller units).
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 is less than 0 or would result in a
FracSec greater than or equal to 1 second.
const pure nothrow int
msecs();
- The value of this FracSec as milliseconds.
pure 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 one second.
const pure nothrow int
usecs();
- The value of this FracSec as microseconds.
pure 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 one second.
const pure nothrow int
hnsecs();
- The value of this FracSec as hnsecs.
pure 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 one second.
const pure nothrow 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 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 one second.
const pure nothrow string
toString();
- Converts this duration to a string.
class
TimeException: object.Exception;
- Exception type used by core.time.
nothrow 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. |