time-1.5.0.1: A time library

Safe HaskellSafe-Inferred
LanguageHaskell2010

Data.Time.Format

Contents

Synopsis

UNIX-style formatting

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

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):

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

For TimeOfDay (and LocalTime and ZonedTime and UTCTime):

%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):

%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 Source

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 Source

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 Source

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 Source

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 Source

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 Source

Arguments

:: ParseTime t 
=> TimeLocale

Time locale.

-> String

Format string.

-> String

Input string.

-> t

The time value.

Deprecated: use "parseTimeOrError True" instead

readsTime Source

Arguments

:: ParseTime t 
=> TimeLocale

Time locale.

-> String

Format string

-> ReadS t 

Deprecated: use "readSTime True" instead

class ParseTime t where Source

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

Methods

buildTime Source

Arguments

:: TimeLocale

The time locale.

-> [(Char, String)]

Pairs of format characters and the corresponding part of the input.

-> 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.

Locale

data TimeLocale Source

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 :: String

formatting strings

dateFmt :: String

formatting strings

timeFmt :: String

formatting strings

time12Fmt :: String

formatting strings

knownTimeZones :: [TimeZone]

time zones known by name

defaultTimeLocale :: TimeLocale Source

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 Source

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 Source

Format string according to RFC822.