SysTime

SysTime is the type used to get the current time from the system or doing anything that involves time zones. Unlike std.datetime.date.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.

$(PANEL Unlike $(REF_SHORT DateTime,std,datetime,date), `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 $(REF_SHORT DateTime,std,datetime,date) would be the type to use. For system time, use `SysTime`. )

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

* std.datetime.date.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 std.datetime.timezone.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.

$(PANEL For using time zones other than local time or UTC, use $(REF PosixTimeZone,std,datetime,timezone) on Posix systems (or on Windows, if providing the TZ Database files), and use $(REF WindowsTimeZone,std,datetime,timezone) 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`. $(REF LocalTime,std,datetime,timezone) is the $(REF_SHORT TimeZone,std,datetime,timezone) class which represents the local time, and `UTC` is the $(REF_SHORT TimeZone,std,datetime,timezone) class which represents UTC. `SysTime` uses $(REF_SHORT LocalTime,std,datetime,timezone) if no $(REF_SHORT TimeZone,std,datetime,timezone) is provided. For more details on time zones, see the documentation for $(REF_SHORT TimeZone,std,datetime,timezone), $(REF_SHORT PosixTimeZone,std,datetime,timezone), and $(REF_SHORT WindowsTimeZone,std,datetime,timezone). )

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

struct SysTime {

struct Rebindable(T) via import std.typecons : Rebindable;;

this(DateTime dateTime, TimeZone tz);

this(DateTime dateTime, Duration fracSecs, TimeZone tz);

this(Date date, TimeZone tz);

this(long stdTime, TimeZone tz);

SysTime opAssign(const(SysTime) rhs);

bool opEquals(const(SysTime) rhs);

int opCmp(const(SysTime) rhs);

size_t toHash();

short year [@property getter];

int year [@property setter];

ushort yearBC [@property getter];

int yearBC [@property setter];

Month month [@property getter];

Month month [@property setter];

ubyte day [@property getter];

int day [@property setter];

ubyte hour [@property getter];

int hour [@property setter];

ubyte minute [@property getter];

int minute [@property setter];

ubyte second [@property getter];

int second [@property setter];

Duration fracSecs [@property getter];

Duration fracSecs [@property setter];

long stdTime [@property getter];

long stdTime [@property setter];

immutable(TimeZone) timezone [@property getter];

TimeZone timezone [@property setter];

bool dstInEffect [@property getter];

Duration utcOffset [@property getter];

SysTime toLocalTime();

SysTime toUTC();

SysTime toOtherTZ(TimeZone tz);

T toUnixTime();

static SysTime fromUnixTime(long unixTime, TimeZone tz);

timeval toTimeVal();

version(StdDdoc)

timespec toTimeSpec();

SysTime add(long value, AllowDayOverflow allowOverflow);

SysTime roll(long value, AllowDayOverflow allowOverflow);

SysTime roll(long value);

SysTime opBinary(Duration duration);

SysTime opOpAssign(Duration duration);

Duration opBinary(SysTime rhs);

int diffMonths(SysTime rhs);

bool isLeapYear [@property getter];

DayOfWeek dayOfWeek [@property getter];

ushort dayOfYear [@property getter];

int dayOfYear [@property setter];

int dayOfGregorianCal [@property getter];

int dayOfGregorianCal [@property setter];

ubyte isoWeek [@property getter];

SysTime endOfMonth [@property getter];

ubyte daysInMonth [@property getter];

bool isAD [@property getter];

long julianDay [@property getter];

long modJulianDay [@property getter];

Date opCast();

DateTime opCast();

TimeOfDay opCast();

string toISOString();

void toISOString(W writer);

string toISOExtString(int prec);

void toISOExtString(W writer, int prec);

string toSimpleString();

void toSimpleString(W writer);

string toString();

void toString(W writer);

static SysTime fromISOString(S isoString, TimeZone tz);

static SysTime fromISOExtString(S isoExtString, TimeZone tz);

static SysTime fromSimpleString(S simpleString, TimeZone tz);

static SysTime min [@property getter];

static SysTime max [@property getter];

}

Constructors

