Data.Time.Format

time-1.6.0.1: A time library

Safe Haskell | Safe
Language | Haskell2010

Data.Time.Format

Contents

- UNIX-style formatting
- UNIX-style parsing
- Locale

Synopsis

- type NumericPadOption = Maybe Char
- class FormatTime t where
- formatTime :: FormatTime t => TimeLocale -> String -> t -> String
- parseTimeM :: (Monad m, ParseTime t) => Bool -> TimeLocale -> String -> String -> m t
- parseTimeOrError :: ParseTime t => Bool -> TimeLocale -> String -> String -> t
- readSTime :: ParseTime t => Bool -> TimeLocale -> String -> ReadS t
- readPTime :: ParseTime t => Bool -> TimeLocale -> String -> ReadP t
- parseTime :: ParseTime t => TimeLocale -> String -> String -> Maybe t
- readTime :: ParseTime t => TimeLocale -> String -> String -> t
- readsTime :: ParseTime t => TimeLocale -> String -> ReadS t
- class ParseTime t where
- data TimeLocale = TimeLocale {
  - wDays :: [(String, String)]
  - months :: [(String, String)]
  - amPm :: (String, String)
  - dateTimeFmt, dateFmt, timeFmt, time12Fmt :: String
  - knownTimeZones :: [TimeZone]
  }
- defaultTimeLocale :: TimeLocale
- iso8601DateFormat :: Maybe String -> String
- rfc822DateFormat :: String

# UNIX-style formatting

type NumericPadOption = Maybe Char #

class FormatTime t where #

Minimal complete definition

formatCharacter

Methods

formatCharacter :: Char -> Maybe (TimeLocale -> Maybe NumericPadOption -> t -> String) #

Instances

FormatTime UniversalTime # |
Methods formatCharacter :: Char -> Maybe (TimeLocale -> Maybe NumericPadOption -> UniversalTime -> String) #
FormatTime Day # |
Methods formatCharacter :: Char -> Maybe (TimeLocale -> Maybe NumericPadOption -> Day -> String) #
FormatTime UTCTime # |
Methods formatCharacter :: Char -> Maybe (TimeLocale -> Maybe NumericPadOption -> UTCTime -> String) #
FormatTime TimeZone # |
Methods formatCharacter :: Char -> Maybe (TimeLocale -> Maybe NumericPadOption -> TimeZone -> String) #
FormatTime TimeOfDay # |
Methods formatCharacter :: Char -> Maybe (TimeLocale -> Maybe NumericPadOption -> TimeOfDay -> String) #
FormatTime ZonedTime # |
Methods formatCharacter :: Char -> Maybe (TimeLocale -> Maybe NumericPadOption -> ZonedTime -> String) #
FormatTime LocalTime # |
Methods formatCharacter :: Char -> Maybe (TimeLocale -> Maybe NumericPadOption -> LocalTime -> String) #

formatTime :: FormatTime t => TimeLocale -> String -> t -> String #

Substitute various time-related information for each %-code in the string, as per `formatCharacter`.

For all types (note these three are done here, not by `formatCharacter`):

`%%`
  `%`
`%t`
  tab
`%n`
  newline

glibc-style modifiers can be used before the letter (here marked as `z`):

`%-z`
  no padding
`%_z`
  pad with spaces
`%0z`
  pad with zeros
`%^z`
  convert to upper case
`%#z`
  convert to lower case (consistently, unlike glibc)

For `TimeZone` (and `ZonedTime` and `UTCTime`):

`%z`
  timezone offset in the format `-HHMM`.
`%Z`
  timezone name

For `LocalTime` (and `ZonedTime` and `UTCTime` and `UniversalTime`):

`%c`
  as `dateTimeFmt` `locale` (e.g. `%a %b %e %H:%M:%S %Z %Y`)

For `TimeOfDay` (and `LocalTime` and `ZonedTime` and `UTCTime` and `UniversalTime`):

`%R`
  same as `%H:%M`
`%T`
  same as `%H:%M:%S`
`%X`
  as `timeFmt` `locale` (e.g. `%H:%M:%S`)
`%r`
  as `time12Fmt` `locale` (e.g. `%I:%M:%S %p`)
`%P`
  day-half of day from (`amPm` `locale`), converted to lowercase, `am`, `pm`
`%p`
  day-half of day from (`amPm` `locale`), `AM`, `PM`
