W3cubDocs

/D

std.datetime.date

License:
Boost License 1.0.
Authors:
Jonathan M Davis
Source
std/datetime/date.d
alias DateTimeException = core.time.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.

enum Month: ubyte

Represents the 12 months of the Gregorian year (January is 1).

jan
feb
mar
apr
may
jun
jul
aug
sep
oct
nov
dec
enum DayOfWeek: ubyte

Represents the 7 days of the Gregorian week (Sunday is 0).

sun
mon
tue
wed
thu
fri
sat
alias AllowDayOverflow = std.typecons.Flag!"allowDayOverflow".Flag

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

AllowDayOverflow only applies to calculations involving months or years.

If set to AllowDayOverflow.no, then day overflow is not allowed.

Otherwise, if set to AllowDayOverflow.yes, then day overflow is allowed.

immutable string[] timeStrings

Array of the strings representing time units, starting with the smallest unit and going to the largest. It does not include "nsecs".

Includes "hnsecs" (hecto-nanoseconds (100 ns)), "usecs" (microseconds), "msecs" (milliseconds), "seconds", "minutes", "hours", "days", "weeks", "months", and "years"

struct DateTime

Combines the std.datetime.date.Date and std.datetime.date.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 std.datetime.systime.SysTime. std.datetime.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.

pure nothrow @nogc @safe this(in Date date, in TimeOfDay tod = TimeOfDay.init)
Parameters:
Date date The date portion of DateTime.
TimeOfDay tod The time portion of DateTime.
pure @safe this(int year, int month, int day, int hour = 0, int minute = 0, int second = 0)
Parameters:
int year The year portion of the date.
int month The month portion of the date (January is 1).
int day The day portion of the date.
int hour The hour portion of the time;
int minute The minute portion of the time;
int second The second portion of the time;
const pure nothrow @nogc @safe int opCmp(in DateTime rhs)

Compares this DateTime with the given DateTime..

Returns:
this < rhs < 0
this == rhs 0
this > rhs > 0
const pure nothrow @nogc @property @safe Date date()

The date portion of DateTime.

pure nothrow @nogc @property @safe void date(in Date date)

The date portion of DateTime.

Parameters:
Date date The Date to set this DateTime's date portion to.
const pure nothrow @nogc @property @safe TimeOfDay timeOfDay()

The time portion of DateTime.

pure nothrow @nogc @property @safe void timeOfDay(in TimeOfDay tod)

The time portion of DateTime.

Parameters:
TimeOfDay tod The std.datetime.date.TimeOfDay to set this DateTime's time portion to.
const pure nothrow @nogc @property @safe short year()

Year of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.

pure @property @safe void year(int year)

Year of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.

Parameters:
int year The year to set this DateTime's year to.
Throws:
std.datetime.date.DateTimeException if the new year is not a leap year and if the resulting date would be on February 29th.
Examples:
writeln(DateTime(Date(1999, 7, 6), TimeOfDay(9, 7, 5)).year); // 1999
writeln(DateTime(Date(2010, 10, 4), TimeOfDay(0, 0, 30)).year); // 2010
writeln(DateTime(Date(-7, 4, 5), TimeOfDay(7, 45, 2)).year); // -7
const pure @property @safe short yearBC()

Year B.C. of the Gregorian Calendar counting year 0 as 1 B.C.

Throws:
std.datetime.date.DateTimeException if isAD is true.
Examples:
writeln(DateTime(Date(0, 1, 1), TimeOfDay(12, 30, 33)).yearBC); // 1
writeln(DateTime(Date(-1, 1, 1), TimeOfDay(10, 7, 2)).yearBC); // 2
writeln(DateTime(Date(-100, 1, 1), TimeOfDay(4, 59, 0)).yearBC); // 101
pure @property @safe void yearBC(int year)

Year B.C. of the Gregorian Calendar counting year 0 as 1 B.C.

Parameters:
int year The year B.C. to set this DateTime's year to.
Throws:
std.datetime.date.DateTimeException if a non-positive value is given.
Examples:
auto dt = DateTime(Date(2010, 1, 1), TimeOfDay(7, 30, 0));
dt.yearBC = 1;
writeln(dt); // DateTime(Date(0, 1, 1), TimeOfDay(7, 30, 0))

dt.yearBC = 10;
writeln(dt); // DateTime(Date(-9, 1, 1), TimeOfDay(7, 30, 0))
const pure nothrow @nogc @property @safe Month month()

Month of a Gregorian Year.

Examples:
writeln(DateTime(Date(1999, 7, 6), TimeOfDay(9, 7, 5)).month); // 7
writeln(DateTime(Date(2010, 10, 4), TimeOfDay(0, 0, 30)).month); // 10
writeln(DateTime(Date(-7, 4, 5), TimeOfDay(7, 45, 2)).month); // 4
pure @property @safe void month(Month month)

Month of a Gregorian Year.

Parameters:
Month month The month to set this DateTime's month to.
Throws:
std.datetime.date.DateTimeException if the given month is not a valid month.
const pure nothrow @nogc @property @safe ubyte day()

Day of a Gregorian Month.

Examples:
writeln(DateTime(Date(1999, 7, 6), TimeOfDay(9, 7, 5)).day); // 6
writeln(DateTime(Date(2010, 10, 4), TimeOfDay(0, 0, 30)).day); // 4
writeln(DateTime(Date(-7, 4, 5), TimeOfDay(7, 45, 2)).day); // 5
pure @property @safe void day(int day)

Day of a Gregorian Month.

Parameters:
int day The day of the month to set this DateTime's day to.
Throws:
std.datetime.date.DateTimeException if the given day is not a valid day of the current month.
const pure nothrow @nogc @property @safe ubyte hour()

Hours past midnight.

pure @property @safe void hour(int hour)

Hours past midnight.

Parameters:
int hour The hour of the day to set this DateTime's hour to.
Throws:
std.datetime.date.DateTimeException if the given hour would result in an invalid DateTime.
const pure nothrow @nogc @property @safe ubyte minute()

Minutes past the hour.

pure @property @safe void minute(int minute)

Minutes past the hour.

Parameters:
int minute The minute to set this DateTime's minute to.
Throws:
std.datetime.date.DateTimeException if the given minute would result in an invalid DateTime.
const pure nothrow @nogc @property @safe ubyte second()

Seconds past the minute.

pure @property @safe void second(int second)

Seconds past the minute.

Parameters:
int second The second to set this DateTime's second to.
Throws:
std.datetime.date.DateTimeException if the given seconds would result in an invalid DateTime.
pure nothrow @nogc ref @safe DateTime add(string units)(long value, AllowDayOverflow allowOverflow = AllowDayOverflow.yes)

Constraints:
if (units == "years" || units == "months")

Adds the given number of years or months to this DateTime. A negative number will subtract.

Note that if day overflow is allowed, and the date with the adjusted year/month overflows the number of days in the new month, then the month will be incremented by one, and the day set to the number of days overflowed. (e.g. if the day were 31 and the new month were June, then the month would be incremented to July, and the new day would be 1). If day overflow is not allowed, then the day will be set to the last valid day in the month (e.g. June 31st would become June 30th).

