# ParseIso
{: .no_toc }

Parses an ISO 8601 date/time string and returns the equivalent local **Date** value.

Syntax: **ParseIso** ( *utc_IsoString* ) **As Date**

*utc_IsoString*
: *required* A **String** containing an ISO 8601 date/time representation, such as `"2024-06-03T14:30:00Z"` or `"2024-06-03T14:30:00+05:30"`.

Returns a **Date** value in the local time zone corresponding to the instant described by *utc_IsoString*.

### Remarks

**ParseIso** accepts the following ISO 8601 forms:

- Date only: `YYYY-MM-DD` (no time component; midnight is assumed and no time-zone conversion is applied).
- Date and time with UTC designator: `YYYY-MM-DDTHH:MM:SSZ`.
- Date and time with a numeric UTC offset: `YYYY-MM-DDTHH:MM:SS+HH:MM` or `YYYY-MM-DDTHH:MM:SS-HH:MM`. The offset may omit minutes (`+HH` or `-HH`).
- Date and time with no offset: `YYYY-MM-DDTHH:MM:SS` (treated as UTC, then converted to local time via [**ParseUtc**](/tB/Packages/Contributed/VBA_JSON/JsonConverter/ParseUtc.md)).

The time component may omit the seconds, or the minutes and seconds (`THH:MM` or `THH`). Seconds may have a fractional part separated by a period (`.`); the fractional part is truncated, so the result is always a whole number of seconds.

When the string has a time component, **ParseIso** reads the time as UTC and converts it to local time by calling [**ParseUtc**](/tB/Packages/Contributed/VBA_JSON/JsonConverter/ParseUtc.md) internally. On Windows, that conversion uses the `SystemTimeToTzSpecificLocalTime` Win32 API and honours daylight saving time rules for the local machine. When an explicit numeric offset is present, the offset is then subtracted from the converted local time so that the returned value reflects local wall-clock time.

**ParseIso** is the inverse of [**ConvertToIso**](/tB/Packages/Contributed/VBA_JSON/JsonConverter/ConvertToIso.md).

On parse failure the function raises run-time error 10013 with the source `"UtcConverter.ParseIso"` and a message that includes the original string. A form that is not listed above, such as the basic format `20240603T090000Z` with no hyphens or colons, is a parse failure.

> [!WARNING] 2.3.1.1
> An offset written without a colon, such as `+0530`, is read as a number of hours: `+0530` is 530 hours, and `2024-06-03T14:30:00+0530` gives 12 May 2024, with no error. Write the offset as `+05:30`.

> [!WARNING] 2.3.1.1
> A string with a time on a date before 30 December 1899 gives the wrong day and time, and one before 1 January 1601 gives a meaningless date, with no error: [**ParseUtc**](/tB/Packages/Contributed/VBA_JSON/JsonConverter/ParseUtc.md) cannot convert it.

### Example

This example parses a UTC timestamp returned in a JSON payload and formats the equivalent local time.

```tb check_build
Dim Json As Object
Dim CreatedAt As Date

Set Json = ParseJson("{""created_at"":""2024-06-03T09:00:00Z""}")
CreatedAt = ParseIso(Json("created_at"))
Debug.Print Format$(CreatedAt, "yyyy-mm-dd hh:nn:ss")   ' local equivalent of 09:00 UTC
```

This example handles a timestamp that has an explicit UTC offset.

```tb check_build
Dim LocalDate As Date
LocalDate = ParseIso("2024-06-03T14:30:00+05:30")
Debug.Print Format$(LocalDate, "yyyy-mm-dd hh:nn:ss")
```

### See Also

- [ConvertToIso](/tB/Packages/Contributed/VBA_JSON/JsonConverter/ConvertToIso.md) function -- converts a local **Date** to an ISO 8601 string
- [ParseUtc](/tB/Packages/Contributed/VBA_JSON/JsonConverter/ParseUtc.md) function -- converts a UTC **Date** to local time
- [ConvertToUtc](/tB/Packages/Contributed/VBA_JSON/JsonConverter/ConvertToUtc.md) function -- converts a local **Date** to UTC
- [ParseJson](/tB/Packages/Contributed/VBA_JSON/JsonConverter/ParseJson.md) function -- parses a JSON string into a **Dictionary** or **Collection**