`%H`
  hour of day (24-hour), 0-padded to two chars, `00` - `23`
`%k`
  hour of day (24-hour), space-padded to two chars, `0` - `23`
`%I`
  hour of day-half (12-hour), 0-padded to two chars, `01` - `12`
`%l`
  hour of day-half (12-hour), space-padded to two chars, `1` - `12`
`%M`
  minute of hour, 0-padded to two chars, `00` - `59`
`%S`
  second of minute (without decimal part), 0-padded to two chars, `00` - `60`
`%q`
  picosecond of second, 0-padded to twelve chars, `000000000000` - `999999999999`.
`%Q`
  decimal point and fraction of second, up to 12 second decimals, without trailing zeros. For a whole number of seconds, `%Q` produces the empty string.

For `UTCTime` and `ZonedTime`:

`%s`
  number of whole seconds since the Unix epoch. For times before the Unix epoch, this is a negative number. Note that in `%s.%q` and `%s%Q` the decimals are positive, not negative. For example, 0.9 seconds before the Unix epoch is formatted as `-1.1` with `%s%Q`.

For `Day` (and `LocalTime` and `ZonedTime` and `UTCTime` and `UniversalTime`):

`%D`
  same as `%m/%d/%y`
`%F`
  same as `%Y-%m-%d`
`%x`
  as `dateFmt` `locale` (e.g. `%m/%d/%y`)
`%Y`
  year, no padding. Note `%0Y` and `%_Y` pad to four chars
`%y`
  year of century, 0-padded to two chars, `00` - `99`
`%C`
  century, no padding. Note `%0C` and `%_C` pad to two chars
`%B`
  month name, long form (`fst` from `months` `locale`), `January` - `December`
`%b`, `%h`
  month name, short form (`snd` from `months` `locale`), `Jan` - `Dec`
`%m`
  month of year, 0-padded to two chars, `01` - `12`
`%d`
  day of month, 0-padded to two chars, `01` - `31`
`%e`
  day of month, space-padded to two chars, `1` - `31`
`%j`
  day of year, 0-padded to three chars, `001` - `366`
`%G`
  year for Week Date format, no padding. Note `%0G` and `%_G` pad to four chars
`%g`
  year of century for Week Date format, 0-padded to two chars, `00` - `99`
`%f`
  century for Week Date format, no padding. Note `%0f` and `%_f` pad to two chars
`%V`
  week of year for Week Date format, 0-padded to two chars, `01` - `53`
`%u`
  day of week for Week Date format, `1` - `7`
`%a`
  day of week, short form (`snd` from `wDays` `locale`), `Sun` - `Sat`
`%A`
  day of week, long form (`fst` from `wDays` `locale`), `Sunday` - `Saturday`
`%U`
  week of year where weeks start on Sunday (as `sundayStartWeek`), 0-padded to two chars, `00` - `53`
`%w`
  day of week number, `0` (= Sunday) - `6` (= Saturday)
`%W`
  week of year where weeks start on Monday (as `mondayStartWeek`), 0-padded to two chars, `00` - `53`

# UNIX-style parsing

parseTimeM #

Arguments

:: (Monad m, ParseTime t) |
=> Bool | Accept leading and trailing whitespace?
-> TimeLocale | Time locale.
-> String | Format string.
-> String | Input string.
-> m t | Return the time value, or fail if the input could not be parsed using the given format.

Parses a time value given a format string. Supports the same %-codes as `formatTime`, including `%-`, `%_` and `%0` modifiers. Case is not significant. Some variations in the input are accepted:

`%z`
  accepts any of `-HHMM` or `-HH:MM`.
`%Z`
  accepts any string of letters, or any of the formats accepted by `%z`.
`%0Y`
  accepts exactly four digits.
`%0G`
  accepts exactly four digits.
`%0C`
  accepts exactly two digits.
`%0f`
  accepts exactly two digits.

parseTimeOrError #

Arguments

:: ParseTime t |
=> Bool | Accept leading and trailing whitespace?
-> TimeLocale | Time locale.
-> String | Format string.
-> String | Input string.
-> t | The time value.

Parse a time value given a format string. Fails if the input could not be parsed using the given format. See `parseTimeM` for details.

readSTime #

Arguments

:: ParseTime t |
=> Bool | Accept leading whitespace?
-> TimeLocale | Time locale.
-> String | Format string
-> ReadS t |

