std.datetime.date

License

Boost License 1.0.

Authors

Jonathan M Davis

Source: std/datetime/date.d

var _monthNames daysIn100Years daysIn400Years daysIn4Years daysInLeapYear daysInYear lastDayLeap lastDayNonLeap timeStrings
tmpl CmpTimeUnits isTimePoint
alias AllowDayOverflow DateTimeException
enum DayOfWeek Month
struct Date DateTime TimeOfDay
fn castToYear cmpTimeUnits cmpTimeUnitsCTFE daysToDayOfWeek enforceValid getDayOfWeek maxDay monthFromString monthsToMonth monthToString splitUnitsFromHNSecs valid validTimeUnits yearIsLeapYear

Types 7

aliasDateTimeException = TimeException

Exception type used by std.datetime. It's an alias to

TimeException. Either can be caught without concern about

which module it came from.

enumMonth : ubyte

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

jan = 1
feb
mar
apr
may
jun
jul
aug
sep
oct
nov
dec
enumDayOfWeek : ubyte

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

sun = 0
mon
tue
wed
thu
fri
sat
aliasAllowDayOverflow = Flag!"allowDayOverflow"

In some date calculations, adding months or years can cause the date to fall on a day of the month which is not valid (e.g. February 29th 2001 or June 31st 2000). If overflow is allowed (as is the default), then the month will be incremented accordingly (so, February 29th 2001 would become March 1st 2001, and June 31st 2000 would become July 1st 2000). If overflow is not allowed, then the day will be adjusted to the last valid day in that month (so, February 29th 2001 would become February 28th 2001 and June 31st 2000 would become June 30th 2000).

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.

structDateTime

Combines the Date and

TimeOfDay structs to give an object which holds

both the date and the time. It is optimized for calendar-based operations and has no concept of time zone. For an object which is optimized for time operations based on the system time, use

SysTime. SysTime has

a concept of time zone and has much higher precision (hnsecs). DateTime is intended primarily for calendar-based uses rather than precise time operations.

