text-iso8601-0.1.1: Converting time to and from ISO 8601 text.

Safe Haskell | None
Language | Haskell2010

Data.Time.FromText

Description

The RFC3339 grammar is below

    date-fullyear   = 4DIGIT
    date-month      = 2DIGIT  ; 01-12
    date-mday       = 2DIGIT  ; 01-28, 01-29, 01-30, 01-31 based on month/year
    time-hour       = 2DIGIT  ; 00-23
    time-minute     = 2DIGIT  ; 00-59
    time-second     = 2DIGIT  ; 00-58, 00-59, 00-60 based on leap second rules
    time-secfrac    = "." 1*DIGIT
    time-numoffset  = ("+" / "-") time-hour ":" time-minute
    time-offset     = "Z" / time-numoffset

    partial-time    = time-hour ":" time-minute ":" time-second [time-secfrac]
    full-date       = date-fullyear "-" date-month "-" date-mday
    full-time       = partial-time time-offset

    date-time       = full-date "T" full-time

The parsers are a bit more lenient:

- We also accept space instead of `T` date-time separator. (Allowed by RFC3339, forbidden by ISO8601)
- Seconds are optional (allowed by ISO8601)
- numerical timezone offset can be just `("+" / "-") time-hour` or without a colon: `("+" / "-") time-hour time-minute` (allowed by ISO8601). However we require colons in between hours, minutes and seconds in the time (`partial-time`) production, and dashes in `full-date` production.
- We allow over 4 digits in the year part (and that is a reason to require dashes).
- We allow `-00:00` time offset. (Allowed by RFC3339, forbidden by ISO8601)
- We always allow time with 60 seconds, we don't consult any leap second database.

Synopsis

- parseDay :: Text -> Either String Day
- parseLocalTime :: Text -> Either String LocalTime
- parseTimeOfDay :: Text -> Either String TimeOfDay
- parseTimeZone :: Text -> Either String TimeZone
- parseUTCTime :: Text -> Either String UTCTime
- parseZonedTime :: Text -> Either String ZonedTime
- parseYear :: Text -> Either String Year
- parseMonth :: Text -> Either String Month
- parseQuarter :: Text -> Either String Quarter
- parseQuarterOfYear :: Text -> Either String QuarterOfYear

# Documentation

parseDay :: Text -> Either String Day #

Parse a date of the form `[+-]YYYY-MM-DD`.

The year must contain at least 4 digits, to avoid the Y2K problem: a two-digit year `YY` may mean `YY`, `19YY`, or `20YY`, and we make it an error to prevent the ambiguity. Years from `0000` to `0999` must thus be zero-padded. The year may have more than 4 digits.

parseLocalTime :: Text -> Either String LocalTime #

Parse a date and time, of the form `YYYY-MM-DD HH:MM[:SS[.SSS]]`. The space may be replaced with a `T`. The number of seconds is optional and may be followed by a fractional component.

parseTimeOfDay :: Text -> Either String TimeOfDay #

Parse a time of the form `HH:MM[:SS[.SSS]]`.

parseTimeZone :: Text -> Either String TimeZone #

Parse a time zone.

The accepted formats are `Z`, `+HH`, `+HHMM`, or `+HH:MM`. (`+` can be `-`).

Accepts `-23:59..23:59` range, i.e. `HH < 24` and `MM < 59`. (This is consistent with grammar, and with what Python, Clojure, joda-time do).

parseUTCTime :: Text -> Either String UTCTime #

Behaves as `zonedTime`, but converts any time zone offset into a UTC time.

parseZonedTime :: Text -> Either String ZonedTime #

Parse a date with time zone info. Acceptable formats:

    YYYY-MM-DD HH:MMZ
    YYYY-MM-DD HH:MM:SSZ
    YYYY-MM-DD HH:MM:SS.SSSZ

The first space may instead be a `T`, and the second space is optional. The `Z` represents UTC. The `Z` may be replaced with a time zone offset of the form `+0000` or `-08:00`, where the first two digits are hours, the `:` is optional and the second two digits (also optional) are minutes.

parseYear :: Text -> Either String Year #

Parse a year `[+-]YYYY`, with at least 4 digits. Can include a sign.

See also `parseDay` for details about the year format.

Note: `Year` is a type synonym for `Integer`.

parseMonth :: Text -> Either String Month #

Parse a month of the form `[+-]YYYY-MM`.

See also `parseDay` for details about the year format.

parseQuarter :: Text -> Either String Quarter #

Parse a quarter of the form `[+-]YYYY-QN`.

See also `parseDay` for details about the year format.

parseQuarterOfYear :: Text -> Either String QuarterOfYear #

Parse a quarter of year of the form `QN` or `qN`.