std.datetime.systime

License

Boost License 1.0.

Authors

Jonathan M Davis

Source: std/datetime/systime.d

alias DosFileTime
struct SysTime
class Clock
fn _convDigits _stripCFWS DosFileTimeToSysTime fracSecsFromISOString fracSecsToISOString getUnitsFromHNSecs parseRFC822DateTime removeUnitsFromHNSecs stdTimeToUnixTime SysTimeToDosFileTime unixTimeToStdTime

Types 3

classClock

Effectively a namespace to make it clear that the methods it contains are getting the time from the system clock. It cannot be instantiated.

Methods
SysTime currTime(ClockType clockType = ClockType.normal)(immutable TimeZone tz = LocalTime()) @safeReturns the current time in the given time zone.
long currStdTime(ClockType clockType = ClockType.normal)() @property @trustedReturns the number of hnsecs since midnight, January 1st, 1 A.D. for the current time.
Constructors
this()
structSysTime

SysTime is the type used to get the current time from the system or doing anything that involves time zones. Unlike

DateTime, the time zone is an integral part of

SysTime (though for local time applications, time zones can be ignored and it will work, since it defaults to using the local time zone). It holds its internal time in std time (hnsecs since midnight, January 1st, 1 A.D. UTC), so it interfaces well with the system time.

An hnsec (hecto-nanosecond) is 100 nanoseconds. There are 10,000,000 hnsecs in a second.

Unlike DateTime, SysTime is not optimized for

calendar-based operations, and getting individual units from it such as years or days is going to involve conversions and be less efficient.

For calendar-based operations that don't care about time zones, then DateTime would be the type to use. For system time, use SysTime.

Casting a SysTime to one of the following types will perform a conversion:

Date DateTime TimeOfDay

To convert a Date or DateTime to a

SysTime, use SysTime's constructor, and pass in the intended time zone with it (or don't pass in a TimeZone, and the local time zone will be used). Be aware, however, that converting from a

DateTime to a SysTime will not necessarily