Fields
Date _date
TimeOfDay _tod
Methods
int opCmp(DateTime rhs) const @safe pure nothrow @nogcCompares this DateTime with the given `DateTime.`.
Date date() @property const @safe pure nothrow @nogcThe date portion of DateTime.
void date(Date date) @property @safe pure nothrow @nogcThe date portion of DateTime.
TimeOfDay timeOfDay() @property const @safe pure nothrow @nogcThe time portion of DateTime.
void timeOfDay(TimeOfDay tod) @property @safe pure nothrow @nogcThe time portion of DateTime.
short year() @property const @safe pure nothrow @nogcYear of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.
void year(int year) @property @safe pureYear of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.
short yearBC() @property const @safe pureYear B.C. of the Gregorian Calendar counting year 0 as 1 B.C.
void yearBC(int year) @property @safe pureYear B.C. of the Gregorian Calendar counting year 0 as 1 B.C.
Month month() @property const @safe pure nothrow @nogcMonth of a Gregorian Year.
void month(Month month) @property @safe pureMonth of a Gregorian Year.
ubyte day() @property const @safe pure nothrow @nogcDay of a Gregorian Month.
void day(int day) @property @safe pureDay of a Gregorian Month.
ubyte hour() @property const @safe pure nothrow @nogcHours past midnight.
void hour(int hour) @property @safe pureHours past midnight.
ubyte minute() @property const @safe pure nothrow @nogcMinutes past the hour.
void minute(int minute) @property @safe pureMinutes past the hour.
ubyte second() @property const @safe pure nothrow @nogcSeconds past the minute.
void second(int second) @property @safe pureSeconds past the minute.
DateTime add(string units)(long value, AllowDayOverflow allowOverflow = AllowDayOverflow.yes) if (units == "years" || units == "months") ref @safe pure nothrow @nogcAdds the given number of years or months to this DateTime, mutating it. A negative number will subtract.
DateTime roll(string units)(long value, AllowDayOverflow allowOverflow = AllowDayOverflow.yes) if (units == "years" || units == "months") ref @safe pure nothrow @nogcAdds the given number of years or months to this DateTime, mutating it. A negative number will subtract.
DateTime roll(string units)(long value) if (units == "days") ref @safe pure nothrow @nogcAdds the given number of units to this DateTime, mutating it. A negative number will subtract.
DateTime roll(string units)(long value) if (units == "hours" || units == "minutes" || units == "seconds") ref @safe pure nothrow @nogcditto
DateTime opBinary(string op)(Duration duration) if (op == "+" || op == "-") const @safe pure nothrow @nogcGives the result of adding or subtracting a Duration from this DateTime.
DateTime opBinaryRight(string op)(Duration duration) if (op == "+") const @safe pure nothrow @nogcditto
DateTime opOpAssign(string op)(Duration duration) if (op == "+" || op == "-") ref @safe pure nothrow @nogcGives the result of adding or subtracting a duration from this DateTime, as well as assigning the result to this DateTime.
Duration opBinary(string op)(DateTime rhs) if (op == "-") const @safe pure nothrow @nogcGives the difference between two DateTimes.
int diffMonths(DateTime rhs) const @safe pure nothrow @nogcReturns the difference between the two DateTimes in months.
bool isLeapYear() @property const @safe pure nothrow @nogcWhether this DateTime is in a leap year.
DayOfWeek dayOfWeek() @property const @safe pure nothrow @nogcDay of the week this DateTime is on.
ushort dayOfYear() @property const @safe pure nothrow @nogcDay of the year this DateTime is on.
void dayOfYear(int day) @property @safe pureDay of the year.
int dayOfGregorianCal() @property const @safe pure nothrow @nogcThe Xth day of the Gregorian Calendar that this DateTime is on.
void dayOfGregorianCal(int days) @property @safe pure nothrow @nogcThe Xth day of the Gregorian Calendar that this DateTime is on. Setting this property does not affect the time portion of DateTime.
ubyte isoWeek() @property const @safe pure nothrowThe ISO 8601 week of the year that this DateTime is in.
short isoWeekYear() @property const @safe pure nothrowThe year of the ISO 8601 week calendar that this DateTime is in.
DateTime endOfMonth() @property const @safe pure nothrowDateTime for the last day in the month that this DateTime is in. The time portion of endOfMonth is always 23:59:59.
ubyte daysInMonth() @property const @safe pure nothrow @nogcThe last day in the month that this DateTime is in.
bool isAD() @property const @safe pure nothrow @nogcWhether the current year is a date in A.D.
long julianDay() @property const @safe pure nothrow @nogcThe en.wikipedia.org/wiki/Julianday for this DateTime at the given time. For example, prior to noon, 1996-03-31 would be the Julian day number 2450173, so this function returns 2450173, while from ...
long modJulianDay() @property const @safe pure nothrow @nogcThe modified en.wikipedia.org/wiki/Julian_day for any time on this date (since, the modified Julian day changes at midnight).
string toISOString() const @safe pure nothrowConverts this DateTime to a string with the format `YYYYMMDDTHHMMSS`. If `writer` is set, the resulting string will be written directly to it.
void toISOString(W)(ref W writer) if (isOutputRange!(W, char)) constditto
string toISOExtString() const @safe pure nothrowConverts 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.
void toISOExtString(W)(ref W writer) if (isOutputRange!(W, char)) constditto
string toSimpleString() const @safe pure nothrowConverts 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.
void toSimpleString(W)(ref W writer) if (isOutputRange!(W, char)) constditto
string toString() const @safe pure nothrowConverts this DateTime to a string.
void toString(W)(ref W writer) if (isOutputRange!(W, char)) constditto
DateTime fromISOString(S)(scope const S isoString) if (isSomeString!S) @safe pureCreates a DateTime from a string with the format YYYYMMDDTHHMMSS. Whitespace is stripped from the given string.
DateTime fromISOExtString(S)(scope const S isoExtString) if (isSomeString!(S)) @safe pureCreates a DateTime from a string with the format YYYY-MM-DDTHH:MM:SS. Whitespace is stripped from the given string.
DateTime fromSimpleString(S)(scope const S simpleString) if (isSomeString!(S)) @safe pureCreates a DateTime from a string with the format YYYY-Mon-DD HH:MM:SS. Whitespace is stripped from the given string.
DateTime min() @property @safe pure nothrow @nogcReturns the DateTime farthest in the past which is representable by DateTime.
DateTime max() @property @safe pure nothrow @nogcReturns the DateTime farthest in the future which is representable by DateTime.
DateTime _addSeconds(long seconds) ref return @safe pure nothrow @nogc
Constructors
this(Date date, TimeOfDay tod = TimeOfDay.init)Params: date = The date portion of DateTime. tod = The time portion of DateTime.
this(int year, int month, int day, int hour = 0, int minute = 0, int second = 0)Params: year = The year portion of the date. month = The month portion of the date (January is 1). day = The day portion of the date. hour = The hour portion of the time; minute = The minut...
structDate

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.

