Display the source code in std/datetime/systime.d from which this page was generated on github.

If you spot a problem with this page, click here to create a Bugzilla issue.

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

Name	Description
`this` (dateTime, tz)
`this` (dateTime, fracSecs, tz)
`this` (date, tz)
`this` (stdTime, tz)

Properties

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

Methods

Name	Description
`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 `SysTime`s 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 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 is the time zone). Whitespace is stripped from the given string.
`fromSimpleString` (simpleString, tz)	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` (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 `SysTime`s.
`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` ()	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.

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.