this this(DateTime dateTime, TimeZone tz)
this this(DateTime dateTime, Duration fracSecs, TimeZone tz)
this this(Date date, TimeZone tz)
this this(long stdTime, TimeZone tz): 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 - this constructor takes a std time, which is specifically already in UTC, so no conversion takes place. Of course, the various getter properties and functions will use the given time zone's conversion function to convert the results to that time zone, but no conversion of the arguments to this constructor takes place.

Members

Functions

add SysTime add(long value, AllowDayOverflow allowOverflow): Adds the given number of years or months to this SysTime. A negative number will subtract.
diffMonths int diffMonths(SysTime rhs): Returns the difference between the two SysTimes in months.
opAssign SysTime opAssign(const(SysTime) rhs)
opBinary SysTime opBinary(Duration duration): Gives the result of adding or subtracting a core.time.Duration from this SysTime.
opBinary Duration opBinary(SysTime rhs): Gives the difference between two SysTimes.
opCast Date opCast(): Returns a std.datetime.date.Date equivalent to this SysTime.
opCast DateTime opCast(): Returns a std.datetime.date.DateTime equivalent to this SysTime.
opCast TimeOfDay opCast(): Returns a std.datetime.date.TimeOfDay equivalent to this SysTime.
opCmp int opCmp(const(SysTime) rhs): Compares this SysTime with the given SysTime.
opEquals bool opEquals(const(SysTime) rhs): Checks for equality between this SysTime and the given SysTime.
opOpAssign SysTime opOpAssign(Duration duration): Gives the result of adding or subtracting a core.time.Duration from this SysTime, as well as assigning the result to this SysTime.
roll SysTime roll(long value, AllowDayOverflow allowOverflow): Adds the given number of years or months to this SysTime. A negative number will subtract.
roll SysTime roll(long value): Adds the given number of units to this SysTime. A negative number will subtract.
toHash size_t toHash()
toISOExtString string toISOExtString(int prec)
void toISOExtString(W writer, int prec): Converts 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).
toISOString string toISOString()
void toISOString(W writer): Converts this SysTime to a string with the format YYYYMMDDTHHMMSS.FFFFFFFTZ (where F is fractional seconds and TZ is time zone).
toLocalTime SysTime toLocalTime(): Returns a SysTime with the same std time as this one, but with std.datetime.timezone.LocalTime as its time zone.
toOtherTZ SysTime toOtherTZ(TimeZone tz): Returns a SysTime with the same std time as this one, but with given time zone as its time zone.
toSimpleString string toSimpleString()
void toSimpleString(W writer): Converts 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).
toString string toString()
void toString(W writer): Converts this SysTime to a string.
toTM tm toTM(): Returns a tm which represents this SysTime.
toTimeSpec timespec toTimeSpec(): Returns a timespec which represents this SysTime.
toTimeVal timeval toTimeVal(): Returns a timeval which represents this SysTime.
toUTC SysTime toUTC(): Returns a SysTime with the same std time as this one, but with UTC as its time zone.
toUnixTime T toUnixTime(): Converts this SysTime to unix time (i.e. seconds from midnight, January 1st, 1970 in UTC).

Properties

