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. However, that means that, unlike DateTime, it 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.

struct SysTime ;

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

Clock.currTime will return the current time as a SysTime. To convert a SysTime to a Date or DateTime, simply cast it. To convert a Date or DateTime to a SysTime, use SysTime's constructor, and pass in the ntended 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 Adds the given number of years or months to this SysTime. A negative number will subtract.
diffMonths Returns the difference between the two SysTimes in months.
fromISOExtString Creates a SysTime from a string with the format YYYY-MM-DDTHH:MM:SS.FFFFFFFTZ (where F is fractional seconds is the time zone). Whitespace is stripped from the given string.
fromISOString Creates a SysTime from a string with the format YYYYMMDDTHHMMSS.FFFFFFFTZ (where F is fractional seconds is the time zone). Whitespace is stripped from the given string.
fromSimpleString Creates a SysTime from a string with the format YYYY-MM-DD HH:MM:SS.FFFFFFFTZ (where F is fractional seconds is the time zone). Whitespace is stripped from the given string.
fromUnixTime Converts from unix time (i.e. seconds from midnight, January 1st, 1970 in UTC) to a SysTime.
opAssign
opBinary Gives the result of adding or subtracting a Duration from this SysTime.
opBinary 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 Compares this SysTime with the given SysTime.
opEquals Checks for equality between this SysTime and the given SysTime.
opOpAssign Gives the result of adding or subtracting a Duration from this SysTime, as well as assigning the result to this SysTime.
roll Adds the given number of years or months to this SysTime. A negative number will subtract.
roll Adds the given number of units to this SysTime. A negative number will subtract.
toHash
toISOExtString 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 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.

Example

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

// make a specific point in time in the UTC timezone
auto st = SysTime(DateTime(2018, 1, 1, 10, 30, 0), UTC());
// make a specific point in time in the New York timezone
auto ny = SysTime(
    DateTime(2018, 1, 1, 10, 30, 0),
    new immutable SimpleTimeZone(-5.hours, "America/New_York")
);

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