Parameters:
units The type of units to add ("years" or "months").
long value The number of months or years to add to this DateTime.
AllowDayOverflow allowOverflow Whether the days should be allowed to overflow, causing the month to increment.
Examples:
auto dt1 = DateTime(2010, 1, 1, 12, 30, 33);
dt1.add!"months"(11);
writeln(dt1); // DateTime(2010, 12, 1, 12, 30, 33)

auto dt2 = DateTime(2010, 1, 1, 12, 30, 33);
dt2.add!"months"(-11);
writeln(dt2); // DateTime(2009, 2, 1, 12, 30, 33)

auto dt3 = DateTime(2000, 2, 29, 12, 30, 33);
dt3.add!"years"(1);
writeln(dt3); // DateTime(2001, 3, 1, 12, 30, 33)

auto dt4 = DateTime(2000, 2, 29, 12, 30, 33);
dt4.add!"years"(1, AllowDayOverflow.no);
writeln(dt4); // DateTime(2001, 2, 28, 12, 30, 33)
pure nothrow @nogc ref @safe DateTime roll(string units)(long value, AllowDayOverflow allowOverflow = AllowDayOverflow.yes)

Constraints:
if (units == "years" || units == "months")

Adds the given number of years or months to this DateTime. A negative number will subtract.

The difference between rolling and adding is that rolling does not affect larger units. Rolling a DateTime 12 months gets the exact same DateTime. However, the days can still be affected due to the differing number of days in each month.

Because there are no units larger than years, there is no difference between adding and rolling years.

Parameters:
units The type of units to add ("years" or "months").
long value The number of months or years to add to this DateTime.
AllowDayOverflow allowOverflow Whether the days should be allowed to overflow, causing the month to increment.
Examples:
auto dt1 = DateTime(2010, 1, 1, 12, 33, 33);
dt1.roll!"months"(1);
writeln(dt1); // DateTime(2010, 2, 1, 12, 33, 33)

auto dt2 = DateTime(2010, 1, 1, 12, 33, 33);
dt2.roll!"months"(-1);
writeln(dt2); // DateTime(2010, 12, 1, 12, 33, 33)

auto dt3 = DateTime(1999, 1, 29, 12, 33, 33);
dt3.roll!"months"(1);
writeln(dt3); // DateTime(1999, 3, 1, 12, 33, 33)

auto dt4 = DateTime(1999, 1, 29, 12, 33, 33);
dt4.roll!"months"(1, AllowDayOverflow.no);
writeln(dt4); // DateTime(1999, 2, 28, 12, 33, 33)

auto dt5 = DateTime(2000, 2, 29, 12, 30, 33);
dt5.roll!"years"(1);
writeln(dt5); // DateTime(2001, 3, 1, 12, 30, 33)

auto dt6 = DateTime(2000, 2, 29, 12, 30, 33);
dt6.roll!"years"(1, AllowDayOverflow.no);
writeln(dt6); // DateTime(2001, 2, 28, 12, 30, 33)
pure nothrow @nogc ref @safe DateTime roll(string units)(long value)

Constraints:
if (units == "days")

Adds the given number of units to this DateTime. A negative number will subtract.

The difference between rolling and adding is that rolling does not affect larger units. For instance, rolling a DateTime one year's worth of days gets the exact same DateTime.

Accepted units are "days", "minutes", "hours", "minutes", and "seconds".

Parameters:
units The units to add.
long value The number of units to add to this DateTime.
Examples:
auto dt1 = DateTime(2010, 1, 1, 11, 23, 12);
dt1.roll!"days"(1);
writeln(dt1); // DateTime(2010, 1, 2, 11, 23, 12)
dt1.roll!"days"(365);
writeln(dt1); // DateTime(2010, 1, 26, 11, 23, 12)
dt1.roll!"days"(-32);
writeln(dt1); // DateTime(2010, 1, 25, 11, 23, 12)

auto dt2 = DateTime(2010, 7, 4, 12, 0, 0);
dt2.roll!"hours"(1);
writeln(dt2); // DateTime(2010, 7, 4, 13, 0, 0)

auto dt3 = DateTime(2010, 1, 1, 0, 0, 0);
dt3.roll!"seconds"(-1);
writeln(dt3); // DateTime(2010, 1, 1, 0, 0, 59)
const pure nothrow @nogc @safe DateTime opBinary(string op)(Duration duration)

Constraints:
if (op == "+" || op == "-")

Gives the result of adding or subtracting a core.time.Duration from this DateTime.

The legal types of arithmetic for DateTime using this operator are

DateTime + Duration --> DateTime
DateTime - Duration --> DateTime
Parameters:
Duration duration The core.time.Duration to add to or subtract from this DateTime.
Examples:
import core.time : hours, seconds;

assert(DateTime(2015, 12, 31, 23, 59, 59) + seconds(1) ==
       DateTime(2016, 1, 1, 0, 0, 0));

assert(DateTime(2015, 12, 31, 23, 59, 59) + hours(1) ==
       DateTime(2016, 1, 1, 0, 59, 59));

assert(DateTime(2016, 1, 1, 0, 0, 0) - seconds(1) ==
       DateTime(2015, 12, 31, 23, 59, 59));

assert(DateTime(2016, 1, 1, 0, 59, 59) - hours(1) ==
       DateTime(2015, 12, 31, 23, 59, 59));
pure nothrow @nogc ref @safe DateTime opOpAssign(string op, D)(in D duration)

Constraints:
if ((op == "+" || op == "-") && (is(Unqual!D == Duration) || is(Unqual!D == TickDuration)))

Gives the result of adding or subtracting a duration from this DateTime, as well as assigning the result to this DateTime.

The legal types of arithmetic for DateTime using this operator are

DateTime + duration --> DateTime
DateTime - duration --> DateTime
Parameters:
D duration The duration to add to or subtract from this DateTime.
const pure nothrow @nogc @safe Duration opBinary(string op)(in DateTime rhs)

Constraints:
if (op == "-")

Gives the difference between two DateTimes.

The legal types of arithmetic for DateTime using this operator are

DateTime - DateTime --> duration
const pure nothrow @nogc @safe int diffMonths(in DateTime rhs)

Returns the difference between the two DateTimes in months.

