elm-iso8601

A pure Elm library for ISO 8601 time parsing and handling.

See Elm Packages for the documentation.

image by XKCD

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 core 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
• Specific error messages

TODO

• Get the day of the week
• Support for simple math (Add, Subtract and Durations)
• Support the ISO 8601 range syntax

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