std.datetime.date

Category	Functions
Main date types	Date DateTime
Other date types	Month DayOfWeek TimeOfDay
Date checking	valid validTimeUnits yearIsLeapYear isTimePoint enforceValid
Date conversion	daysToDayOfWeek monthsToMonth
Time units	cmpTimeUnits timeStrings
Other	AllowDayOverflow DateTimeException

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

Examples:

writeln(Date(2018, 10, 1).month); // Month.oct
writeln(DateTime(1, 1, 1).month); // Month.jan

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

Examples:

writeln(Date(2018, 10, 1).dayOfWeek); // DayOfWeek.mon
writeln(DateTime(5, 5, 5).dayOfWeek); // DayOfWeek.thu

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.

Examples:

import core.time : days, seconds;

auto dt = DateTime(2000, 6, 1, 10, 30, 0);

writeln(dt.date); // Date(2000, 6, 1)
writeln(dt.timeOfDay); // TimeOfDay(10, 30, 0)
writeln(dt.dayOfYear); // 153
writeln(dt.dayOfWeek); // DayOfWeek.thu

dt += 10.days + 100.seconds;
writeln(dt); // DateTime(2000, 6, 11, 10, 31, 40)

writeln(dt.toISOExtString()); // "2000-06-11T10:31:40"
writeln(dt.toISOString()); // "20000611T103140"
writeln(dt.toSimpleString()); // "2000-Jun-11 10:31:40"

writeln(DateTime.fromISOExtString("2018-01-01T12:00:00")); // DateTime(2018, 1, 1, 12, 0, 0)
writeln(DateTime.fromISOString("20180101T120000")); // DateTime(2018, 1, 1, 12, 0, 0)
writeln(DateTime.fromSimpleString("2018-Jan-01 12:00:00")); // DateTime(2018, 1, 1, 12, 0, 0)

