Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Calendar
  - Forums
  - IRC
  - Wiki
  - GitHub
  - Issues
  - Get involved
  - Contributors
  - Foundation
  - Security Team
  - Donate
  - Sponsors
- Resources
  - Tour
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - run.dlang.io
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

# std.datetime

Phobos provides the following functionality for time:

Functionality | Symbols
--- | ---
Points in Time | Date TimeOfDay DateTime SysTime
Timezones | TimeZone UTC LocalTime PosixTimeZone WindowsTimeZone SimpleTimeZone
Intervals and Ranges of Time | Interval PosInfInterval NegInfInterval
Durations of Time | Duration weeks days hours minutes seconds msecs usecs hnsecs nsecs
Time Measurement and Benchmarking | MonoTime StopWatch benchmark

This functionality is separated into the following modules

- std.datetime.date for points in time without timezones.
- std.datetime.timezone for classes which represent timezones.
- std.datetime.systime for a point in time with a timezone.
- std.datetime.interval for types which represent series of points in time.
- std.datetime.stopwatch for measuring time.

See Also:
Introduction to std.datetime
ISO 8601
Wikipedia entry on TZ Database
List of Time Zones
License:
Boost License 1.0.
Authors:
Jonathan M Davis and Kato Shoichi

Source std/datetime/package.d

Examples:
Get the current time from the system clock

    import std.datetime.systime : SysTime, Clock;

    SysTime currentTime = Clock.currTime();

Examples:
Construct a specific point in time without timezone information and get its ISO string.

    import std.datetime.date : DateTime;

    auto dt = DateTime(2018, 1, 1, 12, 30, 10);
    writeln(dt.toISOString()); // "20180101T123010"
    writeln(dt.toISOExtString()); // "2018-01-01T12:30:10"

Examples:
Construct a specific point in time in the UTC timezone and add two days.

    import std.datetime.systime : SysTime;
    import std.datetime.timezone : UTC;
    import core.time : days;

    auto st = SysTime(DateTime(2018, 1, 1, 12, 30, 10), UTC());
    writeln(st.toISOExtString()); // "2018-01-01T12:30:10Z"
    st += 2.days;
    writeln(st.toISOExtString()); // "2018-01-03T12:30:10Z"

deprecated alias `AutoStart` = std.typecons.Flag!"autoStart".Flag;
  The old benchmarking functionality in std.datetime (which uses core.time.TickDuration) has been deprecated. Use what's in std.datetime.stopwatch instead. It uses core.time.MonoTime and core.time.Duration. See std.datetime.stopwatch.AutoStart. This symbol will be removed from the documentation in October 2018 and fully removed from Phobos in October 2019.
  Used by StopWatch to indicate whether it should start immediately upon construction.
  If set to `AutoStart`.no, then the stopwatch is not started when it is constructed.
  Otherwise, if set to `AutoStart`.yes, then the stopwatch is started when it is constructed.
struct `StopWatch`;
  The old benchmarking functionality in std.datetime (which uses core.time.TickDuration) has been deprecated. Use what's in std.datetime.stopwatch instead. It uses core.time.MonoTime and core.time.Duration. See std.datetime.stopwatch.StopWatch. This symbol will be removed from the documentation in October 2018 and fully removed from Phobos in October 2019.
  `StopWatch` measures time as precisely as possible.
  This class uses a high-performance counter. On Windows systems, it uses QueryPerformanceCounter, and on Posix systems, it uses clock_gettime if available, and gettimeofday otherwise.
  But the precision of `StopWatch` differs from system to system. It is impossible to for it to be the same from system to system since the precision of the system clock varies from system to system, and other system-dependent and situation-dependent stuff (such as the overhead of a context switch between threads) can also affect `StopWatch`'s accuracy.
  Examples:

      void writeln(S...)(S args){}
      static void bar() {}

      StopWatch sw;
      enum n = 100;
      TickDuration[n] times;
      TickDuration last = TickDuration.from!"seconds"(0);
      foreach (i; 0 .. n)
      {
         sw.start(); //start/resume mesuring.
         foreach (unused; 0 .. 1_000_000)
             bar();
         sw.stop();  //stop/pause measuring.
         //Return value of peek() after having stopped are the always same.
         writeln((i + 1) * 1_000_000, " times done, lap time: ",
                 sw.peek().msecs, "[ms]");
         times[i] = sw.peek() - last;
         last = sw.peek();
      }
      real sum = 0;
      // To get the number of seconds,
      // use properties of TickDuration.
      // (seconds, msecs, usecs, hnsecs)
      foreach (t; times)
         sum += t.hnsecs;
      writeln("Average time: ", sum/n, " hnsecs");

  @nogc @safe this(AutoStart `autostart`);
    Auto start with constructor.
  const pure nothrow @nogc @safe bool `opEquals`(const StopWatch `rhs`);
  const pure nothrow @nogc @safe bool `opEquals`(ref const StopWatch `rhs`);
  @nogc @safe void `reset`();
    Resets the stop watch.
  @nogc @safe void `start`();
    Starts the stop watch.
  @nogc @safe void `stop`();
    Stops the stop watch.
  const @nogc @safe TickDuration `peek`();
    Peek at the amount of time which has passed since the stop watch was started.
  @nogc @safe void `setMeasured`(TickDuration `d`);
    Set the amount of time which has been measured since the stop watch was started.
  const pure nothrow @nogc @property @safe bool `running`();
    Confirm whether this stopwatch is measuring time.
