Report a bug
If you spot a problem with this page, click here to create a GitHub 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 a local clone.

mir.timestamp

Timestamp
class DateTimeException: object.Exception;
pure nothrow @nogc @safe this(string msg, string file = __FILE__, size_t line = __LINE__, Throwable nextInChain = null);

pure nothrow @nogc @safe this(string msg, Throwable nextInChain, string file = __FILE__, size_t line = __LINE__);
struct Timestamp;
Timestamp

Note The component values in the binary encoding are always in UTC, while components in the text encoding are in the local time! This means that transcoding requires a conversion between UTC and local time.

Timestamp precision is up to picosecond (second/10^12).

enum Precision: ubyte;
year
month
day
minute
second
fraction
pure @nogc @safe this(scope const(char)[] str);
Examples:
assert(Timestamp("2010-07-04") == Timestamp(2010, 7, 4));
assert(Timestamp("20100704") == Timestamp(2010, 7, 4));
assert(Timestamp(2021, 01, 29, 12, 42, 44).withOffset(7 * 60 + 30) == Timestamp.fromISOString("20210129T201244+0730"));
static assert(Timestamp(2021, 01, 29,  4, 42, 44).withOffset(- (7 * 60 + 30)) == Timestamp.fromISOExtString("2021-01-28T21:12:44-07:30"));

assert(Timestamp("T0740Z") == Timestamp.onlyTime(7, 40));
assert(Timestamp("T074030Z") == Timestamp.onlyTime(7, 40, 30));
assert(Timestamp("T074030.056Z") == Timestamp.onlyTime(7, 40, 30, -3, 56));

assert(Timestamp("07:40Z") == Timestamp.onlyTime(7, 40));
assert(Timestamp("07:40:30Z") == Timestamp.onlyTime(7, 40, 30));
assert(Timestamp("T07:40:30.056Z") == Timestamp.onlyTime(7, 40, 30, -3, 56));
short year;
Year
Precision precision;
ubyte month;
Month
If the value equals to thero then this and all the following members are undefined.
ubyte day;
Day
If the value equals to thero then this and all the following members are undefined.
ubyte hour;
Hour
ubyte minute;
Minute

Note the field is implemented as property.

ubyte second;
Second

Note the field is implemented as property.

byte fractionExponent;

long fractionCoefficient;
Fraction
The fraction_exponent and fraction_coefficient denote the fractional seconds of the timestamp as a decimal value The fractional seconds’ value is coefficient * 10 ^ exponent. It must be greater than or equal to zero and less than 1. A missing coefficient defaults to zero. Fractions whose coefficient is zero and exponent is greater than -1 are ignored.
'fractionCoefficient' allowed values are [0 ... 10^12-1]. 'fractionExponent' allowed values are [-12 ... 0].

Note the fields are implemented as property.

pure nothrow @nogc @safe this(short year);
pure nothrow @nogc @safe this(short year, ubyte month);
pure nothrow @nogc @safe this(short year, ubyte month, ubyte day);
pure nothrow @nogc @safe this(short year, ubyte month, ubyte day, ubyte hour, ubyte minute);
pure nothrow @nogc @safe this(short year, ubyte month, ubyte day, ubyte hour, ubyte minute, ubyte second);
pure nothrow @nogc @safe this(short year, ubyte month, ubyte day, ubyte hour, ubyte minute, ubyte second, byte fractionExponent, ulong fractionCoefficient);
static pure nothrow @nogc @safe Timestamp onlyTime(ubyte hour, ubyte minute);
static pure nothrow @nogc @safe Timestamp onlyTime(ubyte hour, ubyte minute, ubyte second);
static pure nothrow @nogc @safe Timestamp onlyTime(ubyte hour, ubyte minute, ubyte second, byte fractionExponent, ulong fractionCoefficient);
this(Date)(const Date datetime)
if (Date.stringof == "Date" || Date.stringof == "date");
Examples:
import mir.date : Date;
auto dt = Date(1982, 4, 1);
Timestamp ts = dt;
assert(ts.opCmp(ts) == 0);
assert(dt.toISOExtString == ts.toString);
assert(dt == cast(Date) ts);
Examples:
import std.datetime.date : Date;
auto dt = Date(1982, 4, 1);
Timestamp ts = dt;
assert(dt.toISOExtString == ts.toString);
assert(dt == cast(Date) ts);
this(TimeOfDay)(const TimeOfDay timeOfDay)
if (TimeOfDay.stringof == "TimeOfDay");
Examples:
import std.datetime.date : TimeOfDay;
auto dt = TimeOfDay(7, 14, 30);
Timestamp ts = dt;
assert(dt.toISOExtString ~ "Z" == ts.toString);
assert(dt == cast(TimeOfDay) ts);
this(DateTime)(const DateTime datetime)
if (DateTime.stringof == "DateTime");
Examples:
import std.datetime.date : DateTime;
auto dt = DateTime(1982, 4, 1, 20, 59, 22);
Timestamp ts = dt;
assert(dt.toISOExtString ~ "Z" == ts.toString);
assert(dt == cast(DateTime) ts);
this(SysTime)(const SysTime systime)
if (SysTime.stringof == "SysTime");
Examples:
import core.time : hnsecs, minutes;
import std.datetime.date : DateTime;
import std.datetime.timezone : SimpleTimeZone;
import std.datetime.systime : SysTime;