pure nothrow @nogc @safe this(Date date, 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(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(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(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, mutating it. 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.

Returns:

A reference to the DateTime (this).

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, mutating it. 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.

Returns:

A reference to the DateTime (this).

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");

pure nothrow @nogc ref @safe DateTime roll(string units)(long value)
Constraints: if (units == "hours" || units == "minutes" || units == "seconds");

Adds the given number of units to this DateTime, mutating it. 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.

Returns:

A reference to the DateTime (this).

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)(Duration duration)
Constraints: if (op == "+" || op == "-");

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:

Duration duration

The duration to add to or subtract from this DateTime.

const pure nothrow @nogc @safe Duration opBinary(string op)(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(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 short isoWeekYear();

The year of the ISO 8601 week calendar 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();

const void toISOString(W)(ref W writer)
Constraints: if (isOutputRange!(W, char));

Converts this DateTime to a string with the format YYYYMMDDTHHMMSS. If writer is set, the resulting string will be written directly to it.

Parameters:

W writer

A char accepting output range

Returns:

A string when not using an output range; void otherwise.

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();

const void toISOExtString(W)(ref W writer)
Constraints: if (isOutputRange!(W, char));

Converts this DateTime to a string with the format YYYY-MM-DDTHH:MM:SS. If writer is set, the resulting string will be written directly to it.

Parameters:

W writer

A char accepting output range

Returns:

A string when not using an output range; void otherwise.

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();

const void toSimpleString(W)(ref W writer)
Constraints: if (isOutputRange!(W, char));

Converts this DateTime to a string with the format YYYY-Mon-DD HH:MM:SS. If writer is set, the resulting string will be written directly to it.

Parameters:

W writer

A char accepting output range

Returns:

A string when not using an output range; void otherwise.

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();

const void toString(W)(ref W writer)
Constraints: if (isOutputRange!(W, char));

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)(scope const 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)(scope const 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)(scope const 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.

Examples:

import core.time : days;

auto d = Date(2000, 6, 1);

writeln(d.dayOfYear); // 153
writeln(d.dayOfWeek); // DayOfWeek.thu

d += 10.days;
writeln(d); // Date(2000, 6, 11)

writeln(d.toISOExtString()); // "2000-06-11"
writeln(d.toISOString()); // "20000611"
writeln(d.toSimpleString()); // "2000-Jun-11"

writeln(Date.fromISOExtString("2018-01-01")); // Date(2018, 1, 1)
writeln(Date.fromISOString("20180101")); // Date(2018, 1, 1)
writeln(Date.fromSimpleString("2018-Jan-01")); // Date(2018, 1, 1)

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(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, mutating it. 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.

Returns:

A reference to the Date (this).

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, mutating it. 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.

Returns:

A reference to the Date (this).

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, mutating it. 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.

Returns:

A reference to the Date (this).

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)(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(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 auto isoWeekAndYear();

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

Returns:

An anonymous struct with the members isoWeekYear for the resulting year and isoWeek for the resulting ISO week.

See Also:

ISO Week Date

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 short isoWeekYear();

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

May differ from year between 28 December and 4 January.

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();

const void toISOString(W)(ref W writer)
Constraints: if (isOutputRange!(W, char));

Converts this Date to a string with the format YYYYMMDD. If writer is set, the resulting string will be written directly to it.

Parameters:

W writer

A char accepting output range

Returns:

A string when not using an output range; void otherwise.

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();

const void toISOExtString(W)(ref W writer)
Constraints: if (isOutputRange!(W, char));

Converts this Date to a string with the format YYYY-MM-DD. If writer is set, the resulting string will be written directly to it.

Parameters:

W writer

A char accepting output range

Returns:

A string when not using an output range; void otherwise.

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();

const void toSimpleString(W)(ref W writer)
Constraints: if (isOutputRange!(W, char));

Converts this Date to a string with the format YYYY-Mon-DD. If writer is set, the resulting string will be written directly to it.

Parameters:

W writer

A char accepting output range

Returns:

A string when not using an output range; void otherwise.

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();

const void toString(W)(ref W writer)
Constraints: if (isOutputRange!(W, char));

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)(scope const 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)(scope const 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)(scope const 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.

Examples:

import core.time : minutes, seconds;

auto t = TimeOfDay(12, 30, 0);

t += 10.minutes + 100.seconds;
writeln(t); // TimeOfDay(12, 41, 40)

writeln(t.toISOExtString()); // "12:41:40"
writeln(t.toISOString()); // "124140"

writeln(TimeOfDay.fromISOExtString("15:00:00")); // TimeOfDay(15, 0, 0)
writeln(TimeOfDay.fromISOString("015000")); // TimeOfDay(1, 50, 0)

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(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");

pure nothrow @nogc ref @safe TimeOfDay roll(string units)(long value)
Constraints: if (units == "minutes" || units == "seconds");

Adds the given number of units to this TimeOfDay, mutating it. 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.

Returns:

A reference to the TimeOfDay (this).

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)(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();

const void toISOString(W)(ref W writer)
Constraints: if (isOutputRange!(W, char));

Converts this TimeOfDay to a string with the format HHMMSS. If writer is set, the resulting string will be written directly to it.

Parameters:

W writer

A char accepting output range

Returns:

A string when not using an output range; void otherwise.

Examples:

writeln(TimeOfDay(0, 0, 0).toISOString()); // "000000"
writeln(TimeOfDay(12, 30, 33).toISOString()); // "123033"

const pure nothrow @safe string toISOExtString();

const void toISOExtString(W)(ref W writer)
Constraints: if (isOutputRange!(W, char));

Converts this TimeOfDay to a string with the format HH:MM:SS. If writer is set, the resulting string will be written directly to it.

Parameters:

W writer

A char accepting output range

Returns:

A string when not using an output range; void otherwise.

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();

const void toString(W)(ref W writer)
Constraints: if (isOutputRange!(W, char));

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.

Parameters:

W writer

A char accepting output range

Returns:

A string when not using an output range; void otherwise.

pure @safe TimeOfDay fromISOString(S)(scope const 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)(scope const 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.

Examples:

import std.exception : assertThrown, assertNotThrown;

assertNotThrown(enforceValid!"months"(10));
assertNotThrown(enforceValid!"seconds"(40));

assertThrown!DateTimeException(enforceValid!"months"(0));
assertThrown!DateTimeException(enforceValid!"hours"(24));
assertThrown!DateTimeException(enforceValid!"minutes"(60));
assertThrown!DateTimeException(enforceValid!"seconds"(60));

pure @safe void enforceValid(string units)(int year, Month month, int day, string file = __FILE__, size_t line = __LINE__)
Constraints: if (units == "days");

Because the validity of the day number depends on both on the year and month of which the day is occurring, take all three variables to validate the day.

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.

Examples:

import std.exception : assertThrown, assertNotThrown;

assertNotThrown(enforceValid!"days"(2000, Month.jan, 1));
// leap year
assertNotThrown(enforceValid!"days"(2000, Month.feb, 29));

assertThrown!DateTimeException(enforceValid!"days"(2001, Month.feb, 29));
assertThrown!DateTimeException(enforceValid!"days"(2000, Month.jan, 32));
assertThrown!DateTimeException(enforceValid!"days"(2000, Month.apr, 31));

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 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:

import std.exception : assertThrown;

writeln(cmpTimeUnits("hours", "hours")); // 0
assert(cmpTimeUnits("hours", "weeks") < 0);
assert(cmpTimeUnits("months", "seconds") > 0);

assertThrown!DateTimeException(cmpTimeUnits("month", "second"));

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

Examples:

static assert(CmpTimeUnits!("years", "weeks") > 0);
static assert(CmpTimeUnits!("days", "days") == 0);
static assert(CmpTimeUnits!("seconds", "hours") < 0);