smjg.libs.util.datetime

enum DAY_OF_WEEK;

Constants representing the days of the week.

enum MONTH;

Constants representing the months of the year.

immutable string[13u] SHORT_DAY_NAME;

Short (three-letter) names of the days of the week.

immutable string[13u] LONG_DAY_NAME;

Full names of the days of the week.

immutable string[13u] SHORT_MONTH_NAME;

Short (three-letter) names of the months of the year.

immutable string[13u] LONG_MONTH_NAME;

Full names of the months of the year.

const int[13u] MONTH_LEN;

The length of each month in a common year.

bool isLeapYear(int year);

Determines whether the given year is a leap year.

int timeZoneOffset;

The local time zone offset from UTC in minutes.

A positive value indicates a zone ahead of UTC; a negative value behind. Under Windows, this is automatically initialised to the system time zone.

Todo:: implement initialisation on platforms other than Windows.

bool allowFieldOverflow;

Whether to allow alignment fields to overflow.

If this is false, a DateTimeFormatException will be thrown if the formatted content of a field exceeds the field's specified width.

int monthLength(int month, int year);

Determines the length of a month.

Params:

int month	month whose length is to be found.
int year	year in which the month occurs.

Returns:: the length of the given month in days.

struct DateInterval;

The DateInterval structure represents an interval between date values, specified in days.

YEAR: a common (non-leap) year
YEAR_4: a period of four years, assumed not to include the night of 28 February-1 March in a centennial common year
YEAR_100: a century, assumed not to include 29 February in a quatercentennial leap year
YEAR_400: a period of 400 years.

struct TimeInterval;

The TimeInterval structure represents an interval between time values, specified in milliseconds.

MS SECOND MINUTE HOUR DAY: Constants representing units of time.

struct DateTimeInterval;

The DateTimeInterval structure represents an interval in both date and time.

DateInterval datePart;

The date component of the interval in days.

TimeInterval timePart;

The time component of the interval in milliseconds.

In a normalised interval, this value will be in the interval [0..TimeInterval.DAY).

this(int days, int millis);

Constructs a DateTimeInterval from the given date and time intervals.

Params:

int days	date interval in days.
int millis	time interval in milliseconds.

this(DateInterval days);

Constructs a DateTimeInterval equal to a given date interval.

this(TimeInterval millis);

Constructs a DateTimeInterval equal to a given time interval.

this(long millis);

Constructs a DateTimeInterval equal to a given value in milliseconds.

@property DateTimeInterval normalise();

Normalises this DateTimeInterval in place.

The timePart will be normalised to the range [0..TimeInterval.DAY), and datePart will be adjusted accordingly.

All methods of DateTimeInterval (except for adding or subtracting a DateInterval from an already unnormalised DateTimeInterval) return a normalised interval where applicable. This method is provided so that you can normalise the interval after modifying timePart directly.

Returns:: this interval.

const @property long milliseconds();

The value of this DateTimeInterval in milliseconds.

const @property int hour();

const @property int minute();

const @property int second();

const @property int millisecond();

const @property string toString();

Returns a string representation in the form e.g. "10 days 12:34:56.789".

const bool opEquals(DateTimeInterval di);

Since:: 0.10

const int opCmp(DateTimeInterval di);

Since:: 0.10

struct DateValue;

The DateValue structure represents a calendar date.

int dayNo;

The internal numerical representation of the date, in days from 1 January 1BC (as it would be defined in the Gregorian calendar).

A value of int.min denotes an invalid or null date.

deprecated alias YEAR; deprecated alias YEAR_4; deprecated alias YEAR_100; deprecated alias YEAR_400;

Deprecated:: now defined in DateInterval

this(int day);

Constructs a DateValue with the given dayNo value.

this(int year, int month, int day);

Constructs a DateValue representing the given date.

Params:

int year	the year.
int month	the month, from 1 (January) to 12 (December). A MONTH value can be used.
int day	the day of the month.

Throws:: DateTimeException if month or day is out of range.

BUGS:: will not work with dates before 1BC.

static @property DateValue now();

Retrieves the current system date.

BUGS:: always gets the date in the system time zone, even if timeZoneOffset has been overridden.