TickDuration[fun.length] `benchmark`(fun...)(uint `n`);
  The old benchmarking functionality in std.datetime (which uses core.time.TickDuration) has been deprecated. Use what's in std.datetime.stopwatch instead. It uses core.time.MonoTime and core.time.Duration. See std.datetime.stopwatch.benchmark. This symbol will be removed from the documentation in October 2018 and fully removed from Phobos in October 2019.
  Benchmarks code for speed assessment and comparison.
  Parameters:

  fun | aliases of callable objects (e.g. function names). Each should take no arguments.
  uint `n` | The number of times each function is to be executed.

  Returns:
  The amount of time (as a core.time.TickDuration) that it took to call each function `n` times. The first value is the length of time that it took to call fun[0] `n` times. The second value is the length of time it took to call fun[1] `n` times. Etc.
  Note that casting the TickDurations to core.time.Durations will make the results easier to deal with (and it may change in the future that benchmark will return an array of Durations rather than TickDurations).
  See Also:
  measureTime
  Examples:

      import std.conv : to;
      int a;
      void f0() {}
      void f1() {auto b = a;}
      void f2() {auto b = to!string(a);}
      auto r = benchmark!(f0, f1, f2)(10_000);
      auto f0Result = to!Duration(r[0]); // time f0 took to run 10,000 times
      auto f1Result = to!Duration(r[1]); // time f1 took to run 10,000 times
      auto f2Result = to!Duration(r[2]); // time f2 took to run 10,000 times

struct `ComparingBenchmarkResult`;
ComparingBenchmarkResult `comparingBenchmark`(alias baseFunc, alias targetFunc, int times = 4095)();
  The old benchmarking functionality in std.datetime (which uses core.time.TickDuration) has been deprecated. Use what's in std.datetime.stopwatch instead. It uses core.time.MonoTime and core.time.Duration. Note that comparingBenchmark has not been ported over, because it's a trivial wrapper around benchmark. See std.datetime.stopwatch.benchmark. This symbol will be removed from the documentation in October 2018 and fully removed from Phobos in October 2019.
  Benchmark with two functions comparing.
  Parameters:

  baseFunc | The function to become the base of the speed.
  targetFunc | The function that wants to measure speed.
  times | The number of times each function is to be executed.

  Examples:

      void f1x() {}
      void f2x() {}
      @safe void f1o() {}
      @safe void f2o() {}
      auto b1 = comparingBenchmark!(f1o, f2o, 1)(); // OK
      //writeln(b1.point);

  const pure nothrow @property @safe real `point`();
    Evaluation value
    This returns the evaluation value of performance as the ratio of baseFunc's time over targetFunc's time. If performance is high, this returns a high value.
  const pure nothrow @property @safe TickDuration `baseTime`();
    The time required of the base function
  const pure nothrow @property @safe TickDuration `targetTime`();
    The time required of the target function
@safe auto `measureTime`(alias func)()
if (isSafe!(() { StopWatch sw; unaryFun!func(sw.peek()); } ));
auto `measureTime`(alias func)()
if (!isSafe!(() { StopWatch sw; unaryFun!func(sw.peek()); } ));
  The old benchmarking functionality in std.datetime (which uses core.time.TickDuration) has been deprecated. Use what's in std.datetime.stopwatch instead. It uses core.time.MonoTime and core.time.Duration. Note that measureTime has not been ported over, because it's a trivial wrapper around StopWatch. See std.datetime.stopwatch.StopWatch. This symbol will be removed from the documentation in October 2018 and fully removed from Phobos in October 2019.
  Function for starting to a stop watch time when the function is called and stopping it when its return value goes out of scope and is destroyed.
  When the value that is returned by this function is destroyed, func will run. func is a unary function that takes a core.time.TickDuration.
  See Also:
  benchmark
  Examples:

      {
          auto mt = measureTime!((TickDuration a)
              { /+ do something when the scope is exited +/ });
          // do something that needs to be timed
      }

      // functionally equivalent to the above
      {
          auto sw = StopWatch(Yes.autoStart);
          scope(exit)
          {
              TickDuration a = sw.peek();
              /+ do something when the scope is exited +/
          }
          // do something that needs to be timed
      }

Copyright © 1999-2018 by the D Language Foundation | Page generated by Ddoc on Thu Nov 1 12:28:56 2018