# DateTimeParser

<a id="datetimeparser"></a>

# DateTimeParser

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

class DateTimeParser
```

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

This class provides a method for parsing dates and times from strings. All parsing methods do their best to parse a meaningful result, even from malformed input strings.

The returned [DateTime](https://auscaster.com/icey/docs/api-reference/icy-DateTime.md#datetime) will always contain a time in the same timezone as the time in the string. Call [DateTime::makeUTC()](https://auscaster.com/icey/docs/api-reference/icy-DateTime.md#makeutc) with the timeZoneDifferential returned by [parse()](#parse) to convert the [DateTime](https://auscaster.com/icey/docs/api-reference/icy-DateTime.md#datetime) to UTC.

Note: When parsing a time in 12-hour (AM/PM) format, the hour (h) must be parsed before the AM/PM designator (a, A), otherwise the AM/PM designator will be ignored.

See the [DateTimeFormatter](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#datetimeformatter) class for a list of supported format specifiers. In addition to the format specifiers supported by [DateTimeFormatter](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#datetimeformatter), an additional specifier is supported: r will parse a year given by either two or four digits. Years 69-00 are interpreted in the 20th century (1969-2000), years 01-68 in the 21th century (2001-2068).

## Public Static Methods

| Return | Name | Description |
|--------|------|-------------|
| `void` | [`parse`](#parse) `static` | Parses a date and time in the given format from the given string. Throws a SyntaxException if the string cannot be successfully parsed. Please see [DateTimeFormatter::format()](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#format) for a description of the format string. Class [DateTimeFormat](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormat.md#datetimeformat) defines format strings for various standard date/time formats. |
| [`DateTime`](https://auscaster.com/icey/docs/api-reference/icy-DateTime.md#datetime) | [`parse`](#parse-1) `static` | Parses a date and time in the given format from the given string. Throws a SyntaxException if the string cannot be successfully parsed. Please see [DateTimeFormatter::format()](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#format) for a description of the format string. Class [DateTimeFormat](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormat.md#datetimeformat) defines format strings for various standard date/time formats. |
| `bool` | [`tryParse`](#tryparse) `static` | Parses a date and time in the given format from the given string. Returns true if the string has been successfully parsed, false otherwise. Please see [DateTimeFormatter::format()](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#format) for a description of the format string. Class [DateTimeFormat](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormat.md#datetimeformat) defines format strings for various standard date/time formats. |
| `void` | [`parse`](#parse-2) `static` | Parses a date and time from the given dateTime string. Before parsing, the method examines the dateTime string for a known date/time format. Throws a SyntaxException if the string cannot be successfully parsed. Please see [DateTimeFormatter::format()](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#format) for a description of the format string. Class [DateTimeFormat](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormat.md#datetimeformat) defines format strings for various standard date/time formats. |
| [`DateTime`](https://auscaster.com/icey/docs/api-reference/icy-DateTime.md#datetime) | [`parse`](#parse-3) `static` | Parses a date and time from the given dateTime string. Before parsing, the method examines the dateTime string for a known date/time format. Please see [DateTimeFormatter::format()](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#format) for a description of the format string. Class [DateTimeFormat](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormat.md#datetimeformat) defines format strings for various standard date/time formats. |
| `bool` | [`tryParse`](#tryparse-1) `static` | Parses a date and time from the given dateTime string. Before parsing, the method examines the dateTime string for a known date/time format. Please see [DateTimeFormatter::format()](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#format) for a description of the format string. Class [DateTimeFormat](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormat.md#datetimeformat) defines format strings for various standard date/time formats. |
| `int` | [`parseMonth`](#parsemonth) `static` | Tries to interpret the given range as a month name. The range must be at least three characters long. Returns the month number (1 .. 12) if the month name is valid. Otherwise throws a SyntaxException. |
| `int` | [`parseDayOfWeek`](#parsedayofweek) `static` | Tries to interpret the given range as a weekday name. The range must be at least three characters long. Returns the weekday number (0 .. 6, where 0 = Synday, 1 = Monday, etc.) if the weekday name is valid. Otherwise throws a SyntaxException. |

---

<a id="parse"></a>

### parse

`static`

```cpp
static void parse(std::string_view fmt, std::string_view str, DateTime & dateTime, int & timeZoneDifferential)
```

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

Parses a date and time in the given format from the given string. Throws a SyntaxException if the string cannot be successfully parsed. Please see [DateTimeFormatter::format()](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#format) for a description of the format string. Class [DateTimeFormat](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormat.md#datetimeformat) defines format strings for various standard date/time formats.

---

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

### parse

`static`

```cpp
static DateTime parse(std::string_view fmt, std::string_view str, int & timeZoneDifferential)
```

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

Parses a date and time in the given format from the given string. Throws a SyntaxException if the string cannot be successfully parsed. Please see [DateTimeFormatter::format()](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#format) for a description of the format string. Class [DateTimeFormat](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormat.md#datetimeformat) defines format strings for various standard date/time formats.

---

<a id="tryparse"></a>

### tryParse

`static`

```cpp
static bool tryParse(std::string_view fmt, std::string_view str, DateTime & dateTime, int & timeZoneDifferential)
```

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

Parses a date and time in the given format from the given string. Returns true if the string has been successfully parsed, false otherwise. Please see [DateTimeFormatter::format()](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#format) for a description of the format string. Class [DateTimeFormat](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormat.md#datetimeformat) defines format strings for various standard date/time formats.

---

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

### parse

`static`

```cpp
static void parse(std::string_view str, DateTime & dateTime, int & timeZoneDifferential)
```

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

Parses a date and time from the given dateTime string. Before parsing, the method examines the dateTime string for a known date/time format. Throws a SyntaxException if the string cannot be successfully parsed. Please see [DateTimeFormatter::format()](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#format) for a description of the format string. Class [DateTimeFormat](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormat.md#datetimeformat) defines format strings for various standard date/time formats.

---

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

### parse

`static`

```cpp
static DateTime parse(std::string_view str, int & timeZoneDifferential)
```

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

Parses a date and time from the given dateTime string. Before parsing, the method examines the dateTime string for a known date/time format. Please see [DateTimeFormatter::format()](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#format) for a description of the format string. Class [DateTimeFormat](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormat.md#datetimeformat) defines format strings for various standard date/time formats.

---

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

### tryParse

`static`

```cpp
static bool tryParse(std::string_view str, DateTime & dateTime, int & timeZoneDifferential)
```

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

Parses a date and time from the given dateTime string. Before parsing, the method examines the dateTime string for a known date/time format. Please see [DateTimeFormatter::format()](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormatter.md#format) for a description of the format string. Class [DateTimeFormat](https://auscaster.com/icey/docs/api-reference/icy-DateTimeFormat.md#datetimeformat) defines format strings for various standard date/time formats.

---

<a id="parsemonth"></a>

### parseMonth

`static`

```cpp
static int parseMonth(const char *& it, const char * end)
```

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

Tries to interpret the given range as a month name. The range must be at least three characters long. Returns the month number (1 .. 12) if the month name is valid. Otherwise throws a SyntaxException.

---

<a id="parsedayofweek"></a>

### parseDayOfWeek

`static`

```cpp
static int parseDayOfWeek(const char *& it, const char * end)
```

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

Tries to interpret the given range as a weekday name. The range must be at least three characters long. Returns the weekday number (0 .. 6, where 0 = Synday, 1 = Monday, etc.) if the weekday name is valid. Otherwise throws a SyntaxException.