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 10^-12 seconds;

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"));
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);
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 toISOExtString = .Timestamp.toISOStringImp!true.toISOStringImp;

alias toString = .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");
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");

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");
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.