Fields
short _year
Month _month
ubyte _day
Methods
int opCmp(Date rhs) const @safe pure nothrow @nogcCompares this Date with the given Date.
short year() @property const @safe pure nothrow @nogcYear of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.
void year(int year) @property @safe pureYear of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.
ushort yearBC() @property const @safe pureYear B.C. of the Gregorian Calendar counting year 0 as 1 B.C.
void yearBC(int year) @property @safe pureYear B.C. of the Gregorian Calendar counting year 0 as 1 B.C.
Month month() @property const @safe pure nothrow @nogcMonth of a Gregorian Year.
void month(Month month) @property @safe pureMonth of a Gregorian Year.
ubyte day() @property const @safe pure nothrow @nogcDay of a Gregorian Month.
void day(int day) @property @safe pureDay of a Gregorian Month.
Date add(string units)(long value, AllowDayOverflow allowOverflow = AllowDayOverflow.yes) if (units == "years") @safe pure nothrow @nogc refAdds the given number of years or months to this Date, mutating it. A negative number will subtract.
Date add(string units)(long months, AllowDayOverflow allowOverflow = AllowDayOverflow.yes) if (units == "months") @safe pure nothrow @nogc ref
Date roll(string units)(long value, AllowDayOverflow allowOverflow = AllowDayOverflow.yes) if (units == "years") @safe pure nothrow @nogc refAdds the given number of years or months to this Date, mutating it. A negative number will subtract.
Date roll(string units)(long months, AllowDayOverflow allowOverflow = AllowDayOverflow.yes) if (units == "months") @safe pure nothrow @nogc ref
Date roll(string units)(long days) if (units == "days") ref @safe pure nothrow @nogcAdds the given number of units to this Date, mutating it. A negative number will subtract.
Date opBinary(string op)(Duration duration) if (op == "+" || op == "-") const @safe pure nothrow @nogcGives the result of adding or subtracting a Duration from this Date.
Date opBinaryRight(string op)(Duration duration) if (op == "+") const @safe pure nothrow @nogcditto
Date opOpAssign(string op)(Duration duration) if (op == "+" || op == "-") ref @safe pure nothrow @nogcGives the result of adding or subtracting a Duration from this Date, as well as assigning the result to this Date.
Duration opBinary(string op)(Date rhs) if (op == "-") const @safe pure nothrow @nogcGives the difference between two Dates.
int diffMonths(Date rhs) const @safe pure nothrow @nogcReturns the difference between the two Dates in months.
bool isLeapYear() @property const @safe pure nothrow @nogcWhether this Date is in a leap year.
DayOfWeek dayOfWeek() @property const @safe pure nothrow @nogcDay of the week this Date is on.
ushort dayOfYear() @property const @safe pure nothrow @nogcDay of the year this Date is on.
void dayOfYear(int day) @property @safe pureDay of the year.
private void setDayOfYear(bool useExceptions = false)(int day)
int dayOfGregorianCal() @property const @safe pure nothrow @nogcThe Xth day of the Gregorian Calendar that this Date is on.
void dayOfGregorianCal(int day) @property @safe pure nothrow @nogcThe Xth day of the Gregorian Calendar that this Date is on.
@property auto isoWeekAndYear() const @safe pure nothrowThe ISO 8601 week and year of the year that this Date is in.
ubyte isoWeek() @property const @safe pure nothrowThe ISO 8601 week of the year that this Date is in.
short isoWeekYear() @property const @safe pure nothrowThe year inside the ISO 8601 week calendar that this Date is in.
Date fromISOWeek(short isoWeekYear, ubyte isoWeek, DayOfWeek weekday) @safe pure nothrow @nogc
Date endOfMonth() @property const @safe pure nothrowDate for the last day in the month that this Date is in.
ubyte daysInMonth() @property const @safe pure nothrow @nogcThe last day in the month that this Date is in.
bool isAD() @property const @safe pure nothrow @nogcWhether the current year is a date in A.D.
long julianDay() @property const @safe pure nothrow @nogcThe en.wikipedia.org/wiki/Julian_day for this Date at noon (since the Julian day changes at noon).
long modJulianDay() @property const @safe pure nothrow @nogcThe modified en.wikipedia.org/wiki/Julian_day for any time on this date (since, the modified Julian day changes at midnight).
string toISOString() const @safe pure nothrowConverts this Date to a string with the format `YYYYMMDD`. If `writer` is set, the resulting string will be written directly to it.
void toISOString(W)(ref W writer) if (isOutputRange!(W, char)) constditto
string toISOExtString() const @safe pure nothrowConverts this Date to a string with the format `YYYY-MM-DD`. If `writer` is set, the resulting string will be written directly to it.
void toISOExtString(W)(ref W writer) if (isOutputRange!(W, char)) constditto
string toSimpleString() const @safe pure nothrowConverts this Date to a string with the format `YYYY-Mon-DD`. If `writer` is set, the resulting string will be written directly to it.
void toSimpleString(W)(ref W writer) if (isOutputRange!(W, char)) constditto
string toString() const @safe pure nothrowConverts this Date to a string.
void toString(W)(ref W writer) if (isOutputRange!(W, char)) constditto
Date fromISOString(S)(scope const S isoString) if (isSomeString!S) @safe pureCreates a Date from a string with the format YYYYMMDD. Whitespace is stripped from the given string.
Date fromISOExtString(S)(scope const S isoExtString) if (isSomeString!(S)) @safe pureCreates a Date from a string with the format YYYY-MM-DD. Whitespace is stripped from the given string.
Date fromSimpleString(S)(scope const S simpleString) if (isSomeString!(S)) @safe pureCreates a Date from a string with the format YYYY-Mon-DD. Whitespace is stripped from the given string.
Date min() @property @safe pure nothrow @nogcReturns the Date farthest in the past which is representable by Date.
Date max() @property @safe pure nothrow @nogcReturns the Date farthest in the future which is representable by Date.
bool _valid(int year, int month, int day) @safe pure nothrow @nogc
Date _addDays(long days) ref return @safe pure nothrow @nogc
Constructors
this(int year, int month, int day)Throws: DateTimeException if the resulting Date would not be valid.
this(int day)Params: day = The Xth day of the Gregorian Calendar that the constructed Date will be for.
structTimeOfDay

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

