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
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
SysTime
s. 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
|
|
this
|
|
this
|
|
this
|
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
|
Adds the given number of years or months to this SysTime . A
negative number will subtract.
|
diffMonths
|
Returns the difference between the two SysTime s 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 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
|
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"