View source code
Display the source code in std/datetime/systime.d from which this page was generated on github.
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone.

Struct std.datetime.systime.SysTime

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.

struct SysTime ;

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.

Constructors

NameDescription
this ()
this ()
this ()
this ()

Properties

NameTypeDescription
day[get] ubyteDay of a Gregorian Month.
day[set] intDay of a Gregorian Month.
dayOfGregorianCal[get] intThe Xth day of the Gregorian Calendar that this SysTime is on.
dayOfGregorianCal[set] intThe Xth day of the Gregorian Calendar that this SysTime is on. Setting this property does not affect the time portion of SysTime.
dayOfWeek[get] DayOfWeekDay of the week this SysTime is on.
dayOfYear[get] ushortDay of the year this SysTime is on.
dayOfYear[set] intDay of the year.
daysInMonth[get] ubyteThe last day in the month that this SysTime is in.
dstInEffect[get] boolReturns whether DST is in effect for this SysTime.
endOfMonth[get] SysTimeSysTime for the last day in the month that this Date is in. The time portion of endOfMonth is always 23:59:59.9999999.
fracSecs[get] DurationFractional seconds past the second (i.e. the portion of a SysTime which is less than a second).
fracSecs[set] DurationFractional seconds past the second (i.e. the portion of a SysTime which is less than a second).
hour[get] ubyteHours past midnight.
hour[set] intHours past midnight.
isAD[get] boolWhether the current year is a date in A.D.
isLeapYear[get] boolWhether this SysTime is in a leap year.
isoWeek[get] ubyteThe ISO 8601 week of the year that this SysTime is in.
julianDay[get] longThe 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[get] SysTimeReturns the SysTime farthest in the future which is representable by SysTime.
min[get] SysTimeReturns the SysTime farthest in the past which is representable by SysTime.
minute[get] ubyteMinutes past the current hour.
minute[set] intMinutes past the current hour.
modJulianDay[get] longThe modified Julian day for any time on this date (since, the modified Julian day changes at midnight).
month[get] MonthMonth of a Gregorian Year.
month[set] MonthMonth of a Gregorian Year.
second[get] ubyteSeconds past the current minute.
second[set] intSeconds past the current minute.
stdTime[get] longThe total hnsecs from midnight, January 1st, 1 A.D. UTC. This is the internal representation of SysTime.
stdTime[set] longThe total hnsecs from midnight, January 1st, 1 A.D. UTC. This is the internal representation of SysTime.
timezone[get] immutable(TimeZone)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[set] immutable(TimeZone)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[get] DurationReturns what the offset from UTC is for this SysTime. It includes the DST offset in effect at that time (if any).
year[get] shortYear of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.
year[set] intYear of the Gregorian Calendar. Positive numbers are A.D. Non-positive are B.C.
yearBC[get] ushortYear B.C. of the Gregorian Calendar counting year 0 as 1 B.C.
yearBC[set] intYear B.C. of the Gregorian Calendar counting year 0 as 1 B.C.

Methods

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

See Also

Clock.currTime will return the current time as a SysTime.

Example

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());
writeln(st.year); // 2018
writeln(st.hour); // 10

// cast to convert
writeln(cast(DateTime)st); // dt
writeln(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);
writeln(ny.hour); // 10

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

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

Authors

Jonathan M Davis

License

Boost License 1.0.