Fields
ubyte _hour
ubyte _minute
ubyte _second
ubyte maxHour
ubyte maxMinute
ubyte maxSecond
Methods
int opCmp(TimeOfDay rhs) const @safe pure nothrow @nogcCompares this TimeOfDay with the given TimeOfDay.
ubyte hour() @property const @safe pure nothrow @nogcHours past midnight.
void hour(int hour) @property @safe pureHours past midnight.
ubyte minute() @property const @safe pure nothrow @nogcMinutes past the hour.
void minute(int minute) @property @safe pureMinutes past the hour.
ubyte second() @property const @safe pure nothrow @nogcSeconds past the minute.
void second(int second) @property @safe pureSeconds past the minute.
TimeOfDay roll(string units)(long value) if (units == "hours") ref @safe pure nothrow @nogcAdds the given number of units to this TimeOfDay, mutating it. A negative number will subtract.
TimeOfDay roll(string units)(long value) if (units == "minutes" || units == "seconds") ref @safe pure nothrow @nogcditto
TimeOfDay opBinary(string op)(Duration duration) if (op == "+" || op == "-") const @safe pure nothrow @nogcGives the result of adding or subtracting a Duration from this TimeOfDay.
TimeOfDay opBinaryRight(string op)(Duration duration) if (op == "+") const @safe pure nothrow @nogcditto
TimeOfDay opOpAssign(string op)(Duration duration) if (op == "+" || op == "-") ref @safe pure nothrow @nogcGives the result of adding or subtracting a Duration from this TimeOfDay, as well as assigning the result to this TimeOfDay.
Duration opBinary(string op)(TimeOfDay rhs) if (op == "-") const @safe pure nothrow @nogcGives the difference between two TimeOfDays.
string toISOString() const @safe pure nothrowConverts this TimeOfDay to a string with the format `HHMMSS`. If `writer` is set, the resulting string will be written directly to it.
void toISOString(W)(ref W writer) if (isOutputRange!(W, char)) constditto
string toISOExtString() const @safe pure nothrowConverts this TimeOfDay to a string with the format `HH:MM:SS`. If `writer` is set, the resulting string will be written directly to it.
void toISOExtString(W)(ref W writer) if (isOutputRange!(W, char)) constditto
string toString() const @safe pure nothrowConverts this TimeOfDay to a string.
void toString(W)(ref W writer) if (isOutputRange!(W, char)) constditto
TimeOfDay fromISOString(S)(scope const S isoString) if (isSomeString!S) @safe pureCreates a TimeOfDay from a string with the format HHMMSS. Whitespace is stripped from the given string.
TimeOfDay fromISOExtString(S)(scope const S isoExtString) if (isSomeString!S) @safe pureCreates a TimeOfDay from a string with the format HH:MM:SS. Whitespace is stripped from the given string.
TimeOfDay min() @property @safe pure nothrow @nogcReturns midnight.
TimeOfDay max() @property @safe pure nothrow @nogcReturns one second short of midnight.
TimeOfDay _addSeconds(long seconds) ref return @safe pure nothrow @nogc
bool _valid(int hour, int minute, int second) @safe pure nothrow @nogc
Constructors
this(int hour, int minute, int second = 0)Params: hour = Hour of the day [0 - 24. minute = Minute of the hour [0 - 60. second = Second of the minute [0 - 60.

Functions 16

fnbool valid(string units)(int value) if (units == "months" || units == "hours" || units == "minutes" || units == "seconds") @safe pure nothrow @nogcReturns 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...
fnbool valid(string units)(int year, int month, int day) if (units == "days") @safe pure nothrow @nogcReturns whether the given day is valid for the given year and month.
private fnshort castToYear(int year, string file = __FILE__, size_t line = __LINE__) @safe pure
fnvoid enforceValid(string units)(int value, string file = __FILE__, size_t line = __LINE__) if (units == "months" || units == "hours" || units == "minutes" || units == "seconds") @safe pureParams: units = The units of time to validate. value = The number to validate. file = The file that the DateTimeException will list if thrown. line = The line number that the DateTimeException wi...
fnvoid enforceValid(string units)(int year, Month month, int day, string file = __FILE__, size_t line = __LINE__) if (units == "days") @safe pureBecause 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.
fnint daysToDayOfWeek(DayOfWeek currDoW, DayOfWeek dow) @safe pure nothrow @nogcReturns 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.
fnint monthsToMonth(int currMonth, int month) @safe pureReturns 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.
fnbool yearIsLeapYear(int year) @safe pure nothrow @nogcWhether the given Gregorian Year is a leap year.
fnbool validTimeUnits(string[] units...) @safe pure nothrow @nogcWhether all of the given strings are valid units of time.
fnint cmpTimeUnits(string lhs, string rhs) @safe pureCompares two time unit strings. `"years"` are the largest units and `"hnsecs"` are the smallest.
private fnint cmpTimeUnitsCTFE(string lhs, string rhs) @safe pure nothrow @nogc
fnubyte maxDay(int year, int month) @safe pure nothrow @nogc
fnlong splitUnitsFromHNSecs(string units)(ref long hnsecs) if (validTimeUnits(units) && CmpTimeUnits!(units, "months") < 0) @safe pure nothrow @nogc
fnDayOfWeek getDayOfWeek(int day) @safe pure nothrow @nogc
fnstring monthToString(Month month) @safe pure
fnMonth monthFromString(T)(T monthStr) if (isSomeString!T) @safe pure

Variables 9

varstring[] 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"

varstring[12] _monthNames
enumvardaysInYear = 365
enumvardaysInLeapYear = 366
enumvardaysIn4Years = daysInYear * 3 + daysInLeapYear
enumvardaysIn100Years = daysIn4Years * 25 - 1
enumvardaysIn400Years = daysIn100Years * 4 + 1
varint[13] lastDayNonLeap
varint[13] lastDayLeap

Templates 2

tmplisTimePoint(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.

  1. T must define a static property named max which is the largest

value of T as Unqual!T.

  1. T must define an opBinary for addition and subtraction that

accepts Duration and returns Unqual!T.

  1. T must define an opOpAssign for addition and subtraction that

accepts Duration and returns ref Unqual!T.

  1. T must define a opBinary for subtraction which accepts T

and returns Duration.

tmplCmpTimeUnits(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