Todo:: Implement on platforms other than Windows.

const DateValue nearest(DAY_OF_WEEK w);

Calculates the nearest w to this date.

const string format(string formatString);

Formats this date according to a format string.

Params:

string formatString	the format string, as defined in smjg.libs.util.datetimeformat.

Returns:: the formatted date string.

Throws:: DateTimeFormatException if the formatting fails, e.g. because of an error in the format string.

const @property int year();

const @property MONTH month();

const @property int day();

const @property DAY_OF_WEEK dayOfWeek();

const @property string toString();

Returns a string representation in the form e.g. "Sat 8 May 2004".

const char[] toFormatString(uint flags = 1);

Formats this date according to the OS-defined format.

Params:

uint flags	a value to pass to the OS date-formatting API determining how to format the date.

Returns:: a string representation of this date in the OS-defined format.

Todo:: implement on platforms other than Windows.

const @property char[] toShortFormatString();

Formats this date according to the OS-defined short format.

Returns:: a string representation of the date in the OS-defined short format.

Todo:: Implement on platforms other than Windows.

const @property char[] toLongFormatString();

Formats this date according to the OS-defined long format.

Returns:: a string representation of the date in the OS-defined long format.

Todo:: Implement on platforms other than Windows.

const DateValue opAdd(int i);

Adds the given interval in days to this date.

const DateValue opSub(int i);

Subtracts the given interval in days from this date.

const DateInterval opSub(DateValue d);

Calculates the interval in days between this date and d.

DateValue opAddAssign(int i);

Adds the given interval in days to this date.

DateValue opSubAssign(int i);

Subtracts the given interval in days from this date.

struct TimeValue;

The TimeValue structure represents a time within a day.

int utcMillis;

The internal numerical representation of the time.

This value is in milliseconds from 00:00 UTC. It must be in the range 0..86401000 or be int.min, representing an invalid or null time.

deprecated alias SECOND; deprecated alias MINUTE; deprecated alias HOUR; deprecated alias DAY;

Deprecated:: now defined in TimeInterval

this(int ms);

Constructs a TimeValue with the given UTC millisecond value.

this(int hour, int minute, int second = 0, int ms = 0); this(int hour, int minute, float second);

Constructs a TimeValue representing the given local time.

static @property TimeValue now();

Retrieves the current system time.

Todo:: implement on platforms other than Windows.

const string format(string formatString);

Formats this time according to a format string.

Params:

string formatString	the format string, as defined in smjg.libs.util.datetimeformat.

Returns:: the formatted date string.

Throws:: DateTimeFormatException if the formatting fails, e.g. because of an error in the format string.

const @property int localMillis(); @property int localMillis(int ms);

The time in milliseconds from midnight in local time.

const @property int hour();

const @property int minute();

const @property int second();

const @property int millisecond();

const @property int localDayOffset();

Returns the offset of the local time calendar date from the UTC date.

Returns:: -1 if the local date is the day before UTC date, e.g. 01:00 UTC when the time zone is UTC-02:00. 0 if the local date equals the UTC date. 1 if the local date is the day after UTC date, e.g. 23:00 UTC when the time zone is UTC+02:00.

const @property string toString();

Returns a string representation in the form e.g. "22:12:31.278".

const char[] toFormatString(uint flags);

Formats this time according to the OS-defined format.

Params:

uint flags	a value to pass to the OS time-formatting API determining how to format the time.

Returns:: a string representation of this time in the OS-defined format.

Todo:: implement on platforms other than Windows.

const TimeValue opAdd(TimeInterval i);

Adds the given interval in milliseconds to this time.

const TimeValue opSub(TimeInterval i);

Subtracts the given interval in milliseconds from this time.

const TimeInterval opSub(TimeValue d);

Calculates the interval in milliseconds between this time and another time.

TimeValue opAddAssign(TimeInterval i);

Adds the given interval in milliseconds to this time.

TimeValue opSubAssign(TimeInterval i);

Subtracts the given interval in milliseconds from this time.

struct DateTime;

The DateTime structure represents a combination of date and time.

BUGS:: checking for invalid/null components not fully implemented.