auto dt = DateTime(1982, 4, 1, 20, 59, 22);
auto tz = new immutable SimpleTimeZone(-330.minutes);
auto st = SysTime(dt, 1234567.hnsecs, tz);
Timestamp ts = st;

assert(st.toISOExtString == ts.toString);
assert(st == cast(SysTime) ts);
const T opCast(T)()
if (T.stringof == "YearMonth" || T.stringof == "YearMonthDay" || T.stringof == "Date" || T.stringof == "TimeOfDay" || T.stringof == "date" || T.stringof == "DateTime" || T.stringof == "SysTime");
const pure nothrow @nogc @property @safe bool isOnlyTime();
Returns:
true if timestamp represent a time only value.
const pure nothrow @nogc @safe int opCmp(Timestamp rhs);
const pure nothrow @nogc @safe Timestamp withOffset(short minutes);
Attaches local offset, doesn't adjust other fields. Local-time offsets may be represented as either hour*60+minute offsets from UTC, or as the zero to denote a local time of UTC. They are required on timestamps with time and are not allowed on date values.
alias toString = .Timestamp.toISOStringImp!true.toISOStringImp;

alias toISOExtString = .Timestamp.toISOStringImp!true.toISOStringImp;
Converts this Timestamp to a string with the format YYYY-MM-DDThh:mm:ss±hh:mm.
If w writer is set, the resulting string will be written directly to it.
Returns:
A string when not using an output range; void otherwise.
Examples:
assert(Timestamp.init.toString == "0000T");
assert(Timestamp(2010, 7, 4).toString == "2010-07-04");
assert(Timestamp(1998, 12, 25).toString == "1998-12-25");
assert(Timestamp(0, 1, 5).toString == "0000-01-05");
assert(Timestamp(-4, 1, 5).toString == "-0004-01-05");

// YYYY-MM-DDThh:mm:ss±hh:mm
assert(Timestamp(2021).toString == "2021T");
assert(Timestamp(2021, 01).toString == "2021-01T", Timestamp(2021, 01).toString);
assert(Timestamp(2021, 01, 29).toString == "2021-01-29");
assert(Timestamp(2021, 01, 29, 19, 42).toString == "2021-01-29T19:42Z");
assert(Timestamp(2021, 01, 29, 12, 42, 44).withOffset(7 * 60).toString == "2021-01-29T19:42:44+07", Timestamp(2021, 01, 29, 12, 42, 44).withOffset(7 * 60).toString);
assert(Timestamp(2021, 01, 29, 12, 42, 44).withOffset(7 * 60 + 30).toString == "2021-01-29T20:12:44+07:30");

assert(Timestamp.onlyTime(7, 40).toString == "07:40Z");
assert(Timestamp.onlyTime(7, 40, 30).toString == "07:40:30Z");
assert(Timestamp.onlyTime(7, 40, 30, -3, 56).toString == "07:40:30.056Z");
Examples:
// Test A.D.
assert(Timestamp(9, 12, 4).toISOExtString == "0009-12-04");
assert(Timestamp(99, 12, 4).toISOExtString == "0099-12-04");
assert(Timestamp(999, 12, 4).toISOExtString == "0999-12-04");
assert(Timestamp(9999, 7, 4).toISOExtString == "9999-07-04");
assert(Timestamp(10000, 10, 20).toISOExtString == "+10000-10-20");

