Dates and Times

DGLux5 script stores a point in time in one of two ways:

• as a number: milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC). dateNow() and dateParse() return this.
• as a DateTime object, created with new DateTime(…). It gives you the year, month, day, and so on.

To show a date to a user, use dateFormat() with a pattern or an ICU skeleton.

On this page:

• The DateTime class
• Date functions: dateNow, dateParse, dateFormat, dateTimeZoneOffset
• Date strings that can be parsed
• Format patterns and ICU skeletons
• Examples

See also the Date Time Operations blocks.

Use DateTime, not the JavaScript Date. Date does not exist in DGLux5 script.

In DateTime, months start at 1 (January = 1). In JavaScript Date, months start at 0.

When you build a date from parts, values outside the normal range roll over. For example, day 0 is the last day of the previous month, and month 13 is January of the next year. Pass numbers only.

d = new DateTime(2017, 2, 27, 13, 27, 0);
return [d.year, d.month, d.day, d.hour, d.minute, d.second];

Output: [2017, 2, 27, 13, 27, 0]

// Day 0 of March is the last day of February.
return new DateTime(2024, 3, 0).day;

Output: 29

Members are read-only. To change a date, build a new one.

return new DateTime(2017, 8, 24).weekday;

Output: 4 (Thursday)

return new DateTime('2017-01-01T13:27:00.798').millisecond;

Output: 798

u = new DateTime(0).toUtc();
return [u.isUtc, u.year, u.month, u.day, u.hour];

Output: [true, 1970, 1, 1, 0]

dateNow()

Returns the current time in milliseconds since the epoch. This is the same as new DateTime().millisecondsSinceEpoch.

start = dateNow();
// ... do some work ...
return dateNow() - start; // elapsed milliseconds

dateParse(str)

Parses a date string and returns milliseconds since the epoch. It accepts the same strings as new DateTime(str). If the string cannot be parsed, the script fails with an error.

return dateParse("2002-02-27T19:00:00Z");

Output: 1014836400000

// The same moment, written with a different offset.
return dateParse("2002-02-27T14:00:00-0500") == dateParse("2002-02-27T19:00:00Z");

Output: true

dateFormat(date, format, [zone])

Returns date as a string, formatted with format.

• date — milliseconds since the epoch, a DateTime, or a date string.
• format — a pattern such as "yyyy-MM-dd HH:mm", or an ICU skeleton such as "yMMMd".
• zone (optional) — controls the time zone. See the table below.

Returns an empty string if date is not a number, DateTime, or string.

return dateFormat(0, "yyyy-MM-dd HH:mm:ss", true);

Output: 1970-01-01 00:00:00

return dateFormat(1500000000000, "yyyy-MM-dd HH:mm xxx", "+05:00");

Output: 2017-07-14 07:40 +05:00

return dateFormat("2020-01-01T10:00:00+05:00", "HH:mm xxx", "auto");

Output: 10:00 +05:00

return dateFormat(new DateTime(2017, 8, 24, 15, 38, 0), "EEEE, MMMM d, y 'at' h:mm a");

Output: Thursday, August 24, 2017 at 3:38 PM

dateTimeZoneOffset([zone])

Returns a time-zone offset in milliseconds.

• With no argument: the browser's current offset from UTC.
• With a number: that many hours, for example 5.5.
• With a string "hh:mm" or "-hh:mm": that offset. Other strings return NaN.

return [dateTimeZoneOffset(8), dateTimeZoneOffset("-05:30"), dateTimeZoneOffset("+05:45")];

Output: [28800000, -19800000, 20700000]

new DateTime(str), dateParse(str), and dateFormat(str, …) accept these strings. Strings longer than 40 characters are not parsed.

ISO 8601 strings. If the string has Z or an offset, it is converted to local time. Otherwise it is read as local time.

• 2012-02-27
• 2012-02-27 13:27:00
• 2012-02-27 13:27:00.123456z
• 2012-02-27T13:27:00.798
• 20120227 13:27:00
• 20120227T132700
• 20120227
• +20120227
• 2012-02-27T14Z
• 2012-02-27T14+00:00
• 2002-02-27T14:00:00-0500 (the same moment as 2002-02-27T19:00:00Z)

Other formats, always read as local time:

• yyyy-M-d, yyyy/M/d, or M/d/yyyy (US order), for example 2017/8/24 or 8/24/2017
• optionally followed by a time HH:mm:ss or HH:mm:ss.SSS (hours need two digits)
• optionally followed by am or pm, for example 8/24/2017 03:38:00 pm

A number string, such as "1500000000000", is read as milliseconds since the epoch.

A pattern is made of the letters below. Repeat a letter to change the output: for numbers, more letters add leading zeros (m → 6, mm → 06); for text, 3 letters give the short form and 4 give the full form. Any other character, such as :, -, /, or a space, is copied as is. Put other text in single quotes.

Examples are for Thursday, August 24, 2017, 15:38:05.978, in the en_US locale, in time zone UTC-8.

d = new DateTime(2017, 8, 24, 15, 38, 5);
return dateFormat(d, "yyyy-MM-dd HH:mm:ss") + " | " + dateFormat(d, "D") + " | " + dateFormat(d, "QQQQ");

Output: 2017-08-24 15:38:05 | 236 | 3rd quarter

A skeleton names a set of fields and lets the locale choose the order and punctuation. If the whole format string matches one of the skeletons below, it is used as a skeleton; otherwise it is read as a pattern.

To combine skeletons, separate them with |. Each part is formatted on its own and the results are joined. For example, yMd| |Hms gives 8/24/2017 15:38:00 (the middle part is a space).

Examples are for Thursday, August 24, 2017, 15:38:00, in the en_US locale.

d = new DateTime(2017, 8, 24, 15, 38, 0);
return dateFormat(d, "yMMMd") + " / " + dateFormat(d, "yMd| |Hms") + " / " + dateFormat(d, "jm");

Output: Aug 24, 2017 / 8/24/2017 15:38:00 / 3:38 PM

dt = new DateTime();
lastMonth = new DateTime(dt.year, dt.month, 0);
return lastMonth.day;

weekday is 7 on Sunday, so this returns the previous Sunday when today is a Sunday.

dt = new DateTime();
lastSunday = new DateTime(dt.year, dt.month, dt.day - dt.weekday);
return dateFormat(lastSunday, "yyyy-MM-dd");

ms = dateParse("2024-03-01T00:00:00Z") - dateParse("2024-02-01T00:00:00Z");
return ms / 86400000;

Output: 29

now = new DateTime();
start = new DateTime(now.year, now.month, now.day);
return start.millisecondsSinceEpoch;

Format a number of milliseconds as UTC so that the time zone does not shift it.

duration = 3725000; // 1 h 2 min 5 s
return dateFormat(duration, "HH:mm:ss", true);

Output: 01:02:05