View source code
Display the source code in std/datetime/package.d from which this page was generated on github.
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 local clone.

Module std.datetime

Module containing Date/Time functionality.

This module provides:

Closely related to std.datetime is core.time, and some of the time types used in std.datetime come from there - such as core.time.Duration, core.time.TickDuration, and core.time.FracSec. core.time is publically imported into std.datetime, it isn't necessary to import it separately.

Three of the main concepts used in this module are time points, time durations, and time intervals.

A time point is a specific point in time. e.g. January 5th, 2010 or 5:00.

A time duration is a length of time with units. e.g. 5 days or 231 seconds.

A time interval indicates a period of time associated with a fixed point in time. It is either two time points associated with each other, indicating the time starting at the first point up to, but not including, the second point - e.g. [January 5th, 2010 - March 10th, 2010) - or it is a time point and a time duration associated with one another. e.g. January 5th, 2010 and 5 days, indicating [January 5th, 2010 - January 10th, 2010).

Various arithmetic operations are supported between time points and durations (e.g. the difference between two time points is a time duration), and ranges can be gotten from time intervals, so range-based operations may be done on a series of time points.

The types that the typical user is most likely to be interested in are std.datetime.date.Date (if they want dates but don't care about time), std.datetime.date.DateTime (if they want dates and times but don't care about time zones), std.datetime.systime.SysTime (if they want the date and time from the OS and/or do care about time zones), and StopWatch (a platform-independent, high precision stop watch). std.datetime.date.Date and std.datetime.date.DateTime are optimized for calendar-based operations, while std.datetime.systime.SysTime is designed for dealing with time from the OS. Check out their specific documentation for more details.

To get the current time, use std.datetime.systime.Clock.currTime. It will return the current time as a std.datetime.systime.SysTime. To print it, toString is sufficient, but if using toISOString, toISOExtString, or toSimpleString, use the corresponding fromISOString, fromISOExtString, or fromSimpleString to create a std.datetime.systime.SysTime from the string.

auto currentTime = Clock.currTime();
auto timeString = currentTime.toISOExtString();
auto restoredTime = SysTime.fromISOExtString(timeString);

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 in core.time which take "nsecs", but because nothing in std.datetime has precision greater than hnsecs, and very little in core.time does, no functions in std.datetime accept "nsecs". To remember which units are abbreviated and which aren't, all units seconds and greater use their full names, and all sub-second units are abbreviated (since they'd be rather long if they weren't).

Note

std.datetime.date.DateTimeException is an alias for core.time.TimeException, so you don't need to worry about core.time functions and std.datetime functions throwing different exception types (except in the rare case that they throw something other than core.time.TimeException or std.datetime.date.DateTimeException).

See Also

Introduction to std.datetime
ISO 8601
Wikipedia entry on TZ Database
List of Time Zones

Functions

Name Description
benchmark 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.
comparingBenchmark 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.
measureTime 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.

Structs

Name Description
ComparingBenchmarkResult 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.
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.

Aliases

Name Type Description
AutoStart std.typecons 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.

Authors

Jonathan M Davis and Kato Shoichi

License

Boost License 1.0.

Comments