core.time

Module containing core time functionality, such as Duration (which represents a duration of time) or MonoTime (which represents a timestamp of the system's monotonic clock).

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.

Copyright

License

Boost License 1.0.

Authors

Jonathan M Davis and Kato Shoichi

Source: core/_time.d

var _ticksPerSecond

tmpl hnsecsPer

alias days hnsecs hours minutes MonoTime msecs nsecs seconds usecs weeks

struct Duration MonoTimeImpl TickDuration

class TimeException

fn _abs _clockTypeIdx _clockTypeName _d_initMonoTime abs allAreAcceptedUnits convClockFreq convert dur nsecsToTicks splitUnitsFromHNSecs ticksToNSecs to unitsAreInDescendingOrder

Types 14

structDuration

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 or one of its non-generic aliases to create

Durations.

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 Durations when dealing with months or years. Rather, functions specific to months and years are defined. For instance,

Date has add!"years" and add!"months" for adding

years and months rather than creating a Duration of years or months and adding that to a Date. But Duration is used when dealing with weeks or smaller.

Examples

--------------------

import std.datetime;

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

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

Fields

long _hnsecs

Methods

void toString(SinkT)(scope SinkT sink) const scopeConverts this `Duration` to a `string`.

Duration zero() @property nothrow @nogcA Duration of 0. It's shorter than doing something like dur!"seconds"(0) and more explicit than Duration.init.

Duration max() @property nothrow @nogcLargest Duration possible.

Duration min() @property nothrow @nogcMost negative Duration possible.

int opCmp(Duration rhs) const nothrow @nogcCompares this Duration with the given Duration.

Duration opBinary(string op)(const Duration rhs) if (op == "+" || op == "-" || op == "%") const nothrow @nogcAdds, subtracts or calculates the modulo of two durations.

Duration opBinary(string op)(const TickDuration rhs) if (op == "+" || op == "-") const nothrow @nogc

Duration opBinaryRight(string op,  D)(D lhs) if ((op ==  "+" ||  op ==  "-")  &&
             is(immutable  D ==  immutable  TickDuration))

const nothrow @nogcTickDuration is Deprecated

Duration opOpAssign(string op)(const Duration rhs) if (op == "+" || op == "-" || op == "%") ref nothrow @nogcAdds, subtracts or calculates the modulo of two durations as well as assigning the result to this Duration.

Duration opOpAssign(string op)(const TickDuration rhs) if (op == "+" || op == "-") ref nothrow @nogc

Duration opBinary(string op)(long value) if (op == "*" || op == "/") const nothrow @nogcMultiplies or divides the duration by an integer value.

Duration opOpAssign(string op)(long value) if (op == "*" || op == "/") ref nothrow @nogcMultiplies/Divides the duration by an integer value as well as assigning the result to this Duration.

long opBinary(string op)(Duration rhs) if (op == "/") const nothrow @nogcDivides two durations.

Duration opBinaryRight(string op)(long value) if (op == "*") const nothrow @nogcMultiplies an integral value and a Duration.

Duration opUnary(string op)() if (op == "-") const nothrow @nogcReturns the negation of this Duration.

TickDuration opCast(T)() if (is(immutable T == immutable TickDuration)) const nothrow @nogcTickDuration is Deprecated

bool opCast(T : bool)() const nothrow @nogcAllow Duration to be used as a boolean. Returns: `true` if this duration is non-zero.

Duration opCast(T)() if (is(immutable T == immutable Duration)) const nothrow @nogc

long total(string units)() if (units ==  "weeks" ||
            units ==  "days" ||
            units ==  "hours" ||
            units ==  "minutes" ||
            units ==  "seconds" ||
            units ==  "msecs" ||
            units ==  "usecs" ||
            units ==  "hnsecs" ||
            units ==  "nsecs")

@property const nothrow @nogcReturns the total number of the given units in this Duration. So, unlike split, it does not strip out the larger units.

string toString() const scope nothrowDitto

bool isNegative() @property const nothrow @nogcReturns whether this Duration is negative.

Constructors

this(long hnsecs)

Nested Templates

split(units...)Splits out the Duration into the given units.

aliasweeks = dur!"weeks"

Ditto

aliasdays = dur!"days"

Ditto

aliashours = dur!"hours"

Ditto

aliasminutes = dur!"minutes"

Ditto

aliasseconds = dur!"seconds"

Ditto

aliasmsecs = dur!"msecs"

Ditto

aliasusecs = dur!"usecs"

Ditto

aliashnsecs = dur!"hnsecs"

Ditto

aliasnsecs = dur!"nsecs"

Ditto

aliasMonoTime = MonoTimeImpl!(ClockType.normal)

alias for MonoTimeImpl instantiated with ClockType.normal. This is what most programs should use. It's also what much of MonoTimeImpl uses in its documentation (particularly in the examples), because that's what's going to be used in most code.

structMonoTimeImpl(ClockType clockType)

Represents a timestamp of the system's monotonic clock.

A monotonic clock is one which always goes forward and never moves backwards, unlike the system's wall clock time (as represented by

SysTime). The system's wall clock time can be adjusted

