mir.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;

ulong fractionCoefficient;

Fraction

The fractionExponent and fractionCoefficient 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);

this(Duration)(const Duration duration)
if (Duration.stringof == "Duration");

Creates a fake timestamp from a Duration using total!"hnsecs" method. For positive and zero timestamps the format is wwww-dd-88Thh:mm:ss.nnnnnnn and for negative timestamps wwww-dd-99Thh:mm:ss.nnnnnnn.

Examples:

import core.time : Duration, weeks, days, hours, minutes, seconds, hnsecs;

auto duration = 5.weeks + 2.days + 7.hours + 40.minutes + 4.seconds + 9876543.hnsecs;
Timestamp ts = duration;

assert(ts.toISOExtString == `0005-02-88T07:40:04.9876543Z`);
assert(duration == cast(Duration) ts);

duration = -duration;
ts = Timestamp(duration);
assert(ts.toISOExtString == `0005-02-99T07:40:04.9876543Z`);
assert(duration == cast(Duration) ts);

assert(Timestamp(Duration.zero).toISOExtString == `0000-00-88T00:00:00.0000000Z`);

const T opCast(T)()
if (__traits(hasMember, T, "AllowedTypes"));

Decomposes Timestamp to an algebraic type. Supported types up to T.stringof equivalence:

• Year
• YearMonth
• YearMonthDay
• Date
• date
• TimeOfDay
• DateTime
• SysTime
• Timestamp as fallback type

Throws:

an exception if timestamp cannot be converted to an algebraic type and there is no Timestamp type in the Algebraic set.

Examples:

import core.time : hnsecs, minutes, Duration;
import mir.algebraic;
import mir.date: Date; // Can be other Date type as well
import std.datetime.date : TimeOfDay, DateTime;
import std.datetime.systime : SysTime;
import std.datetime.timezone: UTC, SimpleTimeZone;

alias A = Variant!(Date, TimeOfDay, DateTime, Duration, SysTime, Timestamp, string); // non-date-time types is OK
assert(cast(A) Timestamp(1023) == Timestamp(1023)); // Year isn't represented in the algebraic, use fallback type
assert(cast(A) Timestamp.onlyTime(7, 40, 30) == TimeOfDay(7, 40, 30));
assert(cast(A) Timestamp(1982, 4, 1, 20, 59, 22) == DateTime(1982, 4, 1, 20, 59, 22));

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

const T opCast(T)()
if (T.stringof == "Year" || T.stringof == "YearMonth" || T.stringof == "YearMonthDay" || T.stringof == "Date" || T.stringof == "date" || T.stringof == "TimeOfDay" || T.stringof == "Duration" || T.stringof == "DateTime" || T.stringof == "SysTime");

Casts timestamp to a date-time type.

Supported types up to T.stringof equivalence:

• Year
• YearMonth
• YearMonthDay
• Date
• date
• TimeOfDay
• DateTime
• SysTime

const pure nothrow @nogc @property @safe long getFraction(int digits)()
if (digits >= 1 && (digits <= 12));

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[.mmm]±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[.mmm]±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");

const pure nothrow @nogc @safe long toUnixTime();

Examples:

assert(Timestamp(1970, 1, 1).toUnixTime == 0);
assert(Timestamp(2007, 12, 22, 8, 14, 45).toUnixTime == 1_198_311_285);
assert(Timestamp(2007, 12, 22, 8, 14, 45).withOffset(90).toUnixTime == 1_198_311_285);
assert(Timestamp(1969, 12, 31, 23, 59, 59).toUnixTime == -1);

static pure nothrow @nogc @safe Timestamp fromUnixTime(long time);

Examples:

import mir.format;
assert(Timestamp.fromUnixTime(0) == Timestamp(1970, 1, 1, 0, 0, 0));
assert(Timestamp.fromUnixTime(1_198_311_285) == Timestamp(2007, 12, 22, 8, 14, 45));
assert(Timestamp.fromUnixTime(-1) == Timestamp(1969, 12, 31, 23, 59, 59));

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[.mmm]±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.

const pure nothrow @nogc @property @safe bool isDuration();

const pure nothrow @nogc @property @safe bool isNegativeDuration();