day ubyte day [@property getter]: Day of a Gregorian Month.
day int day [@property setter]: Day of a Gregorian Month.
dayOfGregorianCal int dayOfGregorianCal [@property getter]: The Xth day of the Gregorian Calendar that this SysTime is on.
dayOfGregorianCal int dayOfGregorianCal [@property setter]: The Xth day of the Gregorian Calendar that this SysTime is on. Setting this property does not affect the time portion of SysTime.
dayOfWeek DayOfWeek dayOfWeek [@property getter]: Day of the week this SysTime is on.
dayOfYear ushort dayOfYear [@property getter]: Day of the year this SysTime is on.
dayOfYear int dayOfYear [@property setter]: Day of the year.
daysInMonth ubyte daysInMonth [@property getter]: The last day in the month that this SysTime is in.
dstInEffect bool dstInEffect [@property getter]: Returns whether DST is in effect for this SysTime.
endOfMonth SysTime endOfMonth [@property getter]: SysTime for the last day in the month that this Date is in. The time portion of endOfMonth is always 23:59:59.9999999.
fracSecs Duration fracSecs [@property getter]: Fractional seconds past the second (i.e. the portion of a SysTime which is less than a second).
fracSecs Duration fracSecs [@property setter]: Fractional seconds past the second (i.e. the portion of a SysTime which is less than a second).
hour ubyte hour [@property getter]: Hours past midnight.
hour int hour [@property setter]: Hours past midnight.
isAD bool isAD [@property getter]: Whether the current year is a date in A.D.
isLeapYear bool isLeapYear [@property getter]: Whether this SysTime is in a leap year.
isoWeek ubyte isoWeek [@property getter]: The ISO 8601 week of the year that this SysTime is in.
julianDay long julianDay [@property getter]: The Julian day for this SysTime 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.
max SysTime max [@property getter]: Returns the SysTime farthest in the future which is representable by SysTime.
min SysTime min [@property getter]: Returns the SysTime farthest in the past which is representable by SysTime.
minute ubyte minute [@property getter]: Minutes past the current hour.
minute int minute [@property setter]: Minutes past the current hour.
modJulianDay long modJulianDay [@property getter]: The modified Julian day for any time on this date (since, the modified Julian day changes at midnight).
month Month month [@property getter]: Month of a Gregorian Year.
month Month month [@property setter]: Month of a Gregorian Year.
second ubyte second [@property getter]: Seconds past the current minute.
second int second [@property setter]: Seconds past the current minute.
stdTime long stdTime [@property getter]: The total hnsecs from midnight, January 1st, 1 A.D. UTC. This is the internal representation of SysTime.
stdTime long stdTime [@property setter]: The total hnsecs from midnight, January 1st, 1 A.D. UTC. This is the internal representation of SysTime.
timezone immutable(TimeZone) timezone [@property getter]: The 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 - such as hours - adjust the time to this SysTime's time zone before returning.
timezone TimeZone timezone [@property setter]: The 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 - such as hours - adjust the time to this SysTime's time zone before returning.
utcOffset Duration utcOffset [@property getter]: Returns what the offset from UTC is for this SysTime. It includes the DST offset in effect at that time (if any).
year short year [@property getter]: Year of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.
year int year [@property setter]: Year of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.
yearBC ushort yearBC [@property getter]: Year B.C. of the Gregorian Calendar counting year 0 as 1 B.C.
yearBC int yearBC [@property setter]: Year B.C. of the Gregorian Calendar counting year 0 as 1 B.C.

Static functions

fromISOExtString SysTime fromISOExtString(S isoExtString, TimeZone tz): Creates 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.
fromISOString SysTime fromISOString(S isoString, TimeZone tz): Creates 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.
fromSimpleString SysTime fromSimpleString(S simpleString, TimeZone tz): Creates 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.
fromUnixTime SysTime fromUnixTime(long unixTime, TimeZone tz): Converts from unix time (i.e. seconds from midnight, January 1st, 1970 in UTC) to a SysTime.

Examples

import core.time : days, hours, seconds;
import std.datetime.date : Date, DateTime;
import std.datetime.timezone : SimpleTimeZone, UTC;

const dt = DateTime(2018, 1, 1, 10, 30, 0);
// make a specific point in time in the UTC timezone
auto st = SysTime(dt, UTC());
assert(st.year == 2018);
assert(st.hour == 10);

// cast to convert
assert(cast(DateTime) st == dt);
assert(cast(Date) st == Date(2018, 1, 1));

// make a specific point in time in the New York timezone
const ny = SysTime(dt,
    new immutable SimpleTimeZone(-5.hours, "America/New_York")
);
assert(ny != st);
assert(ny.hour == 10);

// ISO standard time strings
assert(st.toISOString() == "20180101T103000Z");
assert(st.toISOExtString() == "2018-01-01T10:30:00Z");

// add two days and 30 seconds
st += 2.days + 30.seconds;
assert(st.toISOExtString() == "2018-01-03T10:30:30Z");

See Also

$(RELATIVE_LINK2 .Clock.currTime, `Clock.currTime`) will return the current time as a SysTime.

Meta

Source

See Implementation

std datetime systime aliases

DosFileTime

classes

Clock

functions

structs

SysTime