DateValue utcDate;

The date component in UTC.

TimeValue utcTime;

The time component.

this(DateValue d, TimeValue t = TimeValue(0,0));

Constructs a DateTime from the given date and time.

Params:

DateValue d	the date component in local time.
TimeValue t	the time component.

this(int year, int month, int day, int hour, int minute, int second = 0, int ms = 0); this(int year, int month, int day, int hour, int minute, float second);

Constructs a DateTime representing the given local date and time combination.

static @property DateTime now();

Retrieves the current system date and time.

Todo:: Implement on platforms other than Windows.

const string format(string formatString);

Formats this date according to a format string.

Params:

string formatString	the format string, as defined in smjg.libs.util.datetimeformat.

Returns:: the formatted date string.

Throws:: DateTimeFormatException if the formatting fails, e.g. because of an error in the format string.

const @property real unixTime(); @property real unixTime(real ut);

The date/time as a Unix timestamp, i.e. seconds since the epoch, 00:00 UTC on 1 January 1970.

const @property DateValue date(); @property DateValue date(DateValue d);

The date component in local time.

const @property TimeValue time(); @property TimeValue time(TimeValue t);

The time component. Setting this property preserves the local time date.

const @property int year();

const @property MONTH month();

const @property int day();

const @property DAY_OF_WEEK dayOfWeek();

const @property int hour();

const @property int minute();

const @property int second();

const @property int millisecond();

const @property string toString();

Returns a string representation in the form e.g. "Sat 8 May 2004 22:12:31.278".

const DateTime opAdd(DateInterval di);

Adds the given date interval to the date component.

const DateTime opAdd(TimeInterval ti);

Adds the given time interval to this date and time.

const DateTime opAdd(DateTimeInterval dti);

Adds the given date and time interval to this date and time.

const DateTime opSub(DateInterval di);

Subtracts the given date interval from the date component.

const DateTime opSub(TimeInterval ti);

Subtracts the given time interval from this date and time.

const DateTime opSub(DateTimeInterval dti);

Subtracts the given date and time interval from this date and time.

const DateTimeInterval opSub(DateTime dt);

Determines the time interval between this and another DateTime.

DateTime opAddAssign(DateInterval di);

Adds the given date interval to the date component.

DateTime opAddAssign(TimeInterval ti);

Adds the given time interval to this date and time.

DateTime opAddAssign(DateTimeInterval dti);

Adds the given date and time interval to this date and time.

DateTime opSubAssign(DateInterval di);

Subtracts the given date interval from the date component.

DateTime opSubAssign(TimeInterval ti);

Subtracts the given time interval from this date and time.

DateTime opSubAssign(DateTimeInterval dti);

Subtracts the given date and time interval from this date and time.

class DateTimeException: object.Exception;

Exception thrown when a date/time operation fails, e.g. because some component values are out of range.

struct DateTimeComponents;

The DateTimeComponents structure represents a date and time in structured form.

int year; MONTH month; byte day; byte hour; byte minute; byte second; short millisecond;

Components of the date and time.

Any of these may be set to the .min value of its type, representing an unspecified component.

this(DateValue dv);

Constructs a DateTimeComponents of the given date, with the time components left unspecified.

this(TimeValue tv);

Constructs a DateTimeComponents of the given time, with the date components left unspecified.

this(DateTime dt);

Constructs a DateTimeComponents of the given date and time.

const string format(string formatString);

Formats this date and time according to a format string.

Params:

string formatString	the format string, as defined in smjg.libs.util.datetimeformat.

Returns:: the formatted date string.

Throws:: DateTimeFormatException if the formatting fails, e.g. because of an error in the format string.

const @property DateValue dateValue(); @property DateValue dateValue(DateValue dv);

The DateValue corresponding to the date stored in this DateTimeComponents.

Throws:: DateTimeException if the date stored in this DateTimeComponents is invalid or incomplete.

const @property TimeValue timeValue(); @property TimeValue timeValue(TimeValue tv);

The TimeValue corresponding to the time stored in this DateTimeComponents.

Throws:: DateTimeException if the time stored in this DateTimeComponents is invalid or incomplete.