# Timestamps

Provides utility functions for working with date, time, and UNIX timestamps.

***

## Accessing the Module

```lua
local TIMESTAMPS <const> = exports.boii_utils:get("modules.timestamps")
```

***

## Server

### get\_timestamp()

Gets the current UNIX timestamp and its formatted string.

#### Returns

| Name      | Type   | Description                |
| --------- | ------ | -------------------------- |
| timestamp | number | Current UNIX timestamp     |
| formatted | string | Formatted date-time string |

#### Example

```lua
local time = TIMESTAMPS.get_timestamp()
print(time.timestamp)  -- 1700000000
print(time.formatted)  -- "2025-03-29 18:00:00"
```

***

### convert\_timestamp(timestamp)

Converts a UNIX timestamp to a readable date and time.

#### Parameters

| Name      | Type   | Description               |
| --------- | ------ | ------------------------- |
| timestamp | number | UNIX timestamp to convert |

#### Returns

| Name | Type   | Description          |
| ---- | ------ | -------------------- |
| date | string | Date in `YYYY-MM-DD` |
| time | string | Time in `HH:MM:SS`   |
| both | string | Full datetime string |

#### Example

```lua
local result = TIMESTAMPS.convert_timestamp(os.time())
print(result.both) -- "2025-03-29 18:00:00"
```

***

### get\_current\_date\_time()

Gets the current full date and time information.

#### Returns

| Name      | Type   | Description           |
| --------- | ------ | --------------------- |
| timestamp | number | UNIX timestamp        |
| date      | string | `YYYY-MM-DD`          |
| time      | string | `HH:MM:SS`            |
| both      | string | Full formatted string |

#### Example

```lua
local now = TIMESTAMPS.get_current_date_time()
print(now.date, now.time)
```

***

### add\_days\_to\_date(date, days)

Adds days to a given date.

#### Parameters

| Name | Type   | Description               |
| ---- | ------ | ------------------------- |
| date | string | Base date in `YYYY-MM-DD` |
| days | number | Number of days to add     |

#### Returns

| Type   | Description              |
| ------ | ------------------------ |
| string | New date in `YYYY-MM-DD` |

#### Example

```lua
local new_date = TIMESTAMPS.add_days_to_date("2025-03-29", 7)
print(new_date) -- "2025-04-05"
```

***

### date\_difference(start\_date, end\_date)

Calculates the number of days between two dates.

#### Parameters

| Name        | Type   | Description             |
| ----------- | ------ | ----------------------- |
| start\_date | string | Start date `YYYY-MM-DD` |
| end\_date   | string | End date `YYYY-MM-DD`   |

#### Returns

| Name | Type   | Description                 |
| ---- | ------ | --------------------------- |
| days | number | Absolute difference in days |

#### Example

```lua
local diff = TIMESTAMPS.date_difference("2025-03-01", "2025-03-29")
print(diff.days) -- 28
```

***

### convert\_timestamp\_ms(timestamp\_ms)

Converts a millisecond-based UNIX timestamp to human-readable format.

#### Parameters

| Name          | Type   | Description                    |
| ------------- | ------ | ------------------------------ |
| timestamp\_ms | number | UNIX timestamp in milliseconds |

#### Returns

| Name | Type   | Description           |
| ---- | ------ | --------------------- |
| date | string | `YYYY-MM-DD`          |
| time | string | `HH:MM:SS`            |
| both | string | Full formatted string |

#### Example

```lua
local readable = TIMESTAMPS.convert_timestamp_ms(1700000000000)
print(readable.both) -- "2025-03-29 18:00:00"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.boii.dev/old-docs/boii_utils/api/timestamps.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.