To get the difference in years, subtract the year property of two DateTimes. To get the difference in days or weeks, subtract the DateTimes themselves and use the core.time.Duration that results. Because converting between months and smaller units requires a specific date (which core.time.Durations don't have), getting the difference in months requires some math using both the year and month properties, so this is a convenience function for getting the difference in months.

Note that the number of days in the months or how far into the month either date is is irrelevant. It is the difference in the month property combined with the difference in years * 12. So, for instance, December 31st and January 1st are one month apart just as December 1st and January 31st are one month apart.

Parameters:
DateTime rhs The DateTime to subtract from this one.
Examples:
assert(DateTime(1999, 2, 1, 12, 2, 3).diffMonths(
           DateTime(1999, 1, 31, 23, 59, 59)) == 1);

assert(DateTime(1999, 1, 31, 0, 0, 0).diffMonths(
           DateTime(1999, 2, 1, 12, 3, 42)) == -1);

assert(DateTime(1999, 3, 1, 5, 30, 0).diffMonths(
           DateTime(1999, 1, 1, 2, 4, 7)) == 2);

assert(DateTime(1999, 1, 1, 7, 2, 4).diffMonths(
           DateTime(1999, 3, 31, 0, 30, 58)) == -2);
const pure nothrow @nogc @property @safe bool isLeapYear()

Whether this DateTime is in a leap year.

const pure nothrow @nogc @property @safe DayOfWeek dayOfWeek()

Day of the week this DateTime is on.

const pure nothrow @nogc @property @safe ushort dayOfYear()

Day of the year this DateTime is on.

Examples:
writeln(DateTime(Date(1999, 1, 1), TimeOfDay(12, 22, 7)).dayOfYear); // 1
writeln(DateTime(Date(1999, 12, 31), TimeOfDay(7, 2, 59)).dayOfYear); // 365
writeln(DateTime(Date(2000, 12, 31), TimeOfDay(21, 20, 0)).dayOfYear); // 366
pure @property @safe void dayOfYear(int day)

Day of the year.

Parameters:
int day The day of the year to set which day of the year this DateTime is on.
const pure nothrow @nogc @property @safe int dayOfGregorianCal()

The Xth day of the Gregorian Calendar that this DateTime is on.

Examples:
writeln(DateTime(Date(1, 1, 1), TimeOfDay(0, 0, 0)).dayOfGregorianCal); // 1
writeln(DateTime(Date(1, 12, 31), TimeOfDay(23, 59, 59)).dayOfGregorianCal); // 365
writeln(DateTime(Date(2, 1, 1), TimeOfDay(2, 2, 2)).dayOfGregorianCal); // 366

writeln(DateTime(Date(0, 12, 31), TimeOfDay(7, 7, 7)).dayOfGregorianCal); // 0
writeln(DateTime(Date(0, 1, 1), TimeOfDay(19, 30, 0)).dayOfGregorianCal); // -365
writeln(DateTime(Date(-1, 12, 31), TimeOfDay(4, 7, 0)).dayOfGregorianCal); // -366

writeln(DateTime(Date(2000, 1, 1), TimeOfDay(9, 30, 20)).dayOfGregorianCal); // 730_120
writeln(DateTime(Date(2010, 12, 31), TimeOfDay(15, 45, 50)).dayOfGregorianCal); // 734_137
pure nothrow @nogc @property @safe void dayOfGregorianCal(int days)

The Xth day of the Gregorian Calendar that this DateTime is on. Setting this property does not affect the time portion of DateTime.

Parameters:
int days The day of the Gregorian Calendar to set this DateTime to.
Examples:
auto dt = DateTime(Date.init, TimeOfDay(12, 0, 0));
dt.dayOfGregorianCal = 1;
writeln(dt); // DateTime(Date(1, 1, 1), TimeOfDay(12, 0, 0))

dt.dayOfGregorianCal = 365;
writeln(dt); // DateTime(Date(1, 12, 31), TimeOfDay(12, 0, 0))

dt.dayOfGregorianCal = 366;
writeln(dt); // DateTime(Date(2, 1, 1), TimeOfDay(12, 0, 0))

dt.dayOfGregorianCal = 0;
writeln(dt); // DateTime(Date(0, 12, 31), TimeOfDay(12, 0, 0))

dt.dayOfGregorianCal = -365;
writeln(dt); // DateTime(Date(-0, 1, 1), TimeOfDay(12, 0, 0))

dt.dayOfGregorianCal = -366;
writeln(dt); // DateTime(Date(-1, 12, 31), TimeOfDay(12, 0, 0))

dt.dayOfGregorianCal = 730_120;
writeln(dt); // DateTime(Date(2000, 1, 1), TimeOfDay(12, 0, 0))

dt.dayOfGregorianCal = 734_137;
writeln(dt); // DateTime(Date(2010, 12, 31), TimeOfDay(12, 0, 0))
const pure nothrow @property @safe ubyte isoWeek()

The ISO 8601 week of the year that this DateTime is in.

See Also:
ISO Week Date
const pure nothrow @property @safe DateTime endOfMonth()

DateTime for the last day in the month that this DateTime is in. The time portion of endOfMonth is always 23:59:59.

Examples:
assert(DateTime(Date(1999, 1, 6), TimeOfDay(0, 0, 0)).endOfMonth ==
       DateTime(Date(1999, 1, 31), TimeOfDay(23, 59, 59)));

assert(DateTime(Date(1999, 2, 7), TimeOfDay(19, 30, 0)).endOfMonth ==
       DateTime(Date(1999, 2, 28), TimeOfDay(23, 59, 59)));

assert(DateTime(Date(2000, 2, 7), TimeOfDay(5, 12, 27)).endOfMonth ==
       DateTime(Date(2000, 2, 29), TimeOfDay(23, 59, 59)));

assert(DateTime(Date(2000, 6, 4), TimeOfDay(12, 22, 9)).endOfMonth ==
       DateTime(Date(2000, 6, 30), TimeOfDay(23, 59, 59)));
const pure nothrow @nogc @property @safe ubyte daysInMonth()

The last day in the month that this DateTime is in.

Examples:
writeln(DateTime(Date(1999, 1, 6), TimeOfDay(0, 0, 0)).daysInMonth); // 31
writeln(DateTime(Date(1999, 2, 7), TimeOfDay(19, 30, 0)).daysInMonth); // 28
writeln(DateTime(Date(2000, 2, 7), TimeOfDay(5, 12, 27)).daysInMonth); // 29
writeln(DateTime(Date(2000, 6, 4), TimeOfDay(12, 22, 9)).daysInMonth); // 30
const pure nothrow @nogc @property @safe bool isAD()

Whether the current year is a date in A.D.

Examples:
assert(DateTime(Date(1, 1, 1), TimeOfDay(12, 7, 0)).isAD);
assert(DateTime(Date(2010, 12, 31), TimeOfDay(0, 0, 0)).isAD);
assert(!DateTime(Date(0, 12, 31), TimeOfDay(23, 59, 59)).isAD);
assert(!DateTime(Date(-2010, 1, 1), TimeOfDay(2, 2, 2)).isAD);
const pure nothrow @nogc @property @safe long julianDay()

The Julian day for this DateTime at the given time. For example, prior to noon, 1996-03-31 would be the Julian day number 2_450_173, so this function returns 2_450_173, while from noon onward, the julian day number would be 2_450_174, so this function returns 2_450_174.

const pure nothrow @nogc @property @safe long modJulianDay()

The modified Julian day for any time on this date (since, the modified Julian day changes at midnight).

const pure nothrow @safe string toISOString()

Converts this DateTime to a string with the format YYYYMMDDTHHMMSS.

Examples:
assert(DateTime(Date(2010, 7, 4), TimeOfDay(7, 6, 12)).toISOString() ==
       "20100704T070612");

assert(DateTime(Date(1998, 12, 25), TimeOfDay(2, 15, 0)).toISOString() ==
       "19981225T021500");

assert(DateTime(Date(0, 1, 5), TimeOfDay(23, 9, 59)).toISOString() ==
       "00000105T230959");

assert(DateTime(Date(-4, 1, 5), TimeOfDay(0, 0, 2)).toISOString() ==
       "-00040105T000002");
const pure nothrow @safe string toISOExtString()

Converts this DateTime to a string with the format YYYY-MM-DDTHH:MM:SS.

Examples:
assert(DateTime(Date(2010, 7, 4), TimeOfDay(7, 6, 12)).toISOExtString() ==
       "2010-07-04T07:06:12");

assert(DateTime(Date(1998, 12, 25), TimeOfDay(2, 15, 0)).toISOExtString() ==
       "1998-12-25T02:15:00");

assert(DateTime(Date(0, 1, 5), TimeOfDay(23, 9, 59)).toISOExtString() ==
       "0000-01-05T23:09:59");

assert(DateTime(Date(-4, 1, 5), TimeOfDay(0, 0, 2)).toISOExtString() ==
       "-0004-01-05T00:00:02");
const pure nothrow @safe string toSimpleString()

Converts this DateTime to a string with the format YYYY-Mon-DD HH:MM:SS.

Examples:
assert(DateTime(Date(2010, 7, 4), TimeOfDay(7, 6, 12)).toSimpleString() ==
       "2010-Jul-04 07:06:12");

assert(DateTime(Date(1998, 12, 25), TimeOfDay(2, 15, 0)).toSimpleString() ==
       "1998-Dec-25 02:15:00");

assert(DateTime(Date(0, 1, 5), TimeOfDay(23, 9, 59)).toSimpleString() ==
       "0000-Jan-05 23:09:59");

assert(DateTime(Date(-4, 1, 5), TimeOfDay(0, 0, 2)).toSimpleString() ==
       "-0004-Jan-05 00:00:02");
const pure nothrow @safe string toString()

Converts this DateTime to a string.

This function exists to make it easy to convert a DateTime to a string for code that does not care what the exact format is - just that it presents the information in a clear manner. It also makes it easy to simply convert a DateTime to a string when using functions such as to!string, format, or writeln which use toString to convert user-defined types. So, it is unlikely that much code will call toString directly.

The format of the string is purposefully unspecified, and code that cares about the format of the string should use toISOString, toISOExtString, toSimpleString, or some other custom formatting function that explicitly generates the format that the code needs. The reason is that the code is then clear about what format it's using, making it less error-prone to maintain the code and interact with other software that consumes the generated strings. It's for this same reason that DateTime has no fromString function, whereas it does have fromISOString, fromISOExtString, and fromSimpleString.

The format returned by toString may or may not change in the future.

pure @safe DateTime fromISOString(S)(in S isoString)

Constraints:
if (isSomeString!S)

Creates a DateTime from a string with the format YYYYMMDDTHHMMSS. Whitespace is stripped from the given string.

Parameters:
S isoString A string formatted in the ISO format for dates and times.
Throws:
std.datetime.date.DateTimeException if the given string is not in the ISO format or if the resulting DateTime would not be valid.
pure @safe DateTime fromISOExtString(S)(in S isoExtString)

Constraints:
if (isSomeString!S)

Creates a DateTime from a string with the format YYYY-MM-DDTHH:MM:SS. Whitespace is stripped from the given string.

Parameters:
S isoExtString A string formatted in the ISO Extended format for dates and times.
Throws:
std.datetime.date.DateTimeException if the given string is not in the ISO Extended format or if the resulting DateTime would not be valid.
pure @safe DateTime fromSimpleString(S)(in S simpleString)

Constraints:
if (isSomeString!S)

Creates a DateTime from a string with the format YYYY-Mon-DD HH:MM:SS. Whitespace is stripped from the given string.

Parameters:
S simpleString A string formatted in the way that toSimpleString formats dates and times.
Throws:
std.datetime.date.DateTimeException if the given string is not in the correct format or if the resulting DateTime would not be valid.
static pure nothrow @nogc @property @safe DateTime min()

Returns the DateTime farthest in the past which is representable by DateTime.

static pure nothrow @nogc @property @safe DateTime max()

Returns the DateTime farthest in the future which is representable by DateTime.

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

Year, month, and day are kept separately internally so that Date is optimized for calendar-based operations.

Date uses the Proleptic Gregorian Calendar, so it assumes the Gregorian leap year calculations for its entire length. As per ISO 8601, it treats 1 B.C. as year 0, i.e. 1 B.C. is 0, 2 B.C. is -1, etc. Use yearBC to use B.C. as a positive integer with 1 B.C. being the year prior to 1 A.D.

Year 0 is a leap year.

pure @safe this(int year, int month, int day)
Throws:
std.datetime.date.DateTimeException if the resulting Date would not be valid.
Parameters:
int year Year of the Gregorian Calendar. Positive values are A.D. Non-positive values are B.C. with year 0 being the year prior to 1 A.D.
int month Month of the year (January is 1).
int day Day of the month.
pure nothrow @nogc @safe this(int day)
Parameters:
int day The Xth day of the Gregorian Calendar that the constructed Date will be for.
const pure nothrow @nogc @safe int opCmp(in Date rhs)

Compares this Date with the given Date.

Returns:
this < rhs < 0
this == rhs 0
this > rhs > 0
const pure nothrow @nogc @property @safe short year()

Year of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.

Examples:
writeln(Date(1999, 7, 6).year); // 1999
writeln(Date(2010, 10, 4).year); // 2010
writeln(Date(-7, 4, 5).year); // -7
pure @property @safe void year(int year)

Year of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.

Parameters:
int year The year to set this Date's year to.
Throws:
std.datetime.date.DateTimeException if the new year is not a leap year and the resulting date would be on February 29th.
Examples:
writeln(Date(1999, 7, 6).year); // 1999
writeln(Date(2010, 10, 4).year); // 2010
writeln(Date(-7, 4, 5).year); // -7
const pure @property @safe ushort yearBC()

Year B.C. of the Gregorian Calendar counting year 0 as 1 B.C.

Throws:
std.datetime.date.DateTimeException if isAD is true.
Examples:
writeln(Date(0, 1, 1).yearBC); // 1
writeln(Date(-1, 1, 1).yearBC); // 2
writeln(Date(-100, 1, 1).yearBC); // 101
pure @property @safe void yearBC(int year)

Year B.C. of the Gregorian Calendar counting year 0 as 1 B.C.

Parameters:
int year The year B.C. to set this Date's year to.
Throws:
std.datetime.date.DateTimeException if a non-positive value is given.
Examples:
auto date = Date(2010, 1, 1);
date.yearBC = 1;
writeln(date); // Date(0, 1, 1)

date.yearBC = 10;
writeln(date); // Date(-9, 1, 1)
const pure nothrow @nogc @property @safe Month month()

Month of a Gregorian Year.

Examples:
writeln(Date(1999, 7, 6).month); // 7
writeln(Date(2010, 10, 4).month); // 10
writeln(Date(-7, 4, 5).month); // 4
pure @property @safe void month(Month month)

Month of a Gregorian Year.

Parameters:
Month month The month to set this Date's month to.
Throws:
std.datetime.date.DateTimeException if the given month is not a valid month or if the current day would not be valid in the given month.
const pure nothrow @nogc @property @safe ubyte day()

Day of a Gregorian Month.

Examples:
writeln(Date(1999, 7, 6).day); // 6
writeln(Date(2010, 10, 4).day); // 4
writeln(Date(-7, 4, 5).day); // 5
pure @property @safe void day(int day)

Day of a Gregorian Month.

Parameters:
int day The day of the month to set this Date's day to.
Throws:
std.datetime.date.DateTimeException if the given day is not a valid day of the current month.
pure nothrow @nogc ref @safe Date add(string units)(long value, AllowDayOverflow allowOverflow = AllowDayOverflow.yes)

Constraints:
if (units == "years")

Adds the given number of years or months to this Date. A negative number will subtract.

Note that if day overflow is allowed, and the date with the adjusted year/month overflows the number of days in the new month, then the month will be incremented by one, and the day set to the number of days overflowed. (e.g. if the day were 31 and the new month were June, then the month would be incremented to July, and the new day would be 1). If day overflow is not allowed, then the day will be set to the last valid day in the month (e.g. June 31st would become June 30th).

Parameters:
units The type of units to add ("years" or "months").
long value The number of months or years to add to this Date.
AllowDayOverflow allowOverflow Whether the day should be allowed to overflow, causing the month to increment.
Examples:
auto d1 = Date(2010, 1, 1);
d1.add!"months"(11);
writeln(d1); // Date(2010, 12, 1)

auto d2 = Date(2010, 1, 1);
d2.add!"months"(-11);
writeln(d2); // Date(2009, 2, 1)

auto d3 = Date(2000, 2, 29);
d3.add!"years"(1);
writeln(d3); // Date(2001, 3, 1)

auto d4 = Date(2000, 2, 29);
d4.add!"years"(1, AllowDayOverflow.no);
writeln(d4); // Date(2001, 2, 28)
pure nothrow @nogc ref @safe Date roll(string units)(long value, AllowDayOverflow allowOverflow = AllowDayOverflow.yes)

Constraints:
if (units == "years")

Adds the given number of years or months to this Date. A negative number will subtract.

The difference between rolling and adding is that rolling does not affect larger units. Rolling a Date 12 months gets the exact same Date. However, the days can still be affected due to the differing number of days in each month.

Because there are no units larger than years, there is no difference between adding and rolling years.

Parameters:
units The type of units to add ("years" or "months").
long value The number of months or years to add to this Date.
AllowDayOverflow allowOverflow Whether the day should be allowed to overflow, causing the month to increment.
Examples:
auto d1 = Date(2010, 1, 1);
d1.roll!"months"(1);
writeln(d1); // Date(2010, 2, 1)

auto d2 = Date(2010, 1, 1);
d2.roll!"months"(-1);
writeln(d2); // Date(2010, 12, 1)

auto d3 = Date(1999, 1, 29);
d3.roll!"months"(1);
writeln(d3); // Date(1999, 3, 1)

auto d4 = Date(1999, 1, 29);
d4.roll!"months"(1, AllowDayOverflow.no);
writeln(d4); // Date(1999, 2, 28)

auto d5 = Date(2000, 2, 29);
d5.roll!"years"(1);
writeln(d5); // Date(2001, 3, 1)

auto d6 = Date(2000, 2, 29);
d6.roll!"years"(1, AllowDayOverflow.no);
writeln(d6); // Date(2001, 2, 28)
pure nothrow @nogc ref @safe Date roll(string units)(long days)

Constraints:
if (units == "days")

Adds the given number of units to this Date. A negative number will subtract.

The difference between rolling and adding is that rolling does not affect larger units. For instance, rolling a Date one year's worth of days gets the exact same Date.

The only accepted units are "days".

Parameters:
units The units to add. Must be "days".
long days The number of days to add to this Date.
Examples:
auto d = Date(2010, 1, 1);
d.roll!"days"(1);
writeln(d); // Date(2010, 1, 2)
d.roll!"days"(365);
writeln(d); // Date(2010, 1, 26)
d.roll!"days"(-32);
writeln(d); // Date(2010, 1, 25)
const pure nothrow @nogc @safe Date opBinary(string op)(Duration duration)

Constraints:
if (op == "+" || op == "-")

Gives the result of adding or subtracting a core.time.Duration from

The legal types of arithmetic for Date using this operator are

Date + Duration --> Date
Date - Duration --> Date
Parameters:
Duration duration The core.time.Duration to add to or subtract from this Date.
Examples:
import core.time : days;

writeln(Date(2015, 12, 31) + days(1)); // Date(2016, 1, 1)
writeln(Date(2004, 2, 26) + days(4)); // Date(2004, 3, 1)

writeln(Date(2016, 1, 1) - days(1)); // Date(2015, 12, 31)
writeln(Date(2004, 3, 1) - days(4)); // Date(2004, 2, 26)
pure nothrow @nogc ref @safe Date opOpAssign(string op)(Duration duration)

Constraints:
if (op == "+" || op == "-")

Gives the result of adding or subtracting a core.time.Duration from this Date, as well as assigning the result to this Date.

The legal types of arithmetic for Date using this operator are

Date + Duration --> Date
Date - Duration --> Date
Parameters:
Duration duration The core.time.Duration to add to or subtract from this Date.
const pure nothrow @nogc @safe Duration opBinary(string op)(in Date rhs)

Constraints:
if (op == "-")

Gives the difference between two Dates.

The legal types of arithmetic for Date using this operator are

Date - Date --> duration
const pure nothrow @nogc @safe int diffMonths(in Date rhs)

Returns the difference between the two Dates in months.

To get the difference in years, subtract the year property of two Dates. To get the difference in days or weeks, subtract the Dates themselves and use the core.time.Duration that results. Because converting between months and smaller units requires a specific date (which core.time.Durations don't have), getting the difference in months requires some math using both the year and month properties, so this is a convenience function for getting the difference in months.

Note that the number of days in the months or how far into the month either Date is is irrelevant. It is the difference in the month property combined with the difference in years * 12. So, for instance, December 31st and January 1st are one month apart just as December 1st and January 31st are one month apart.

Parameters:
Date rhs The Date to subtract from this one.
Examples:
writeln(Date(1999, 2, 1).diffMonths(Date(1999, 1, 31))); // 1
writeln(Date(1999, 1, 31).diffMonths(Date(1999, 2, 1))); // -1
writeln(Date(1999, 3, 1).diffMonths(Date(1999, 1, 1))); // 2
writeln(Date(1999, 1, 1).diffMonths(Date(1999, 3, 31))); // -2
const pure nothrow @nogc @property @safe bool isLeapYear()

Whether this Date is in a leap year.

const pure nothrow @nogc @property @safe DayOfWeek dayOfWeek()

Day of the week this Date is on.

const pure nothrow @nogc @property @safe ushort dayOfYear()

Day of the year this Date is on.

Examples:
writeln(Date(1999, 1, 1).dayOfYear); // 1
writeln(Date(1999, 12, 31).dayOfYear); // 365
writeln(Date(2000, 12, 31).dayOfYear); // 366
pure @property @safe void dayOfYear(int day)

Day of the year.

Parameters:
int day The day of the year to set which day of the year this Date is on.
Throws:
std.datetime.date.DateTimeException if the given day is an invalid day of the year.
const pure nothrow @nogc @property @safe int dayOfGregorianCal()

The Xth day of the Gregorian Calendar that this Date is on.

Examples:
writeln(Date(1, 1, 1).dayOfGregorianCal); // 1
writeln(Date(1, 12, 31).dayOfGregorianCal); // 365
writeln(Date(2, 1, 1).dayOfGregorianCal); // 366

writeln(Date(0, 12, 31).dayOfGregorianCal); // 0
writeln(Date(0, 1, 1).dayOfGregorianCal); // -365
writeln(Date(-1, 12, 31).dayOfGregorianCal); // -366

writeln(Date(2000, 1, 1).dayOfGregorianCal); // 730_120
writeln(Date(2010, 12, 31).dayOfGregorianCal); // 734_137
pure nothrow @nogc @property @safe void dayOfGregorianCal(int day)

The Xth day of the Gregorian Calendar that this Date is on.

Parameters:
int day The day of the Gregorian Calendar to set this Date to.
Examples:
auto date = Date.init;
date.dayOfGregorianCal = 1;
writeln(date); // Date(1, 1, 1)

date.dayOfGregorianCal = 365;
writeln(date); // Date(1, 12, 31)

date.dayOfGregorianCal = 366;
writeln(date); // Date(2, 1, 1)

date.dayOfGregorianCal = 0;
writeln(date); // Date(0, 12, 31)

date.dayOfGregorianCal = -365;
writeln(date); // Date(-0, 1, 1)

date.dayOfGregorianCal = -366;
writeln(date); // Date(-1, 12, 31)

date.dayOfGregorianCal = 730_120;
writeln(date); // Date(2000, 1, 1)

date.dayOfGregorianCal = 734_137;
writeln(date); // Date(2010, 12, 31)
const pure nothrow @property @safe ubyte isoWeek()

The ISO 8601 week of the year that this Date is in.

See Also:
ISO Week Date
const pure nothrow @property @safe Date endOfMonth()

Date for the last day in the month that this Date is in.

Examples:
writeln(Date(1999, 1, 6).endOfMonth); // Date(1999, 1, 31)
writeln(Date(1999, 2, 7).endOfMonth); // Date(1999, 2, 28)
writeln(Date(2000, 2, 7).endOfMonth); // Date(2000, 2, 29)
writeln(Date(2000, 6, 4).endOfMonth); // Date(2000, 6, 30)
const pure nothrow @nogc @property @safe ubyte daysInMonth()

The last day in the month that this Date is in.

Examples:
writeln(Date(1999, 1, 6).daysInMonth); // 31
writeln(Date(1999, 2, 7).daysInMonth); // 28
writeln(Date(2000, 2, 7).daysInMonth); // 29
writeln(Date(2000, 6, 4).daysInMonth); // 30
const pure nothrow @nogc @property @safe bool isAD()

Whether the current year is a date in A.D.

Examples:
assert(Date(1, 1, 1).isAD);
assert(Date(2010, 12, 31).isAD);
assert(!Date(0, 12, 31).isAD);
assert(!Date(-2010, 1, 1).isAD);
const pure nothrow @nogc @property @safe long julianDay()

The Julian day for this Date at noon (since the Julian day changes at noon).

const pure nothrow @nogc @property @safe long modJulianDay()

The modified Julian day for any time on this date (since, the modified Julian day changes at midnight).

const pure nothrow @safe string toISOString()

Converts this Date to a string with the format YYYYMMDD.

Examples:
writeln(Date(2010, 7, 4).toISOString()); // "20100704"
writeln(Date(1998, 12, 25).toISOString()); // "19981225"
writeln(Date(0, 1, 5).toISOString()); // "00000105"
writeln(Date(-4, 1, 5).toISOString()); // "-00040105"
const pure nothrow @safe string toISOExtString()

Converts this Date to a string with the format YYYY-MM-DD.

Examples:
writeln(Date(2010, 7, 4).toISOExtString()); // "2010-07-04"
writeln(Date(1998, 12, 25).toISOExtString()); // "1998-12-25"
writeln(Date(0, 1, 5).toISOExtString()); // "0000-01-05"
writeln(Date(-4, 1, 5).toISOExtString()); // "-0004-01-05"
const pure nothrow @safe string toSimpleString()

Converts this Date to a string with the format YYYY-Mon-DD.

Examples:
writeln(Date(2010, 7, 4).toSimpleString()); // "2010-Jul-04"
writeln(Date(1998, 12, 25).toSimpleString()); // "1998-Dec-25"
writeln(Date(0, 1, 5).toSimpleString()); // "0000-Jan-05"
writeln(Date(-4, 1, 5).toSimpleString()); // "-0004-Jan-05"
const pure nothrow @safe string toString()

Converts this Date to a string.

This function exists to make it easy to convert a Date to a string for code that does not care what the exact format is - just that it presents the information in a clear manner. It also makes it easy to simply convert a Date to a string when using functions such as to!string, format, or writeln which use toString to convert user-defined types. So, it is unlikely that much code will call toString directly.

The format of the string is purposefully unspecified, and code that cares about the format of the string should use toISOString, toISOExtString, toSimpleString, or some other custom formatting function that explicitly generates the format that the code needs. The reason is that the code is then clear about what format it's using, making it less error-prone to maintain the code and interact with other software that consumes the generated strings. It's for this same reason Date has no fromString function, whereas it does have fromISOString, fromISOExtString, and fromSimpleString.

The format returned by toString may or may not change in the future.

pure @safe Date fromISOString(S)(in S isoString)

Constraints:
if (isSomeString!S)

Creates a Date from a string with the format YYYYMMDD. Whitespace is stripped from the given string.

Parameters:
S isoString A string formatted in the ISO format for dates.
Throws:
std.datetime.date.DateTimeException if the given string is not in the ISO format or if the resulting Date would not be valid.
pure @safe Date fromISOExtString(S)(in S isoExtString)

Constraints:
if (isSomeString!S)

Creates a Date from a string with the format YYYY-MM-DD. Whitespace is stripped from the given string.

Parameters:
S isoExtString A string formatted in the ISO Extended format for dates.
Throws:
std.datetime.date.DateTimeException if the given string is not in the ISO Extended format or if the resulting Date would not be valid.
pure @safe Date fromSimpleString(S)(in S simpleString)

Constraints:
if (isSomeString!S)

Creates a Date from a string with the format YYYY-Mon-DD. Whitespace is stripped from the given string.

Parameters:
S simpleString A string formatted in the way that toSimpleString formats dates.
Throws:
std.datetime.date.DateTimeException if the given string is not in the correct format or if the resulting Date would not be valid.
static pure nothrow @nogc @property @safe Date min()

Returns the Date farthest in the past which is representable by Date.

static pure nothrow @nogc @property @safe Date max()

Returns the Date farthest in the future which is representable by Date.

struct TimeOfDay

Represents a time of day with hours, minutes, and seconds. It uses 24 hour time.

pure @safe this(int hour, int minute, int second = 0)
Parameters:
int hour Hour of the day [0 - 24).
int minute Minute of the hour [0 - 60).
int second Second of the minute [0 - 60).
Throws:
std.datetime.date.DateTimeException if the resulting TimeOfDay would be not be valid.
const pure nothrow @nogc @safe int opCmp(in TimeOfDay rhs)

Compares this TimeOfDay with the given TimeOfDay.

Returns:
this < rhs < 0
this == rhs 0
this > rhs > 0
const pure nothrow @nogc @property @safe ubyte hour()

Hours past midnight.

pure @property @safe void hour(int hour)

Hours past midnight.

Parameters:
int hour The hour of the day to set this TimeOfDay's hour to.
Throws:
std.datetime.date.DateTimeException if the given hour would result in an invalid TimeOfDay.
const pure nothrow @nogc @property @safe ubyte minute()

Minutes past the hour.

pure @property @safe void minute(int minute)

Minutes past the hour.

Parameters:
int minute The minute to set this TimeOfDay's minute to.
Throws:
std.datetime.date.DateTimeException if the given minute would result in an invalid TimeOfDay.
const pure nothrow @nogc @property @safe ubyte second()

Seconds past the minute.

pure @property @safe void second(int second)

Seconds past the minute.

Parameters:
int second The second to set this TimeOfDay's second to.
Throws:
std.datetime.date.DateTimeException if the given second would result in an invalid TimeOfDay.
pure nothrow @nogc ref @safe TimeOfDay roll(string units)(long value)

Constraints:
if (units == "hours")

Adds the given number of units to this TimeOfDay. A negative number will subtract.

The difference between rolling and adding is that rolling does not affect larger units. For instance, rolling a TimeOfDay one hours's worth of minutes gets the exact same TimeOfDay.

Accepted units are "hours", "minutes", and "seconds".

Parameters:
units The units to add.
long value The number of units to add to this TimeOfDay.
Examples:
auto tod1 = TimeOfDay(7, 12, 0);
tod1.roll!"hours"(1);
writeln(tod1); // TimeOfDay(8, 12, 0)

auto tod2 = TimeOfDay(7, 12, 0);
tod2.roll!"hours"(-1);
writeln(tod2); // TimeOfDay(6, 12, 0)

auto tod3 = TimeOfDay(23, 59, 0);
tod3.roll!"minutes"(1);
writeln(tod3); // TimeOfDay(23, 0, 0)

auto tod4 = TimeOfDay(0, 0, 0);
tod4.roll!"minutes"(-1);
writeln(tod4); // TimeOfDay(0, 59, 0)

auto tod5 = TimeOfDay(23, 59, 59);
tod5.roll!"seconds"(1);
writeln(tod5); // TimeOfDay(23, 59, 0)

auto tod6 = TimeOfDay(0, 0, 0);
tod6.roll!"seconds"(-1);
writeln(tod6); // TimeOfDay(0, 0, 59)
const pure nothrow @nogc @safe TimeOfDay opBinary(string op)(Duration duration)

Constraints:
if (op == "+" || op == "-")

Gives the result of adding or subtracting a core.time.Duration from this TimeOfDay.

The legal types of arithmetic for TimeOfDay using this operator are

TimeOfDay + Duration --> TimeOfDay
TimeOfDay - Duration --> TimeOfDay
Parameters:
Duration duration The core.time.Duration to add to or subtract from this TimeOfDay.
Examples:
import core.time : hours, minutes, seconds;

writeln(TimeOfDay(12, 12, 12) + seconds(1)); // TimeOfDay(12, 12, 13)
writeln(TimeOfDay(12, 12, 12) + minutes(1)); // TimeOfDay(12, 13, 12)
writeln(TimeOfDay(12, 12, 12) + hours(1)); // TimeOfDay(13, 12, 12)
writeln(TimeOfDay(23, 59, 59) + seconds(1)); // TimeOfDay(0, 0, 0)

writeln(TimeOfDay(12, 12, 12) - seconds(1)); // TimeOfDay(12, 12, 11)
writeln(TimeOfDay(12, 12, 12) - minutes(1)); // TimeOfDay(12, 11, 12)
writeln(TimeOfDay(12, 12, 12) - hours(1)); // TimeOfDay(11, 12, 12)
writeln(TimeOfDay(0, 0, 0) - seconds(1)); // TimeOfDay(23, 59, 59)
pure nothrow @nogc ref @safe TimeOfDay opOpAssign(string op)(Duration duration)

Constraints:
if (op == "+" || op == "-")

Gives the result of adding or subtracting a core.time.Duration from this TimeOfDay, as well as assigning the result to this TimeOfDay.

The legal types of arithmetic for TimeOfDay using this operator are

TimeOfDay + Duration --> TimeOfDay
TimeOfDay - Duration --> TimeOfDay
Parameters:
Duration duration The core.time.Duration to add to or subtract from this TimeOfDay.
const pure nothrow @nogc @safe Duration opBinary(string op)(in TimeOfDay rhs)

Constraints:
if (op == "-")

Gives the difference between two TimeOfDays.

The legal types of arithmetic for TimeOfDay using this operator are

TimeOfDay - TimeOfDay --> duration
Parameters:
TimeOfDay rhs The TimeOfDay to subtract from this one.
const pure nothrow @safe string toISOString()

Converts this TimeOfDay to a string with the format HHMMSS.

Examples:
writeln(TimeOfDay(0, 0, 0).toISOString()); // "000000"
writeln(TimeOfDay(12, 30, 33).toISOString()); // "123033"
const pure nothrow @safe string toISOExtString()

Converts this TimeOfDay to a string with the format HH:MM:SS.

Examples:
writeln(TimeOfDay(0, 0, 0).toISOExtString()); // "00:00:00"
writeln(TimeOfDay(12, 30, 33).toISOExtString()); // "12:30:33"
const pure nothrow @safe string toString()

Converts this TimeOfDay to a string.

This function exists to make it easy to convert a TimeOfDay to a string for code that does not care what the exact format is - just that it presents the information in a clear manner. It also makes it easy to simply convert a TimeOfDay to a string when using functions such as to!string, format, or writeln which use toString to convert user-defined types. So, it is unlikely that much code will call toString directly.

The format of the string is purposefully unspecified, and code that cares about the format of the string should use toISOString, toISOExtString, or some other custom formatting function that explicitly generates the format that the code needs. The reason is that the code is then clear about what format it's using, making it less error-prone to maintain the code and interact with other software that consumes the generated strings. It's for this same reason that TimeOfDay has no fromString function, whereas it does have fromISOString and fromISOExtString.

The format returned by toString may or may not change in the future.

pure @safe TimeOfDay fromISOString(S)(in S isoString)

Constraints:
if (isSomeString!S)

Creates a TimeOfDay from a string with the format HHMMSS. Whitespace is stripped from the given string.

Parameters:
S isoString A string formatted in the ISO format for times.
Throws:
std.datetime.date.DateTimeException if the given string is not in the ISO format or if the resulting TimeOfDay would not be valid.
pure @safe TimeOfDay fromISOExtString(S)(in S isoExtString)

Constraints:
if (isSomeString!S)

Creates a TimeOfDay from a string with the format HH:MM:SS. Whitespace is stripped from the given string.

Parameters:
S isoExtString A string formatted in the ISO Extended format for times.
Throws:
std.datetime.date.DateTimeException if the given string is not in the ISO Extended format or if the resulting TimeOfDay would not be valid.
static pure nothrow @nogc @property @safe TimeOfDay min()

Returns midnight.

static pure nothrow @nogc @property @safe TimeOfDay max()

Returns one second short of midnight.

pure nothrow @nogc @safe bool valid(string units)(int value)

Constraints:
if (units == "months" || units == "hours" || units == "minutes" || units == "seconds")

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

Parameters:
units The units of time to validate.
int value The number to validate.
Examples:
assert(valid!"hours"(12));
assert(!valid!"hours"(32));
assert(valid!"months"(12));
assert(!valid!"months"(13));
pure nothrow @nogc @safe bool valid(string units)(int year, int month, int day)

Constraints:
if (units == "days")

Returns whether the given day is valid for the given year and month.

Parameters:
units The units of time to validate.
int year The year of the day to validate.
int month The month of the day to validate (January is 1).
int day The day to validate.
Examples:
assert(valid!"days"(2016, 2, 29));
assert(!valid!"days"(2016, 2, 30));
assert(valid!"days"(2017, 2, 20));
assert(!valid!"days"(2017, 2, 29));
pure @safe void enforceValid(string units)(int value, string file = __FILE__, size_t line = __LINE__)

Constraints:
if (units == "months" || units == "hours" || units == "minutes" || units == "seconds")
Parameters:
units The units of time to validate.
int value The number to validate.
string file The file that the DateTimeException will list if thrown.
size_t line The line number that the DateTimeException will list if thrown.
Throws:
DateTimeException if valid!units(value) is false.
pure @safe void enforceValid(string units)(int year, Month month, int day, string file = __FILE__, size_t line = __LINE__)

Constraints:
if (units == "days")
Parameters:
units The units of time to validate.
int year The year of the day to validate.
Month month The month of the day to validate.
int day The day to validate.
string file The file that the DateTimeException will list if thrown.
size_t line The line number that the DateTimeException will list if thrown.
Throws:
DateTimeException if valid!"days"(year, month, day) is false.
pure nothrow @nogc @safe int daysToDayOfWeek(DayOfWeek currDoW, DayOfWeek dow)

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.

Parameters:
DayOfWeek currDoW The current day of the week.
DayOfWeek dow The day of the week to get the number of days to.
Examples:
writeln(daysToDayOfWeek(DayOfWeek.mon, DayOfWeek.mon)); // 0
writeln(daysToDayOfWeek(DayOfWeek.mon, DayOfWeek.sun)); // 6
writeln(daysToDayOfWeek(DayOfWeek.mon, DayOfWeek.wed)); // 2
pure @safe int monthsToMonth(int currMonth, int month)

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.

Parameters:
int currMonth The current month of the year.
int month The month of the year to get the number of months to.
Examples:
writeln(monthsToMonth(Month.jan, Month.jan)); // 0
writeln(monthsToMonth(Month.jan, Month.dec)); // 11
writeln(monthsToMonth(Month.jul, Month.oct)); // 3
pure nothrow @nogc @safe bool yearIsLeapYear(int year)

Whether the given Gregorian Year is a leap year.

Parameters:
int year The year to to be tested.
Examples:
foreach (year; [1, 2, 100, 2001, 2002, 2003, 2005, 2006, 2007, 2009, 2010])
{
    assert(!yearIsLeapYear(year));
    assert(!yearIsLeapYear(-year));
}

foreach (year; [0, 4, 8, 400, 800, 1600, 1996, 2000, 2004, 2008, 2012])
{
    assert(yearIsLeapYear(year));
    assert(yearIsLeapYear(-year));
}
enum auto isTimePoint(T)

Whether the given type defines all of the necessary functions for it to function as a time point.

1. T must define a static property named min which is the smallest value of T as Unqual!T.

2. T must define a static property named max which is the largest value of T as Unqual!T.

3. T must define an opBinary for addition and subtraction that accepts core.time.Duration and returns Unqual!T.

4. T must define an opOpAssign for addition and subtraction that accepts core.time.Duration and returns ref Unqual!T.

5. T must define a opBinary for subtraction which accepts T and returns returns core.time.Duration.

Examples:
import core.time : Duration;
import std.datetime.interval : Interval;
import std.datetime.systime : SysTime;

static assert(isTimePoint!Date);
static assert(isTimePoint!DateTime);
static assert(isTimePoint!SysTime);
static assert(isTimePoint!TimeOfDay);

static assert(!isTimePoint!int);
static assert(!isTimePoint!Duration);
static assert(!isTimePoint!(Interval!SysTime));
pure nothrow @nogc @safe bool validTimeUnits(string[] units...)

Whether all of the given strings are valid units of time.

"nsecs" is not considered a valid unit of time. Nothing in std.datetime can handle precision greater than hnsecs, and the few functions in core.time which deal with "nsecs" deal with it explicitly.

Examples:
assert(validTimeUnits("msecs", "seconds", "minutes"));
assert(validTimeUnits("days", "weeks", "months"));
assert(!validTimeUnits("ms", "seconds", "minutes"));
pure @safe int cmpTimeUnits(string lhs, string rhs)

Compares two time unit strings. "years" are the largest units and "hnsecs" are the smallest.

Returns:
this < rhs < 0
this == rhs 0
this > rhs > 0
Throws:
DateTimeException if either of the given strings is not a valid time unit string.
Examples:
writeln(cmpTimeUnits("hours", "hours")); // 0
assert(cmpTimeUnits("hours", "weeks") < 0);
assert(cmpTimeUnits("months", "seconds") > 0);
template CmpTimeUnits(string lhs, string rhs) if (validTimeUnits(lhs, rhs))

Compares two time unit strings at compile time. "years" are the largest units and "hnsecs" are the smallest.

This template is used instead of cmpTimeUnits because exceptions can't be thrown at compile time and cmpTimeUnits must enforce that the strings it's given are valid time unit strings. This template uses a template constraint instead.

Returns:
this < rhs < 0
this == rhs 0
this > rhs > 0

© 1999–2017 The D Language Foundation
Licensed under the Boost License 1.0.
https://dlang.org/phobos/std_datetime_date.html