# time

<a id="time-3"></a>

# time

Classes and functions for handling time.

## Functions

| Return | Name | Description |
|--------|------|-------------|
| `std::time_t` | [`now`](#now)  | Returns the current wall-clock time as a UTC time_t (seconds since epoch). |
| `double` | [`clockSecs`](#clocksecs)  | Returns the elapsed process time in decimal seconds using a monotonic clock. |
| `std::string` | [`print`](#print-9)  | Formats a broken-down time value using the given strftime format string. |
| `std::string` | [`printLocal`](#printlocal)  | Formats the current local time using the given strftime format string. |
| `std::string` | [`printUTC`](#printutc)  | Formats the current UTC time using the given strftime format string. |
| `std::tm` | [`toLocal`](#tolocal)  | Converts a time_t value to a broken-down local time structure. Uses thread-safe native functions (localtime_r / localtime_s). |
| `std::tm` | [`toUTC`](#toutc)  | Converts a time_t value to a broken-down UTC time structure. Uses thread-safe native functions (gmtime_r / gmtime_s). |
| `std::string` | [`getLocal`](#getlocal)  | Returns the current local time as an ISO8601 formatted string. |
| `std::string` | [`getUTC`](#getutc)  | Returns the current UTC time as an ISO8601 formatted string. |
| `uint64_t` | [`hrtime`](#hrtime)  | Returns the current high-resolution monotonic time in nanoseconds. |

---

<a id="now"></a>

### now

```cpp
std::time_t now()
```

[Defined in src/base/include/icy/time.h:48](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L48)

Returns the current wall-clock time as a UTC time_t (seconds since epoch). 
#### Returns
Current UTC time in seconds since the Unix epoch.

---

<a id="clocksecs"></a>

### clockSecs

```cpp
double clockSecs()
```

[Defined in src/base/include/icy/time.h:52](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L52)

Returns the elapsed process time in decimal seconds using a monotonic clock. 
#### Returns
[Process](https://auscaster.com/icey/docs/api-reference/icy-Process.md#process-3) time in seconds.

---

<a id="print-9"></a>

### print

```cpp
std::string print(const std::tm & dt, const char * fmt = ISO8601Format)
```

[Defined in src/base/include/icy/time.h:58](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L58)

Formats a broken-down time value using the given strftime format string. 
#### Returns
Formatted time string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `dt` | `const std::tm &` | Broken-down time to format. |
| `fmt` | `const char *` | strftime format string (default: ISO8601Format). |

---

<a id="printlocal"></a>

### printLocal

```cpp
std::string printLocal(const char * fmt = ISO8601Format)
```

[Defined in src/base/include/icy/time.h:63](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L63)

Formats the current local time using the given strftime format string. 
#### Returns
Formatted local time string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `fmt` | `const char *` | strftime format string (default: ISO8601Format). |

---

<a id="printutc"></a>

### printUTC

```cpp
std::string printUTC(const char * fmt = ISO8601Format)
```

[Defined in src/base/include/icy/time.h:68](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L68)

Formats the current UTC time using the given strftime format string. 
#### Returns
Formatted UTC time string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `fmt` | `const char *` | strftime format string (default: ISO8601Format). |

---

<a id="tolocal"></a>

### toLocal

```cpp
std::tm toLocal(const std::time_t & time)
```

[Defined in src/base/include/icy/time.h:74](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L74)

Converts a time_t value to a broken-down local time structure. Uses thread-safe native functions (localtime_r / localtime_s). 
#### Returns
Broken-down local time.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `time` | `const std::time_t &` | UTC time value to convert. |

---

<a id="toutc"></a>

### toUTC

```cpp
std::tm toUTC(const std::time_t & time)
```

[Defined in src/base/include/icy/time.h:80](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L80)

Converts a time_t value to a broken-down UTC time structure. Uses thread-safe native functions (gmtime_r / gmtime_s). 
#### Returns
Broken-down UTC time.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `time` | `const std::time_t &` | UTC time value to convert. |

---

<a id="getlocal"></a>

### getLocal

```cpp
std::string getLocal()
```

[Defined in src/base/include/icy/time.h:84](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L84)

Returns the current local time as an ISO8601 formatted string. 
#### Returns
ISO8601 local time string.

---

<a id="getutc"></a>

### getUTC

```cpp
std::string getUTC()
```

[Defined in src/base/include/icy/time.h:88](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L88)

Returns the current UTC time as an ISO8601 formatted string. 
#### Returns
ISO8601 UTC time string.

---

<a id="hrtime"></a>

### hrtime

```cpp
uint64_t hrtime()
```

[Defined in src/base/include/icy/time.h:92](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L92)

Returns the current high-resolution monotonic time in nanoseconds. 
#### Returns
Current time in nanoseconds (suitable for measuring intervals).

## Variables

| Return | Name | Description |
|--------|------|-------------|
| `const int64_t` | [`kNumMillisecsPerSec`](#knummillisecspersec) `static` | Constants for calculating time. |
| `const int64_t` | [`kNumMicrosecsPerSec`](#knummicrosecspersec) `static` |  |
| `const int64_t` | [`kNumNanosecsPerSec`](#knumnanosecspersec) `static` |  |
| `const int64_t` | [`kNumMicrosecsPerMillisec`](#knummicrosecspermillisec) `static` |  |
| `const int64_t` | [`kNumNanosecsPerMillisec`](#knumnanosecspermillisec) `static` |  |
| `const int64_t` | [`kNumNanosecsPerMicrosec`](#knumnanosecspermicrosec) `static` |  |
| `const char *` | [`ISO8601Format`](#iso8601format) `static` | The date/time format defined in the ISO 8601 standard. This is the default format used throughout the library for consistency. |

---

<a id="knummillisecspersec"></a>

### kNumMillisecsPerSec

`static`

```cpp
const int64_t kNumMillisecsPerSec = INT64_C(1000)
```

[Defined in src/base/include/icy/time.h:30](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L30)

Constants for calculating time.

---

<a id="knummicrosecspersec"></a>

### kNumMicrosecsPerSec

`static`

```cpp
const int64_t kNumMicrosecsPerSec = INT64_C(1000000)
```

[Defined in src/base/include/icy/time.h:31](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L31)

---

<a id="knumnanosecspersec"></a>

### kNumNanosecsPerSec

`static`

```cpp
const int64_t kNumNanosecsPerSec = INT64_C(1000000000)
```

[Defined in src/base/include/icy/time.h:32](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L32)

---

<a id="knummicrosecspermillisec"></a>

### kNumMicrosecsPerMillisec

`static`

```cpp
const int64_t kNumMicrosecsPerMillisec = kNumMicrosecsPerSec / kNumMillisecsPerSec
```

[Defined in src/base/include/icy/time.h:34](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L34)

---

<a id="knumnanosecspermillisec"></a>

### kNumNanosecsPerMillisec

`static`

```cpp
const int64_t kNumNanosecsPerMillisec = kNumNanosecsPerSec / kNumMillisecsPerSec
```

[Defined in src/base/include/icy/time.h:35](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L35)

---

<a id="knumnanosecspermicrosec"></a>

### kNumNanosecsPerMicrosec

`static`

```cpp
const int64_t kNumNanosecsPerMicrosec = kNumNanosecsPerSec / kNumMicrosecsPerSec
```

[Defined in src/base/include/icy/time.h:36](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L36)

---

<a id="iso8601format"></a>

### ISO8601Format

`static`

```cpp
const char * ISO8601Format = "%Y-%m-%dT%H:%M:%SZ"
```

[Defined in src/base/include/icy/time.h:44](https://github.com/auscaster/icey/blob/main/src/base/include/icy/time.h#L44)

The date/time format defined in the ISO 8601 standard. This is the default format used throughout the library for consistency.

Examples: 2005-01-01T12:00:00+01:00 2005-01-01T11:00:00Z