DateTime

Built-in library for date & time

Example usage

local DateTime = require("@lune/datetime")
 
-- Creates a DateTime for the current exact moment in time
local now = DateTime.now()
 
-- Formats the current moment in time as an ISO 8601 string
print(now:toIsoDate())
 
-- Formats the current moment in time, using the local
-- time, the French locale, and the specified time string
print(now:formatLocalTime("%A, %d %B %Y", "fr"))
 
-- Returns a specific moment in time as a DateTime instance
local someDayInTheFuture = DateTime.fromLocalTime({
	year = 3033,
	month = 8,
	day = 26,
	hour = 16,
	minute = 56,
	second = 28,
	millisecond = 892,
})
 
-- Extracts the current local date & time as separate values (same values as above table)
print(now:toLocalTime())
 
-- Returns a DateTime instance from a given float, where the whole
-- denotes the seconds and the fraction denotes the milliseconds
-- Note that the fraction for millis here is completely optional
DateTime.fromUnixTimestamp(871978212313.321)
 
-- Extracts the current universal (UTC) date & time as separate values
print(now:toUniversalTime())

Constructors

now

Returns a DateTime representing the current moment in time.

Returns

• DateTime The new DateTime object

fromUnixTimestamp

Creates a new DateTime from the given UNIX timestamp.

This timestamp may contain both a whole and fractional part - where the fractional part denotes milliseconds / nanoseconds.

Example usage of fractions:

• DateTime.fromUnixTimestamp(123456789.001) - one millisecond
• DateTime.fromUnixTimestamp(123456789.000000001) - one nanosecond

Note that the fractional part has limited precision down to exactly one nanosecond, any fraction that is more precise will get truncated.

Parameters

• unixTimestamp number Seconds passed since the UNIX epoch

Returns

• DateTime The new DateTime object

fromUniversalTime

Creates a new DateTime from the given date & time values table, in universal (UTC) time.

The given table must contain the following values:

An additional millisecond value may also be included, and should be within the range 0 -> 999, but is optional.

Any non-integer values in the given table will be rounded down.

Errors

This constructor is fallible and may throw an error in the following situations:

• Date units (year, month, day) were given that produce an invalid date. For example, January 32nd or February 29th on a non-leap year.

Parameters

• values DateTimeValueArguments Table containing date & time values

Returns

• DateTime The new DateTime object

fromLocalTime

Creates a new DateTime from the given date & time values table, in local time.

The given table must contain the following values:

An additional millisecond value may also be included, and should be within the range 0 -> 999, but is optional.

Any non-integer values in the given table will be rounded down.

Errors

This constructor is fallible and may throw an error in the following situations:

• Date units (year, month, day) were given that produce an invalid date. For example, January 32nd or February 29th on a non-leap year.

Parameters

• values DateTimeValueArguments Table containing date & time values

Returns

• DateTime The new DateTime object

fromIsoDate

Creates a new DateTime from an ISO 8601 date-time string.

Errors

This constructor is fallible and may throw an error if the given string does not strictly follow the ISO 8601 date-time string format.

Some examples of valid ISO 8601 date-time strings are:

• 2020-02-22T18:12:08Z
• 2000-01-31T12:34:56+05:00
• 1970-01-01T00:00:00.055Z

Parameters

• isoDate string An ISO 8601 formatted string

Returns

• DateTime The new DateTime object

Methods

formatLocalTime

Formats this DateTime using the given formatString and locale, as local time.

The given formatString is parsed using a strftime/strptime-inspired date and time formatting syntax, allowing tokens such as the following:

For a full reference of all available tokens, see the chrono documentation (opens in a new tab).

If not provided, formatString and locale will default to "%Y-%m-%d %H:%M:%S" and "en" (english) respectively.

Parameters

• self DateTime

• formatString string? A string containing formatting tokens

• locale Locale? The locale the time should be formatted in

Returns

• string The formatting string

formatUniversalTime

Formats this DateTime using the given formatString and locale, as UTC (universal) time.

The given formatString is parsed using a strftime/strptime-inspired date and time formatting syntax, allowing tokens such as the following:

For a full reference of all available tokens, see the chrono documentation (opens in a new tab).

If not provided, formatString and locale will default to "%Y-%m-%d %H:%M:%S" and "en" (english) respectively.

Parameters

• self DateTime

• formatString string? A string containing formatting tokens

• locale Locale? The locale the time should be formatted in

Returns

• string The formatting string

toIsoDate

Formats this DateTime as an ISO 8601 date-time string.

Some examples of ISO 8601 date-time strings are:

• 2020-02-22T18:12:08Z
• 2000-01-31T12:34:56+05:00
• 1970-01-01T00:00:00.055Z

Parameters

• self DateTime

Returns

• string The ISO 8601 formatted string

toLocalTime

Extracts separated local date & time values from this DateTime.

The returned table contains the following values:

Parameters

• self DateTime

Returns

• DateTimeValueReturns A table of DateTime values

toUniversalTime

Extracts separated UTC (universal) date & time values from this DateTime.

The returned table contains the following values:

Parameters

• self DateTime

Returns

• DateTimeValueReturns A table of DateTime values

Types

Locale

Enum type representing supported DateTime locales.

Currently supported locales are:

• en - English
• de - German
• es - Spanish
• fr - French
• it - Italian
• ja - Japanese
• pl - Polish
• pt-br - Brazilian Portuguese
• pt - Portuguese
• tr - Turkish

DateTimeValues

Individual date & time values, representing the primitives that make up a DateTime.

This is a dictionary that will contain the following values:

• year - Year(s), in the range 1400 -> 9999
• month - Month(s), in the range 1 -> 12
• day - Day(s), in the range 1 -> 31
• hour - Hour(s), in the range 0 -> 23
• minute - Minute(s), in the range 0 -> 59
• second - Second(s), in the range 0 -> 60, where 60 is a leap second

An additional millisecond value may also be included, and should be within the range 0 -> 999, but is optional.

However, any method returning this type should be guaranteed to include milliseconds - see individual methods to verify.

DateTimeValueArguments

Alias for DateTimeValues with an optional millisecond value.

Refer to the DateTimeValues documentation for additional information.

DateTimeValueReturns

Alias for DateTimeValues with a mandatory millisecond value.

Refer to the DateTimeValues documentation for additional information.