# DateTime

Built-in library for date & time

#### Example usage

```lua
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:

| Key      | Type     | Range          |
| -------- | -------- | -------------- |
| `year`   | `number` | `1400 -> 9999` |
| `month`  | `number` | `1 -> 12`      |
| `day`    | `number` | `1 -> 31`      |
| `hour`   | `number` | `0 -> 23`      |
| `minute` | `number` | `0 -> 59`      |
| `second` | `number` | `0 -> 60`      |

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:

| Key      | Type     | Range          |
| -------- | -------- | -------------- |
| `year`   | `number` | `1400 -> 9999` |
| `month`  | `number` | `1 -> 12`      |
| `day`    | `number` | `1 -> 31`      |
| `hour`   | `number` | `0 -> 23`      |
| `minute` | `number` | `0 -> 59`      |
| `second` | `number` | `0 -> 60`      |

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:

| Token | Example  | Description   |
| ----- | -------- | ------------- |
| `%Y`  | `1998`   | Year number   |
| `%m`  | `04`     | Month number  |
| `%d`  | `29`     | Day number    |
| `%A`  | `Monday` | Weekday name  |
| `%M`  | `59`     | Minute number |
| `%S`  | `10`     | Second number |

For a full reference of all available tokens, see the
[chrono documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).

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:

| Token | Example  | Description   |
| ----- | -------- | ------------- |
| `%Y`  | `1998`   | Year number   |
| `%m`  | `04`     | Month number  |
| `%d`  | `29`     | Day number    |
| `%A`  | `Monday` | Weekday name  |
| `%M`  | `59`     | Minute number |
| `%S`  | `10`     | Second number |

For a full reference of all available tokens, see the
[chrono documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).

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:

| Key           | Type     | Range          |
| ------------- | -------- | -------------- |
| `year`        | `number` | `1400 -> 9999` |
| `month`       | `number` | `1 -> 12`      |
| `day`         | `number` | `1 -> 31`      |
| `hour`        | `number` | `0 -> 23`      |
| `minute`      | `number` | `0 -> 59`      |
| `second`      | `number` | `0 -> 60`      |
| `millisecond` | `number` | `0 -> 999`     |

#### 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:

| Key           | Type     | Range          |
| ------------- | -------- | -------------- |
| `year`        | `number` | `1400 -> 9999` |
| `month`       | `number` | `1 -> 12`      |
| `day`         | `number` | `1 -> 31`      |
| `hour`        | `number` | `0 -> 23`      |
| `minute`      | `number` | `0 -> 59`      |
| `second`      | `number` | `0 -> 60`      |
| `millisecond` | `number` | `0 -> 999`     |

#### 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.

---