# DateTimeFormatter

<a id="datetimeformatter"></a>

# DateTimeFormatter

```cpp
#include <icy/datetime.h>

class DateTimeFormatter
```

[Defined in src/base/include/icy/datetime.h:1142](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1142)

This class converts dates and times into strings, supporting a variety of standard and custom formats.

There are two kind of static member functions:

* format* functions return a std::string containin the formatted value.
* append* functions append the formatted value to an existing string.

## Public Static Methods

| Return | Name | Description |
|--------|------|-------------|
| `std::string` | [`format`](#format) `static` `inline` | Formats the given timestamp according to the given format. The format string is used as a template to format the date and is copied character by character except for the following special characters, which are replaced by the corresponding value. |
| `std::string` | [`format`](#format-1) `static` `inline` | Formats the given date and time according to the given format. See [format(const Timestamp&, std::string_view, int)](#format) for more information. |
| `std::string` | [`format`](#format-2) `static` `inline` | Formats the given local date and time according to the given format. See [format(const Timestamp&, std::string_view, int)](#format) for more information. |
| `std::string` | [`format`](#format-3) `static` `inline` | Formats the given timespan according to the given format. The format string is used as a template to format the date and is copied character by character except for the following special characters, which are replaced by the corresponding value. |
| `void` | [`append`](#append) `static` `inline` | Formats the given timestamp according to the given format and appends it to str. |
| `void` | [`append`](#append-1) `static` | Formats the given date and time according to the given format and appends it to str. |
| `void` | [`append`](#append-2) `static` | Formats the given local date and time according to the given format and appends it to str. |
| `void` | [`append`](#append-3) `static` | Formats the given timespan according to the given format and appends it to str. |
| `std::string` | [`tzdISO`](#tzdiso) `static` `inline` | Formats the given timezone differential in ISO format. If timeZoneDifferential is UTC, "Z" is returned, otherwise, +HH.MM (or -HH.MM) is returned. |
| `std::string` | [`tzdRFC`](#tzdrfc) `static` `inline` | Formats the given timezone differential in RFC format. If timeZoneDifferential is UTC, "GMT" is returned, otherwise ++HHMM (or -HHMM) is returned. |
| `void` | [`tzdISO`](#tzdiso-1) `static` | Formats the given timezone differential in ISO format and appends it to the given string. If timeZoneDifferential is UTC, "Z" is returned, otherwise, +HH.MM (or -HH.MM) is returned. |
| `void` | [`tzdRFC`](#tzdrfc-1) `static` | Formats the given timezone differential in RFC format and appends it to the given string. If timeZoneDifferential is UTC, "GMT" is returned, otherwise ++HHMM (or -HHMM) is returned. |

---

<a id="format"></a>

### format

`static` `inline`

```cpp
static inline std::string format(const Timestamp & timestamp, std::string_view fmt, int timeZoneDifferential = UTC)
```

[Defined in src/base/include/icy/datetime.h:1183](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1183)

Formats the given timestamp according to the given format. The format string is used as a template to format the date and is copied character by character except for the following special characters, which are replaced by the corresponding value.

* w - abbreviated weekday (Mon, Tue, ...)
* W - full weekday (Monday, Tuesday, ...)
* b - abbreviated month (Jan, Feb, ...)
* B - full month (January, February, ...)
* d - zero-padded day of month (01 .. 31)
* e - day of month (1 .. 31)
* f - space-padded day of month ( 1 .. 31)
* m - zero-padded month (01 .. 12)
* n - month (1 .. 12)
* o - space-padded month ( 1 .. 12)
* y - year without century (70)
* Y - year with century (1970)
* H - hour (00 .. 23)
* h - hour (00 .. 12)
* a - am/pm
* A - AM/PM
* M - minute (00 .. 59)
* S - second (00 .. 59)
* s - seconds and microseconds (equivalent to S.F)
* i - millisecond (000 .. 999)
* c - centisecond (0 .. 9)
* F - fractional seconds/microseconds (000000 - 999999)
* z - time zone differential in ISO 8601 format (Z or +NN.NN)
* Z - time zone differential in RFC format (GMT or +NNNN)
* %% - percent sign

Class [DateTimeFormat](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormat.md#datetimeformat) defines format strings for various standard date/time formats.

---

<a id="format-1"></a>

### format

`static` `inline`

```cpp
static inline std::string format(const DateTime & dateTime, std::string_view fmt, int timeZoneDifferential = UTC)
```

[Defined in src/base/include/icy/datetime.h:1190](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1190)

Formats the given date and time according to the given format. See [format(const Timestamp&, std::string_view, int)](#format) for more information.

---

<a id="format-2"></a>

### format

`static` `inline`

```cpp
static inline std::string format(const LocalDateTime & dateTime, std::string_view fmt)
```

[Defined in src/base/include/icy/datetime.h:1196](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1196)

Formats the given local date and time according to the given format. See [format(const Timestamp&, std::string_view, int)](#format) for more information.

---

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

### format

`static` `inline`

```cpp
static inline std::string format(const Timespan & timespan, std::string_view fmt = "%dd %H:%M:%S.%i")
```

[Defined in src/base/include/icy/datetime.h:1215](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1215)

Formats the given timespan according to the given format. The format string is used as a template to format the date and is copied character by character except for the following special characters, which are replaced by the corresponding value.

* d - days
* H - hours (00 .. 23)
* h - total hours (0 .. n)
* M - minutes (00 .. 59)
* m - total minutes (0 .. n)
* S - seconds (00 .. 59)
* s - total seconds (0 .. n)
* i - milliseconds (000 .. 999)
* c - centisecond (0 .. 9)
* F - fractional seconds/microseconds (000000 - 999999)
* %% - percent sign

---

<a id="append"></a>

### append

`static` `inline`

```cpp
static inline void append(std::string & str, const Timestamp & timestamp, std::string_view fmt, int timeZoneDifferential = UTC)
```

[Defined in src/base/include/icy/datetime.h:1222](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1222)

Formats the given timestamp according to the given format and appends it to str.

See [format()](#format) for documentation of the formatting string.

---

<a id="append-1"></a>

### append

`static`

```cpp
static void append(std::string & str, const DateTime & dateTime, std::string_view fmt, int timeZoneDifferential = UTC)
```

[Defined in src/base/include/icy/datetime.h:1229](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1229)

Formats the given date and time according to the given format and appends it to str.

See [format()](#format) for documentation of the formatting string.

---

<a id="append-2"></a>

### append

`static`

```cpp
static void append(std::string & str, const LocalDateTime & dateTime, std::string_view fmt)
```

[Defined in src/base/include/icy/datetime.h:1236](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1236)

Formats the given local date and time according to the given format and appends it to str.

See [format()](#format) for documentation of the formatting string.

---

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

### append

`static`

```cpp
static void append(std::string & str, const Timespan & timespan, std::string_view fmt = "%dd %H:%M:%S.%i")
```

[Defined in src/base/include/icy/datetime.h:1243](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1243)

Formats the given timespan according to the given format and appends it to str.

See [format()](#format) for documentation of the formatting string.

---

<a id="tzdiso"></a>

### tzdISO

`static` `inline`

```cpp
static inline std::string tzdISO(int timeZoneDifferential)
```

[Defined in src/base/include/icy/datetime.h:1249](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1249)

Formats the given timezone differential in ISO format. If timeZoneDifferential is UTC, "Z" is returned, otherwise, +HH.MM (or -HH.MM) is returned.

---

<a id="tzdrfc"></a>

### tzdRFC

`static` `inline`

```cpp
static inline std::string tzdRFC(int timeZoneDifferential)
```

[Defined in src/base/include/icy/datetime.h:1254](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1254)

Formats the given timezone differential in RFC format. If timeZoneDifferential is UTC, "GMT" is returned, otherwise ++HHMM (or -HHMM) is returned.

---

<a id="tzdiso-1"></a>

### tzdISO

`static`

```cpp
static void tzdISO(std::string & str, int timeZoneDifferential)
```

[Defined in src/base/include/icy/datetime.h:1260](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1260)

Formats the given timezone differential in ISO format and appends it to the given string. If timeZoneDifferential is UTC, "Z" is returned, otherwise, +HH.MM (or -HH.MM) is returned.

---

<a id="tzdrfc-1"></a>

### tzdRFC

`static`

```cpp
static void tzdRFC(std::string & str, int timeZoneDifferential)
```

[Defined in src/base/include/icy/datetime.h:1266](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1266)

Formats the given timezone differential in RFC format and appends it to the given string. If timeZoneDifferential is UTC, "GMT" is returned, otherwise ++HHMM (or -HHMM) is returned.

## Public Types

| Name | Description |
|------|-------------|
| [``](#unknown)  |  |

---

<a id="unknown"></a>

### 

```cpp
enum 
```

[Defined in src/base/include/icy/datetime.h:1145](https://github.com/auscaster/icey/blob/main/src/base/include/icy/datetime.h#L1145)

| Value | Description |
|-------|-------------|
| `UTC` | Special value for timeZoneDifferential denoting UTC. |