be 100% accurate due to DST (one hour of the year doesn't exist and another occurs twice). To not risk any conversion errors, keep times as SysTimes. Aside from DST though, there shouldn't be any conversion problems.

For using time zones other than local time or UTC, use PosixTimeZone on Posix systems (or on Windows,

if providing the TZ Database files), and use

WindowsTimeZone on Windows systems. The time in

SysTime is kept internally in hnsecs from midnight, January 1st, 1 A.D. UTC. Conversion error cannot happen when changing the time zone of a SysTime. LocalTime is the

TimeZone class which represents the local time,

and UTC is the TimeZone class which represents UTC. SysTime uses LocalTime if no TimeZone is provided. For more details on time zones, see the documentation for TimeZone,

PosixTimeZone, and WindowsTimeZone.

SysTime's range is from approximately 29,000 B.C. to approximately

29,000 A.D.

See Also

.Clock.currTime, Clock.currTime will return the current time as a SysTime.
Fields
long _stdTime
Rebindable!(immutable TimeZone) _timezoneStorage
Methods
SysTime opAssign()(auto ref const(SysTime) rhs) ref scope return @safe pure nothrowParams: rhs = The SysTime to assign to this one.
bool opEquals()(auto ref const(SysTime) rhs) @safe const pure nothrow scopeChecks for equality between this SysTime and the given SysTime.
int opCmp()(auto ref const(SysTime) rhs) @safe const pure nothrow scopeCompares this SysTime with the given SysTime.
size_t toHash() const @nogc pure nothrow @safe scopeReturns: A hash of the SysTime.
short year() @property @safe const nothrow scopeYear of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.
void year(int year) @property @safe scopeYear of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.
ushort yearBC() @property @safe const scopeYear B.C. of the Gregorian Calendar counting year 0 as 1 B.C.
void yearBC(int year) @property @safe scopeYear B.C. of the Gregorian Calendar counting year 0 as 1 B.C.
Month month() @property @safe const nothrow scopeMonth of a Gregorian Year.
void month(Month month) @property @safe scopeMonth of a Gregorian Year.
ubyte day() @property @safe const nothrow scopeDay of a Gregorian Month.
void day(int day) @property @safe scopeDay of a Gregorian Month.
ubyte hour() @property @safe const nothrow scopeHours past midnight.
void hour(int hour) @property @safe scopeHours past midnight.
ubyte minute() @property @safe const nothrow scopeMinutes past the current hour.
void minute(int minute) @property @safe scopeMinutes past the current hour.
ubyte second() @property @safe const nothrow scopeSeconds past the current minute.
void second(int second) @property @safe scopeSeconds past the current minute.
Duration fracSecs() @property @safe const nothrow scopeFractional seconds past the second (i.e. the portion of a SysTime which is less than a second).
void fracSecs(Duration fracSecs) @property @safe scopeFractional seconds past the second (i.e. the portion of a SysTime which is less than a second).
long stdTime() @property @safe const pure nothrow scope @nogcThe total hnsecs from midnight, January 1st, 1 A.D. UTC. This is the internal representation of SysTime.
void stdTime(long stdTime) @property @safe pure nothrow scopeThe total hnsecs from midnight, January 1st, 1 A.D. UTC. This is the internal representation of SysTime.
immutable(TimeZone) timezone() @property @safe const pure nothrow return scopeThe current time zone of this SysTime. Its internal time is always kept in UTC, so there are no conversion issues between time zones due to DST. Functions which return all or part of the time - suc...
void timezone(immutable TimeZone timezone) @property @safe pure nothrow scopeThe current time zone of this SysTime. It's internal time is always kept in UTC, so there are no conversion issues between time zones due to DST. Functions which return all or part of the time - su...
bool dstInEffect() @property @safe const nothrow return scopeReturns whether DST is in effect for this SysTime.
Duration utcOffset() @property @safe const nothrow return scopeReturns what the offset from UTC is for this SysTime. It includes the DST offset in effect at that time (if any).
SysTime toLocalTime() @safe const pure nothrow scopeReturns a SysTime with the same std time as this one, but with LocalTime as its time zone.
SysTime toUTC() @safe const pure nothrow scopeReturns a SysTime with the same std time as this one, but with `UTC` as its time zone.
SysTime toOtherTZ(immutable TimeZone tz) @safe const pure nothrow scopeReturns a SysTime with the same std time as this one, but with given time zone as its time zone.
T toUnixTime(T = time_t)() if (is(T == int) || is(T == long)) @safe const pure nothrow scopeConverts this SysTime to unix time (i.e. seconds from midnight, January 1st, 1970 in UTC).
SysTime fromUnixTime(long unixTime, immutable TimeZone tz = LocalTime()) @safe pure nothrowConverts from unix time (i.e. seconds from midnight, January 1st, 1970 in UTC) to a SysTime.
timeval toTimeVal() @safe const pure nothrow scopeReturns a `timeval` which represents this SysTime.
tm toTM() @safe const nothrow scopeReturns a `tm` which represents this SysTime.
SysTime add(string units)(long value, AllowDayOverflow allowOverflow = AllowDayOverflow.yes) if (units == "years" || units == "months") ref @safe nothrow scopeAdds the given number of years or months to this SysTime. A negative number will subtract.
SysTime roll(string units)(long value, AllowDayOverflow allowOverflow = AllowDayOverflow.yes) if (units == "years") ref @safe nothrow scopeAdds the given number of years or months to this SysTime. A negative number will subtract.
SysTime roll(string units)(long value, AllowDayOverflow allowOverflow = AllowDayOverflow.yes) if (units == "months") ref @safe nothrow scope
SysTime roll(string units)(long value) if (units == "days") ref @safe nothrow scopeAdds the given number of units to this SysTime. A negative number will subtract.
SysTime roll(string units)(long value) if (units == "hours" || units == "minutes" || units == "seconds") ref @safe nothrow scope
SysTime roll(string units)(long value) if (units == "msecs" || units == "usecs" || units == "hnsecs") ref @safe nothrow scope
SysTime opBinary(string op)(Duration duration) if (op == "+" || op == "-") @safe const pure nothrow return scopeGives the result of adding or subtracting a Duration from this SysTime.
SysTime opBinaryRight(string op)(Duration duration) if (op == "+") const @safe pure nothrowditto
SysTime opOpAssign(string op)(Duration duration) if (op == "+" || op == "-") ref @safe pure nothrow scopeGives the result of adding or subtracting a Duration from this SysTime, as well as assigning the result to this SysTime.
Duration opBinary(string op)(SysTime rhs) if (op == "-") @safe const pure nothrow scopeGives the difference between two SysTimes.
int diffMonths(scope SysTime rhs) @safe const nothrow scopeReturns the difference between the two SysTimes in months.
bool isLeapYear() @property @safe const nothrow scopeWhether this SysTime is in a leap year.
DayOfWeek dayOfWeek() @property @safe const nothrow scopeDay of the week this SysTime is on.
ushort dayOfYear() @property @safe const nothrow scopeDay of the year this SysTime is on.
void dayOfYear(int day) @property @safe scopeDay of the year.
int dayOfGregorianCal() @property @safe const nothrow scopeThe Xth day of the Gregorian Calendar that this SysTime is on.
void dayOfGregorianCal(int days) @property @safe nothrow scopeThe Xth day of the Gregorian Calendar that this SysTime is on. Setting this property does not affect the time portion of SysTime.
ubyte isoWeek() @property @safe const nothrow scopeThe ISO 8601 week of the year that this SysTime is in.
SysTime endOfMonth() @property @safe const nothrow return scopeSysTime for the last day in the month that this Date is in. The time portion of endOfMonth is always 23:59:59.9999999.
ubyte daysInMonth() @property @safe const nothrow scopeThe last day in the month that this SysTime is in.
bool isAD() @property @safe const nothrow scopeWhether the current year is a date in A.D.
long julianDay() @property @safe const nothrow scopeThe en.wikipedia.org/wiki/Julianday for this SysTime 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 n...
long modJulianDay() @property @safe const nothrow scopeThe modified en.wikipedia.org/wiki/Julian_day for any time on this date (since, the modified Julian day changes at midnight).
Date opCast(T)() if (is(immutable T == immutable Date)) @safe const nothrow scopeReturns a Date equivalent to this SysTime.
DateTime opCast(T)() if (is(immutable T == immutable DateTime)) @safe const nothrow scopeReturns a DateTime equivalent to this SysTime.
TimeOfDay opCast(T)() if (is(immutable T == immutable TimeOfDay)) @safe const nothrow scopeReturns a TimeOfDay equivalent to this SysTime.
SysTime opCast(T)() if (is(immutable T == immutable SysTime)) @safe const pure nothrow scope
string toISOString() @safe const nothrow scopeConverts this SysTime to a string with the format YYYYMMDDTHHMMSS.FFFFFFFTZ (where F is fractional seconds and TZ is time zone).
void toISOString(W)(ref W writer) if (isOutputRange!(W, char)) const scopeditto
string toISOExtString(int prec = - 1) @safe const nothrow scopeConverts this SysTime to a string with the format YYYY-MM-DDTHH:MM:SS.FFFFFFFTZ (where F is fractional seconds and TZ is the time zone).
void toISOExtString(W)(ref W writer, int prec = - 1) if (isOutputRange!(W, char)) const scopeditto
string toSimpleString() @safe const nothrow scopeConverts this SysTime to a string with the format YYYY-Mon-DD HH:MM:SS.FFFFFFFTZ (where F is fractional seconds and TZ is the time zone).
void toSimpleString(W)(ref W writer) if (isOutputRange!(W, char)) const scopeditto
string toString() @safe const nothrow scopeConverts this SysTime to a string.
void toString(W)(ref W writer) if (isOutputRange!(W, char)) const scopeditto
SysTime fromISOString(S)(scope const S isoString, immutable TimeZone tz = null) if (isSomeString!S) @safeCreates a SysTime from a string with the format YYYYMMDDTHHMMSS.FFFFFFFTZ (where F is fractional seconds and TZ is the time zone). Whitespace is stripped from the given string.
SysTime fromISOExtString(S)(scope const S isoExtString, immutable TimeZone tz = null) if (isSomeString!(S)) @safeCreates a SysTime from a string with the format YYYY-MM-DDTHH:MM:SS.FFFFFFFTZ (where F is fractional seconds and TZ is the time zone). Whitespace is stripped from the given string.
SysTime fromSimpleString(S)(scope const S simpleString, immutable TimeZone tz = null) if (isSomeString!(S)) @safeCreates a SysTime from a string with the format YYYY-Mon-DD HH:MM:SS.FFFFFFFTZ (where F is fractional seconds and TZ is the time zone). Whitespace is stripped from the given string.
SysTime min() @property @safe pure nothrowReturns the SysTime farthest in the past which is representable by SysTime.
SysTime max() @property @safe pure nothrowReturns the SysTime farthest in the future which is representable by SysTime.
long adjTime() @property @safe const nothrow scope
void adjTime(long adjTime) @property @safe nothrow scope
@property _timezone() @safe const pure nothrow @nogc
void _timezone(return scope immutable TimeZone tz) @property @safe pure nothrow @nogc scope
Constructors
this(DateTime dateTime, return scope immutable TimeZone tz = null)Params: dateTime = The DateTime to use to set this SysTime's internal std time. As DateTime has no concept of time zone, tz is used as its time zone. tz = The TimeZone to use for this SysTime...
this(DateTime dateTime, Duration fracSecs, return scope immutable TimeZone tz = null)Params: dateTime = The DateTime to use to set this SysTime's internal std time. As DateTime has no concept of time zone, tz is used as its time zone. fracSecs = The fractional seconds portion of th...
this(Date date, return scope immutable TimeZone tz = null)Params: date = The Date to use to set this SysTime's internal std time. As Date has no concept of time zone, tz is used as its time zone. tz = The TimeZone to use for this SysTime. If null, Local...
this(long stdTime, return scope immutable TimeZone tz = null)Note: Whereas the other constructors take in the given date/time, assume that it's in the given time zone, and convert it to hnsecs in UTC since midnight, January 1st, 1 A.D. UTC - i.e. std time - ...
Nested Templates
InitTimeZone
aliasDosFileTime = uint

Type representing the DOS file date/time format.

Functions 13

fnlong unixTimeToStdTime(long unixTime) @safe pure nothrow @nogcConverts from unix time (which uses midnight, January 1st, 1970 UTC as its epoch and seconds as its units) to "std time" (which uses midnight, January 1st, 1 A.D. UTC and hnsecs as its units).
fnT stdTimeToUnixTime(T = time_t)(long stdTime) if (is(T == int) || is(T == long)) @safe pure nothrowConverts std time (which uses midnight, January 1st, 1 A.D. UTC as its epoch and hnsecs as its units) to unix time (which uses midnight, January 1st, 1970 UTC as its epoch and seconds as its units).
fnSysTime DosFileTimeToSysTime(DosFileTime dft, immutable TimeZone tz = LocalTime()) @safeConverts from DOS file date/time to SysTime.
fnDosFileTime SysTimeToDosFileTime(scope SysTime sysTime) @safeConverts from SysTime to DOS file date/time.
fnSysTime parseRFC822DateTime()(scope const char[] value) @safeThe given array of `char` or random-access range of `char` or `ubyte` is expected to be in the format specified in tools.ietf.org/html/rfc5322 section 3.3 with the grammar rule date-time. It is the...
fnSysTime parseRFC822DateTime(R)(scope R value) if (isRandomAccessRange!R && hasSlicing!R && hasLength!R && (is(immutable ElementType!R == immutable char) || is(immutable ElementType!R == immutable ubyte)))Ditto
fnstring fracSecsToISOString(int hnsecs, int prec = - 1) @safe pure nothrow
fnvoid fracSecsToISOString(W)(ref W writer, int hnsecs, int prec = - 1)
fnDuration fracSecsFromISOString(S)(scope const S isoString) if (isSomeString!S) @safe pure
fnlong getUnitsFromHNSecs(string units)(long hnsecs) if (validTimeUnits(units) && CmpTimeUnits!(units, "months") < 0) @safe pure nothrow
fnlong removeUnitsFromHNSecs(string units)(long hnsecs) if (validTimeUnits(units) && CmpTimeUnits!(units, "months") < 0) @safe pure nothrow
fnR _stripCFWS(R)(R range) if (isRandomAccessRange!R && hasSlicing!R && hasLength!R && (is(immutable ElementType!R == immutable char) || is(immutable ElementType!R == immutable ubyte)))
fnT _convDigits(T, R)(R str) if (isIntegral!T && isSigned!T)