# 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 Frech 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())
```

## Functions

### toIsoDate

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

Some examples of ISO 8601 date-time strings:

-   `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 local 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

-   `DateTimeValues` A table of DateTime values

---

### toUniversalTime

Extracts UTC (universal) 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

-   `DateTimeValues` A table of DateTime values

---

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

---

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

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

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

-   Date units (year, month, day) that produce an invalid date will raise an error. For example,
    January 32nd or February 29th on a non-leap year.
-   Non-integer values are rounded down. For example, providing 2.5 hours is equivalent to providing
    2 hours, not 2 hours and 30 minutes.

#### Parameters

-   `values` `DateTimeValues` 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 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`      |

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

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

-   Date units (year, month, day) that produce an invalid date will raise an error. For example,
    January 32nd or February 29th on a non-leap year.
-   Non-integer values are rounded down. For example, providing 2.5 hours is equivalent to providing
    2 hours, not 2 hours and 30 minutes.

#### Parameters

-   `values` `DateTimeValues` Table containing date & time values

#### Returns

-   `DateTime` The new DateTime object

---

### fromIsoDate

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

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:

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

---