Parse a time value given a format string. See `parseTimeM` for details.

readPTime #

Arguments

:: ParseTime t |
=> Bool | Accept leading whitespace?
-> TimeLocale | Time locale.
-> String | Format string
-> ReadP t |

Parse a time value given a format string. See `parseTimeM` for details.

parseTime #

Arguments

:: ParseTime t |
=> TimeLocale | Time locale.
-> String | Format string.
-> String | Input string.
-> Maybe t | The time value, or `Nothing` if the input could not be parsed using the given format.

Deprecated: use "parseTimeM True" instead

readTime #

Arguments

:: ParseTime t |
=> TimeLocale | Time locale.
-> String | Format string.
-> String | Input string.
-> t | The time value.

Deprecated: use "parseTimeOrError True" instead

readsTime #

Arguments

:: ParseTime t |
=> TimeLocale | Time locale.
-> String | Format string
-> ReadS t |

Deprecated: use "readSTime True" instead

class ParseTime t where #

The class of types which can be parsed given a UNIX-style time format string.

Minimal complete definition

buildTime

Methods

buildTime :: TimeLocale -> [(Char, String)] -> Maybe t #

Builds a time value from a parsed input string. If the input does not include all the information needed to construct a complete value, any missing parts should be taken from 1970-01-01 00:00:00 +0000 (which was a Thursday). In the absence of `%C` or `%Y`, century is 1969 - 2068.

Instances

ParseTime UniversalTime # |
Methods buildTime :: TimeLocale -> [(Char, String)] -> Maybe UniversalTime #
ParseTime Day # |
Methods buildTime :: TimeLocale -> [(Char, String)] -> Maybe Day #
ParseTime UTCTime # |
Methods buildTime :: TimeLocale -> [(Char, String)] -> Maybe UTCTime #
ParseTime TimeZone # |
Methods buildTime :: TimeLocale -> [(Char, String)] -> Maybe TimeZone #
ParseTime TimeOfDay # |
Methods buildTime :: TimeLocale -> [(Char, String)] -> Maybe TimeOfDay #
ParseTime ZonedTime # |
Methods buildTime :: TimeLocale -> [(Char, String)] -> Maybe ZonedTime #
ParseTime LocalTime # |
Methods buildTime :: TimeLocale -> [(Char, String)] -> Maybe LocalTime #

# Locale

data TimeLocale #

Constructors

TimeLocale |
Fields wDays :: [(String, String)] full and abbreviated week days, starting with Sunday months :: [(String, String)] full and abbreviated months amPm :: (String, String) AM/PM symbols dateTimeFmt, dateFmt, timeFmt, time12Fmt :: String formatting strings knownTimeZones :: [TimeZone] time zones known by name

Instances

Eq TimeLocale # |
Methods (==) :: TimeLocale -> TimeLocale -> Bool # (/=) :: TimeLocale -> TimeLocale -> Bool #
Ord TimeLocale # |
Methods compare :: TimeLocale -> TimeLocale -> Ordering # (<) :: TimeLocale -> TimeLocale -> Bool # (<=) :: TimeLocale -> TimeLocale -> Bool # (>) :: TimeLocale -> TimeLocale -> Bool # (>=) :: TimeLocale -> TimeLocale -> Bool # max :: TimeLocale -> TimeLocale -> TimeLocale # min :: TimeLocale -> TimeLocale -> TimeLocale #
Show TimeLocale # |
Methods showsPrec :: Int -> TimeLocale -> ShowS Source # show :: TimeLocale -> String Source # showList :: [TimeLocale] -> ShowS Source #

defaultTimeLocale :: TimeLocale #

Locale representing American usage.

`knownTimeZones` contains only the ten time-zones mentioned in RFC 822 sec. 5: "UT", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", "PDT". Note that the parsing functions will regardless parse single-letter military time-zones and +HHMM format.

iso8601DateFormat :: Maybe String -> String #

Construct format string according to ISO-8601.

The `Maybe String` argument allows to supply an optional time specification. E.g.:

    iso8601DateFormat Nothing            == "%Y-%m-%d"           -- i.e. YYYY-MM-DD
    iso8601DateFormat (Just "%H:%M:%S")  == "%Y-%m-%dT%H:%M:%S"  -- i.e. YYYY-MM-DDTHH:MM:SS

rfc822DateFormat :: String #

Format string according to RFC822.