// Test B.C.
assert(Timestamp(0, 12, 4).toISOExtString == "0000-12-04");
assert(Timestamp(-9, 12, 4).toISOExtString == "-0009-12-04");
assert(Timestamp(-99, 12, 4).toISOExtString == "-0099-12-04");
assert(Timestamp(-999, 12, 4).toISOExtString == "-0999-12-04");
assert(Timestamp(-9999, 7, 4).toISOExtString == "-9999-07-04");
assert(Timestamp(-10000, 10, 20).toISOExtString == "-10000-10-20");

assert(Timestamp.onlyTime(7, 40).toISOExtString == "07:40Z");
assert(Timestamp.onlyTime(7, 40, 30).toISOExtString == "07:40:30Z");
assert(Timestamp.onlyTime(7, 40, 30, -3, 56).toISOExtString == "07:40:30.056Z");

const cdate = Timestamp(1999, 7, 6);
immutable idate = Timestamp(1999, 7, 6);
assert(cdate.toISOExtString == "1999-07-06");
assert(idate.toISOExtString == "1999-07-06");
alias toISOString = .Timestamp.toISOStringImp!false.toISOStringImp;
Converts this Timestamp to a string with the format YYYYMMDDThhmmss±hhmm.
If w writer is set, the resulting string will be written directly to it.
Returns:
A string when not using an output range; void otherwise.
Examples:
assert(Timestamp.init.toISOString == "0000T");
assert(Timestamp(2010, 7, 4).toISOString == "20100704");
assert(Timestamp(1998, 12, 25).toISOString == "19981225");
assert(Timestamp(0, 1, 5).toISOString == "00000105");
assert(Timestamp(-4, 1, 5).toISOString == "-00040105");

// YYYYMMDDThhmmss±hhmm
assert(Timestamp(2021).toISOString == "2021T");
assert(Timestamp(2021, 01).toISOString == "2021-01T"); // always extended
assert(Timestamp(2021, 01, 29).toISOString == "20210129");
assert(Timestamp(2021, 01, 29, 19, 42).toISOString == "20210129T1942Z");
assert(Timestamp(2021, 01, 29, 12, 42, 44).withOffset(7 * 60).toISOString == "20210129T194244+07");
assert(Timestamp(2021, 01, 29, 12, 42, 44).withOffset(7 * 60 + 30).toISOString == "20210129T201244+0730");
static assert(Timestamp(2021, 01, 29, 12, 42, 44).withOffset(7 * 60 + 30).toISOString == "20210129T201244+0730");

