Module std.datetime
Module containing Date/Time functionality.
This module provides:
- Types to represent points in time:
SysTime,Date,TimeOfDay,DateTime. - Types to represent intervals of time.
- Types to represent ranges over intervals of time.
- Types to represent time zones (used by
SysTime). - A platform-independent, high precision stopwatch type:
StopWatch - Benchmarking functions.
- Various helper functions.
Closely related to std.datetime is core,
and some of the time types used in std.datetime come from there - such as
Duration, TickDuration, and
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
Date (if they want dates but don't care about
time), DateTime (if they want dates and times
but don't care about time zones), 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).
Date and DateTime are
optimized for calendar-based operations, while
SysTime is designed for dealing with time from
the OS. Check out their specific documentation for more details.
To get the current time, use Clock.
It will return the current time as a SysTime. To
print it, toString is sufficient, but if using toISOString,
toISOExtString, or toSimpleString, use the corresponding
fromISOString, fromISOExtString, or fromSimpleString to
create a SysTime from the string.
auto currentTime = 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 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
DateTimeException is an alias for
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 TimeException or
DateTimeException).
See Also
Introduction to std.datetime
ISO 8601
Wikipedia entry on TZ Database
List of Time Zones
Functions
| Name | Description |
|---|---|
benchmark(n)
|
The old benchmarking functionality in std.datetime (which uses
TickDuration) has been deprecated. Use what's in
std.datetime.stopwatch instead. It uses MonoTime and
Duration. See
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
TickDuration) has been deprecated. Use what's in
std.datetime.stopwatch instead. It uses MonoTime and
Duration. Note that comparingBenchmark has
not been ported over, because it's a trivial wrapper around benchmark.
See 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
TickDuration) has been deprecated. Use what's in
std.datetime.stopwatch instead. It uses MonoTime and
Duration. Note that measureTime has not been ported
over, because it's a trivial wrapper around StopWatch. See
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
TickDuration) has been deprecated. Use what's in
std.datetime.stopwatch instead. It uses MonoTime and
Duration. Note that comparingBenchmark has
not been ported over, because it's a trivial wrapper around benchmark.
See 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
TickDuration) has been deprecated. Use what's in
std.datetime.stopwatch instead. It uses MonoTime and
Duration. See
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
|
Flag!("autoStart")
|
The old benchmarking functionality in std.datetime (which uses
TickDuration) has been deprecated. Use what's in
std.datetime.stopwatch instead. It uses MonoTime and
Duration. See
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