The OpenD Programming Language

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

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