D Programming Language 2.0

- Comments
- D
- Search
- Home

Last update Mon Oct 24 15:54:31 2011

# 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

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 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));

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

  const pure nothrow @safe 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

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

  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 DateTime.

  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 with the same number of hnsecs as this .

  const pure nothrow @safe 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);

  const pure nothrow @property @safe long weeks();
    Returns the number of weeks in the duration.

    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 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);

  const pure nothrow @property @safe long hours();
    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);

  const pure nothrow @property @safe long minutes();
    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);

  const pure nothrow @property @safe long seconds();
    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 @property @safe 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));

        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 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 @safe string toString();
    Converts this duration to a string.

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

struct TickDuration;
  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.

  long length;
    The number of ticks.

    You can convert this length into number of seconds by dividing it by ticksPerSec.

  const pure nothrow @safe T to(string units, T)();
    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.

  const pure nothrow @safe T to(string units, T)();
    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.

  const pure nothrow @property @safe long seconds();
    Alias for converting TickDuration to seconds.

  const pure nothrow @property @safe long msecs();
    Alias for converting TickDuration to milliseconds.

  const pure nothrow @property @safe long usecs();
    Alias for converting TickDuration to microseconds.

  const pure nothrow @property @safe long hnsecs();
    Alias for converting TickDuration to hecto-nanoseconds (100 ns).

  const pure nothrow @property @safe long nsecs();
    Alias for converting TickDuration to nanoseconds.

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

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

  pure nothrow @safe TickDuration opOpAssign(string op)(in TickDuration rhs);
    operator overloading "-=, +="

  const pure nothrow @safe TickDuration opBinary(string op)(in TickDuration rhs);
    operator overloading "-, +"

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

  const pure nothrow @safe bool opEquals(ref const TickDuration rhs);
    operator overloading "=="

  const pure nothrow @safe int opCmp(ref const 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 duration.

    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 duration.

  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 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 @property @trusted 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.

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.

  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);

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.

  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);

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.

  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);

struct FracSec;
  Represents fractional seconds.

  This is the portion of the time which is smaller than a second and cannot hold values which would 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 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).

  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 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 one second.

  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 one second.

  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 one second.

  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 one second.

  const pure nothrow @safe 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__, uint line = cast(uint)__LINE__, Throwable next = cast(Throwable)null);
    Parameters:

    string msg | The message for the exception.
    string file | The file where the exception occurred.
    uint line | The line number where the exception occurred.
    Throwable next | The previous exception in the chain of exceptions, if any.

Copyright 2010 - 2011 | Page generated by Ddoc.