assert(Timestamp.onlyTime(7, 40).toISOString == "T0740Z");
assert(Timestamp.onlyTime(7, 40, 30).toISOString == "T074030Z");
assert(Timestamp.onlyTime(7, 40, 30, -3, 56).toISOString == "T074030.056Z");
pure nothrow @nogc @safe void addMinutes(short minutes);
Helpfer for time zone offsets
alias fromISOString = .Timestamp.fromISOStringImpl!false.fromISOStringImpl(C)(scope const(C)[] str) if (isSomeChar!C);
Creates a Timestamp from a string with the format `YYYYMMDDThhmmss±hhmm or its leading part allowed by the standard.
or its leading part allowed by the standard.
Parameters:
const(C)[] str A string formatted in the way that .Timestamp.toISOExtString formats dates.
Timestamp value (optional) result value.
Throws:
DateTimeException if the given string is not in the correct format. Two arguments overload is nothrow.
Returns:
bool on success for two arguments overload, and the resulting timestamp for single argument overdload.
Examples:
assert(Timestamp.fromISOString("20100704") == Timestamp(2010, 7, 4));
assert(Timestamp.fromISOString("19981225") == Timestamp(1998, 12, 25));
assert(Timestamp.fromISOString("00000105") == Timestamp(0, 1, 5));
// assert(Timestamp.fromISOString("-00040105") == Timestamp(-4, 1, 5));

assert(Timestamp(2021) == Timestamp.fromISOString("2021"));
assert(Timestamp(2021) == Timestamp.fromISOString("2021T"));
// assert(Timestamp(2021, 01) == Timestamp.fromISOString("2021-01"));
// assert(Timestamp(2021, 01) == Timestamp.fromISOString("2021-01T"));
assert(Timestamp(2021, 01, 29) == Timestamp.fromISOString("20210129"));
assert(Timestamp(2021, 01, 29, 19, 42) == Timestamp.fromISOString("20210129T1942"));
assert(Timestamp(2021, 01, 29, 19, 42) == Timestamp.fromISOString("20210129T1942Z"));
assert(Timestamp(2021, 01, 29, 19, 42, 12) == Timestamp.fromISOString("20210129T194212"));
assert(Timestamp(2021, 01, 29, 19, 42, 12, -3, 67) == Timestamp.fromISOString("20210129T194212.067Z"));
assert(Timestamp(2021, 01, 29, 12, 42, 44).withOffset(7 * 60) == Timestamp.fromISOString("20210129T194244+07"));
assert(Timestamp(2021, 01, 29, 12, 42, 44).withOffset(7 * 60 + 30) == Timestamp.fromISOString("20210129T201244+0730"));
static assert(Timestamp(2021, 01, 29, 12, 42, 44).withOffset(7 * 60 + 30) == Timestamp.fromISOString("20210129T201244+0730"));
static assert(Timestamp(2021, 01, 29,  4, 42, 44).withOffset(- (7 * 60 + 30)) == Timestamp.fromISOString("20210128T211244-0730"));
alias fromISOExtString = .Timestamp.fromISOStringImpl!true.fromISOStringImpl(C)(scope const(C)[] str) if (isSomeChar!C);
Creates a Timestamp from a string with the format YYYY-MM-DDThh:mm:ss±hh:mm or its leading part allowed by the standard.
Parameters:
const(C)[] str A string formatted in the way that .Timestamp.toISOExtString formats dates.
Timestamp value (optional) result value.
Throws:
DateTimeException if the given string is not in the correct format. Two arguments overload is nothrow.
Returns:
bool on success for two arguments overload, and the resulting timestamp for single argument overdload.
Examples:
assert(Timestamp.fromISOExtString("2010-07-04") == Timestamp(2010, 7, 4));
assert(Timestamp.fromISOExtString("1998-12-25") == Timestamp(1998, 12, 25));
assert(Timestamp.fromISOExtString("0000-01-05") == Timestamp(0, 1, 5));
assert(Timestamp.fromISOExtString("-0004-01-05") == Timestamp(-4, 1, 5));

assert(Timestamp(2021) == Timestamp.fromISOExtString("2021"));
assert(Timestamp(2021) == Timestamp.fromISOExtString("2021T"));
assert(Timestamp(2021, 01) == Timestamp.fromISOExtString("2021-01"));
assert(Timestamp(2021, 01) == Timestamp.fromISOExtString("2021-01T"));
assert(Timestamp(2021, 01, 29) == Timestamp.fromISOExtString("2021-01-29"));
assert(Timestamp(2021, 01, 29, 19, 42) == Timestamp.fromISOExtString("2021-01-29T19:42"));
assert(Timestamp(2021, 01, 29, 19, 42) == Timestamp.fromISOExtString("2021-01-29T19:42Z"));
assert(Timestamp(2021, 01, 29, 19, 42, 12) == Timestamp.fromISOExtString("2021-01-29T19:42:12"));
assert(Timestamp(2021, 01, 29, 19, 42, 12, -3, 67) == Timestamp.fromISOExtString("2021-01-29T19:42:12.067Z"));
assert(Timestamp(2021, 01, 29, 12, 42, 44).withOffset(7 * 60) == Timestamp.fromISOExtString("2021-01-29T19:42:44+07"));
assert(Timestamp(2021, 01, 29, 12, 42, 44).withOffset(7 * 60 + 30) == Timestamp.fromISOExtString("2021-01-29T20:12:44+07:30"));
static assert(Timestamp(2021, 01, 29, 12, 42, 44).withOffset(7 * 60 + 30) == Timestamp.fromISOExtString("2021-01-29T20:12:44+07:30"));
static assert(Timestamp(2021, 01, 29,  4, 42, 44).withOffset(- (7 * 60 + 30)) == Timestamp.fromISOExtString("2021-01-28T21:12:44-07:30"));
pure nothrow @nogc @safe bool fromString(C)(scope const(C)[] str, out Timestamp value);

pure @safe Timestamp fromString(C)(scope const(C)[] str)
if (isSomeChar!C);
Creates a Timestamp from a string with the format YYYY-MM-DD, YYYYMMDD, or YYYY-Mon-DD.
Parameters:
const(C)[] str A string formatted in the way that .Timestamp.toISOExtString and .Timestamp.toISOString format dates. The function is case sensetive.
Timestamp value (optional) result value.
Throws:
DateTimeException if the given string is not in the correct format. Two arguments overload is nothrow.
Returns:
bool on success for two arguments overload, and the resulting timestamp for single argument overdload.