View source code Display the source code in std/datetime.d from which this page was generated on github. 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. Page wiki View or edit the community-maintained wiki page associated with this page.

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

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 DateTimeException).

See Also

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

Functions

Name Description
benchmark Benchmarks code for speed assessment and comparison.
clearTZEnvVar This function is Posix-Only.
cmpTimeUnits Compares two time unit strings. "years" are the largest units and "hnsecs" are the smallest.
comparingBenchmark Benchmark with two functions comparing.
daysToDayOfWeek Returns the number of days from the current day of the week to the given day of the week. If they are the same, then the result is 0.
DosFileTimeToSysTime Converts from DOS file date/time to SysTime.
enforceValid
enforceValid
everyDayOfWeek Range-generating function.
everyDuration Range-generating function.
everyDuration Range-generating function.
everyMonth Range-generating function.
FILETIMEToStdTime This function is Windows-Only.
FILETIMEToSysTime This function is Windows-Only.
measureTime 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.
monthsToMonth Returns the number of months from the current months of the year to the given month of the year. If they are the same, then the result is 0.
parseRFC822DateTime The given array of char or random-access range of char or ubyte is expected to be in the format specified in RFC 5322 section 3.3 with the grammar rule date-time. It is the date-time format commonly used in internet messages such as e-mail and HTTP. The corresponding SysTime will be returned.
setTZEnvVar This function is Posix-Only.
stdTimeToFILETIME This function is Windows-Only.
stdTimeToUnixTime Converts std time (which uses midnight, January 1st, 1 A.D. UTC as its epoch and hnsecs as its units) to time_t (which uses midnight, January 1st, 1970 UTC as its epoch and seconds as its units). If time_t is 32 bits, rather than 64, and the result can't fit in a 32-bit value, then the closest value that can be held in 32 bits will be used (so time_t.max if it goes over and time_t.min if it goes under).
SYSTEMTIMEToSysTime This function is Windows-Only.
SysTimeToDosFileTime Converts from SysTime to DOS file date/time.
SysTimeToFILETIME This function is Windows-Only.
SysTimeToSYSTEMTIME This function is Windows-Only.
tzDatabaseNameToWindowsTZName Converts the given TZ Database name to the corresponding Windows time zone name.
unixTimeToStdTime Converts a time_t (which uses midnight, January 1st, 1970 UTC as its epoch and seconds as its units) to std time (which uses midnight, January 1st, 1 A.D. UTC and hnsecs as its units).
valid Returns whether the given value is valid for the given unit type when in a time point. Naturally, a duration is not held to a particular range, but the values in a time point are (e.g. a month must be in the range of 1 - 12 inclusive).
valid Returns whether the given day is valid for the given year and month.
validTimeUnits Whether all of the given strings are valid units of time.
windowsTZNameToTZDatabaseName Converts the given Windows time zone name to a corresponding TZ Database name.
yearIsLeapYear Whether the given Gregorian Year is a leap year.

Classes

Name Description
Clock Effectively a namespace to make it clear that the methods it contains are getting the time from the system clock. It cannot be instantiated.
LocalTime A TimeZone which represents the current local time zone on the system running your program.
PosixTimeZone Represents a time zone from a TZ Database time zone file. Files from the TZ Database are how Posix systems hold their time zone information. Unfortunately, Windows does not use the TZ Database. To use the TZ Database, use PosixTimeZone (which reads its information from the TZ Database files on disk) on Windows by providing the TZ Database files and telling PosixTimeZone.getTimeZone where the directory holding them is.
SimpleTimeZone Represents a time zone with an offset (in minutes, west is negative) from UTC but no DST.
TimeZone Represents a time zone. It is used with SysTime to indicate the time zone of a SysTime.
UTC A .TimeZone, TimeZone which represents UTC.
WindowsTimeZone This class is Windows-Only.

Structs

Name Description
ComparingBenchmarkResult Return value of benchmark with two functions comparing.
Date Represents a date in the Proleptic Gregorian Calendar ranging from 32,768 B.C. to 32,767 A.D. Positive years are A.D. Non-positive years are B.C.
DateTime Combines the Date and TimeOfDay structs to give an object which holds both the date and the time. It is optimized for calendar-based operations and has no concept of time zone. For an object which is optimized for time operations based on the system time, use SysTime. SysTime has a concept of time zone and has much higher precision (hnsecs). DateTime is intended primarily for calendar-based uses rather than precise time operations.
Interval Represents an interval of time.
IntervalRange A range over an .Interval, Interval.
NegInfInterval Represents an interval of time which has negative infinity as its starting point.
NegInfIntervalRange A range over a NegInfInterval. It is an infinite range.
PosInfInterval Represents an interval of time which has positive infinity as its end point.
PosInfIntervalRange A range over a PosInfInterval. It is an infinite range.
StopWatch StopWatch measures time as precisely as possible.
SysTime SysTime is the type used to get the current time from the system or doing anything that involves time zones. Unlike DateTime, the time zone is an integral part of SysTime (though for local time applications, time zones can be ignored and it will work, since it defaults to using the local time zone). It holds its internal time in std time (hnsecs since midnight, January 1st, 1 A.D. UTC), so it interfaces well with the system time. However, that means that, unlike DateTime, it is not optimized for calendar-based operations, and getting individual units from it such as years or days is going to involve conversions and be less efficient.
TimeOfDay Represents a time of day with hours, minutes, and seconds. It uses 24 hour time.

Enums

Name Description
AllowDayOverflow In some date calculations, adding months or years can cause the date to fall on a day of the month which is not valid (e.g. February 29th 2001 or June 31st 2000). If overflow is allowed (as is the default), then the month will be incremented accordingly (so, February 29th 2001 would become March 1st 2001, and June 31st 2000 would become July 1st 2000). If overflow is not allowed, then the day will be adjusted to the last valid day in that month (so, February 29th 2001 would become February 28th 2001 and June 31st 2000 would become June 30th 2000).
AutoStart Used by StopWatch to indicate whether it should start immediately upon construction.
DayOfWeek Represents the 7 days of the Gregorian week (Sunday is 0).
Direction Indicates a direction in time. One example of its use is .Interval, Interval's expand function which uses it to indicate whether the interval should be expanded backwards (into the past), forwards (into the future), or both.
Month Represents the 12 months of the Gregorian year (January is 1).
PopFirst Used to indicate whether popFront should be called immediately upon creating a range. The idea is that for some functions used to generate a range for an interval, front is not necessarily a time point which would ever be generated by the range. To get the first time point in the range to match what the function generates, then use PopFirst.yes to indicate that the range should have popFront called on it before the range is returned so that front is a time point which the function would generate.

Enum values

Name Type Description
CmpTimeUnits Compares two time unit strings at compile time. "years" are the largest units and "hnsecs" are the smallest.
isTimePoint Whether the given type defines all of the necessary functions for it to function as a time point.

Global variables

Name Type Description
timeStrings immutable(char[][]) Array of the strings representing time units, starting with the smallest unit and going to the largest. It does not include "nsecs".

Aliases

Name Type Description
DateTimeException TimeException Exception type used by std.datetime. It's an alias to core.time.TimeException. Either can be caught without concern about which module it came from.
DosFileTime uint Type representing the DOS file date/time format.

Authors

Jonathan M Davis and Kato Shoichi

License

Boost License 1.0.

Comments