by the user or by the system itself via services such as NTP, so it is unreliable to use the wall clock time for timing. Timers which use the wall clock time could easily end up never going off due to changes made to the wall clock time or otherwise waiting for a different period of time than that specified by the programmer. However, because the monotonic clock always increases at a fixed rate and is not affected by adjustments to the wall clock time, it is ideal for use with timers or anything which requires high precision timing.

So, MonoTime should be used for anything involving timers and timing, whereas SysTime should be used when the wall clock time is required.

The monotonic clock has no relation to wall clock time. Rather, it holds its time as the number of ticks of the clock which have occurred since the clock started (typically when the system booted up). So, to determine how much time has passed between two points in time, one monotonic time is subtracted from the other to determine the number of ticks which occurred between the two points of time, and those ticks are divided by the number of ticks that occur every second (as represented by MonoTime.ticksPerSecond) to get a meaningful duration of time. Normally, MonoTime does these calculations for the programmer, but the ticks and ticksPerSecond properties are provided for those who require direct access to the system ticks. The normal way that MonoTime would be used is

-------------------- MonoTime before = MonoTime.currTime; // do stuff... MonoTime after = MonoTime.currTime; Duration timeElapsed = after - before; --------------------

MonoTime is an alias to MonoTimeImpl!(ClockType.normal) and is

what most programs should use for the monotonic clock, so that's what is used in most of MonoTimeImpl's documentation. But MonoTimeImpl can be instantiated with other clock types for those rare programs that need it.

Functions 16

T to(string units,  T,  D)(D td) if (is(immutable  D ==  immutable  TickDuration)  &&
       (units ==  "seconds" ||
         units ==  "msecs" ||
         units ==  "usecs" ||
         units ==  "hnsecs" ||
         units ==  "nsecs"))

@safe pure nothrow @nogc

deprecated TickDuration has been deprecated, please use Duration or MonoTime instead

TickDuration is DEPRECATED

Duration dur(string units)(long  length) if (units ==  "weeks" ||
        units ==  "days" ||
        units ==  "hours" ||
        units ==  "minutes" ||
        units ==  "seconds" ||
        units ==  "msecs" ||
        units ==  "usecs" ||
        units ==  "hnsecs" ||
        units ==  "nsecs")

@safe pure nothrow @nogcThese allow you to construct a Duration from the given time units with the given length.

private fnstring _clockTypeName(ClockType clockType)

private fnsize_t _clockTypeIdx(ClockType clockType)

fnvoid _d_initMonoTime() @nogc nothrow

fnlong convClockFreq(long ticks, long srcTicksPerSecond, long dstTicksPerSecond) @safe pure nothrow @nogcConverts the given time from one clock frequency/resolution to another.

fnlong ticksToNSecs(long ticks) @safe pure nothrow @nogcConvenience wrapper around convClockFreq which converts ticks at a clock frequency of MonoTime.ticksPerSecond to nanoseconds.

fnlong nsecsToTicks(long ticks) @safe pure nothrow @nogcThe reverse of ticksToNSecs.

long convert(string from,  string to)(long  value) if (((from ==  "weeks" ||
          from ==  "days" ||
          from ==  "hours" ||
          from ==  "minutes" ||
          from ==  "seconds" ||
          from ==  "msecs" ||
          from ==  "usecs" ||
          from ==  "hnsecs" ||
          from ==  "nsecs")  &&
        (to ==  "weeks" ||
          to ==  "days" ||
          to ==  "hours" ||
          to ==  "minutes" ||
          to ==  "seconds" ||
          to ==  "msecs" ||
          to ==  "usecs" ||
          to ==  "hnsecs" ||
          to ==  "nsecs"))  ||
       ((from ==  "years" ||  from ==  "months")  && (to ==  "years" ||  to ==  "months")))

@safe pure nothrow @nogcGeneric 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, ...

fnDuration abs(Duration duration) @safe pure nothrow @nogcReturns the absolute value of a duration.

fnTickDuration abs(TickDuration duration) @safe pure nothrow @nogc

deprecated TickDuration has been deprecated, please use Duration or MonoTime instead

Ditto

long splitUnitsFromHNSecs(string units)(ref  long  hnsecs) if (units ==  "weeks" ||
        units ==  "days" ||
        units ==  "hours" ||
        units ==  "minutes" ||
        units ==  "seconds" ||
        units ==  "msecs" ||
        units ==  "usecs" ||
        units ==  "hnsecs")

@safe pure nothrow @nogc

fnbool allAreAcceptedUnits(acceptedUnits...)(scope string[] units)

fnbool unitsAreInDescendingOrder(scope string[] units)

fnlong _abs(long val) @safe pure nothrow @nogc

fndouble _abs(double val) @safe pure nothrow @nogc

Variables 1

private varlong[__traits(allMembers, ClockType).length] _ticksPerSecond

Templates 1

tmplhnsecsPer(string units)

if (units ==  "weeks" ||
        units ==  "days" ||
        units ==  "hours" ||
        units ==  "minutes" ||
        units ==  "seconds" ||
        units ==  "msecs" ||
        units ==  "usecs" ||
        units ==  "hnsecs")

core.time

Copyright

License

Authors

Types 14

Examples

See Also

Functions 16

Variables 1

Templates 1