ISO8601

This package provides functionality for working with time and strings based on the ISO 8601 standard i.e. 2016-03-31T12:13:14.22-04:00

It is a "pure" Elm package – no Native bindings to Javascript's Date are used. This does have a performance cost. This package is about 10x slower than the native Date library. But there are advantages:

Does not cast the time in the local timezone
Preserves the timezone offset values
Detects invalid dates
Provides a record with easy access to the time's components

If you have worked with time in Javascript you may have come across issues where the time is recast in the local timezone – not fun.

For example with Elm.Date (which uses Javascript)

Date.fromString "2016-01-01T01:30:00-04:00" \
  |> Result.map (\d -> Date.year d)
--Ok 2015 : Result.Result String Int

While the above is the correct time, it is looses its context – year is 2015!

Now with ISO8601

import ISO8601

t = ISO8601.fromString "2016-01-01T01:30:00-04:00"
-- Ok { year = 2016, month = 1, day = 1, hour = 1, minute = 30, second = 0, millisecond = 0, offset = (-4,0) }
    : Result.Result String ISO8601.Time

t |> Result.map .year
-- Ok 2016 : Result.Result String Int

ISO8601 strives to offer better error handling:

import Date
import ISO8601

-- The below is not a valid date...
Date.fromString "2014-02-30"
-- Ok {} : Result.Result String Date.Date

ISO8601.fromString "2014-02-30"
--- Err ("day is out of range") : Result.Result String ISO8601.Time

Error messages specify the first error found:


Date.fromString "2014-04-02T13:01:61"
-- Err ("unable to parse '2014-04-02T13:01:61' as a date")

ISO8601.fromString "2014-04-02T13:01:61"
-- Err ("second is out of range") : Result.Result String ISO8601.Time

Time record

type alias Time =

{ year : Int

, month : Int

, day : Int

, hour : Int

, minute : Int

, second : Int

, millisecond : Int

, offset : ( Int, Int )

}

Record representing the time. Offset is tuple representing the hour and minute ± from UTC.

Parsing

fromString : String -> Result String Time

Given an ISO 8601 compatible string, returns a Time record.

ISO8601.fromString "2016-01-01T01:30:00-04:00"
-- { year = 2016, month = 1, day = 1, hour = 1, minute = 30, second = 0, millisecond = 0, offset = (-4,0) }
    : ISO8601.Time
ISO8601.fromString "2016-11-07"
--{ year = 2016, month = 11, day = 7, hour = 0, minute = 0, second = 0, millisecond = 0, offset = (0,0) }
    : ISO8601.Time
```

toString : Time -> String

Converts a Time record to an ISO 8601 formated string.

Time conversion

toTime : Time -> Int

Converts the Time to milliseconds relative to the Unix epoch: 1970-01-01T00:00:00Z

fromTime : Int -> Time

Converts the milliseconds relative to the Unix epoch to a Time record.

Modules

ISO8601

jweir/elm-iso8601/2.0.0

ISO8601

Time record

Parsing

Time conversion

Modules