text-icu-0.8.0.5: Bindings to the ICU library

Copyright | (c) 2021 Torsten Kemps-Benedix
License | BSD-style
Maintainer | bos@serpentine.com
Stability | experimental
Portability | GHC
Safe Haskell | None
Language | Haskell98

Data.Text.ICU.DateFormatter

Description

Calendar formatter implemented as bindings to the International Components for Unicode (ICU) libraries. You display or print a Date by first converting it to a locale-specific string that conforms to the conventions of the end user’s Locale. For example, Germans recognize 20.4.98 as a valid date, and Americans recognize 42098.

👉 Note: The appropriate Calendar support is required for different locales. For example, the Buddhist calendar is the official calendar in Thailand so the typical assumption of Gregorian Calendar usage should not be used. ICU will pick the appropriate Calendar based on the locale you supply when opening a Calendar or DateFormat.

Date and time formatters are used to convert dates and times from their internal representations to textual form in a language-independent manner.

Synopsis

- data DateFormatter
- data FormatStyle
  - = FullFormatStyle
  - | LongFormatStyle
  - | MediumFormatStyle
  - | ShortFormatStyle
  - | DefaultFormatStyle
  - | RelativeFormatStyle
  - | NoFormatStyle
- data DateFormatSymbolType
  - = Eras
  - | Months
  - | ShortMonths
  - | Weekdays
  - | ShortWeekdays
  - | AmPms
  - | LocalizedChars
  - | EraNames
  - | NarrowMonths
  - | NarrowWeekdays
  - | StandaloneMonths
  - | StandaloneWeekdays
  - | StandaoneShortWeekdays
  - | StandaloneNarrowWeekdays
  - | Quarters
  - | ShortQuarters
  - | StandaloneQuarters
  - | ShorterWeekdays
  - | StandaloneShorterWeekdays
  - | CyclicYearsWide
  - | CyclicYearsAbbreviated
  - | CyclicYearsNarrow
  - | ZodiacNamesWide
  - | ZodiacNamesAbbreviated
  - | ZodiacNamesNarrow
  - | NarrowQuarters
  - | StandaloneNarrowQuarters
- standardDateFormatter :: FormatStyle -> FormatStyle -> LocaleName -> Text -> IO DateFormatter
- patternDateFormatter :: Text -> LocaleName -> Text -> IO DateFormatter
- dateSymbols :: DateFormatter -> DateFormatSymbolType -> [Text]
- formatCalendar :: DateFormatter -> Calendar -> Text

# Documentation

data DateFormatter Source #

This is an abstract data type holding a reference to the ICU date format object. Create a `DateFormatter` with either `standardDateFormatter` or `patternDateFormatter` and use it in order to format `Calendar` objects with the function `formatCalendar`.

data FormatStyle Source #

The possible date/time format styles.

Constructors

FullFormatStyle | Full style, such as Tuesday, April 12, 1952 AD or 3:30:42pm PST
LongFormatStyle | Long style, such as January 12, 1952 or 3:30:32pm
MediumFormatStyle | Medium style, such as Jan. 12, 1952
ShortFormatStyle | Short style, such as 121352 or 3:30pm
DefaultFormatStyle | Default style

RelativeFormatStyle

Relative style: ICU currently provides limited support for formatting dates using a “relative” style, specified using RELATIVE_SHORT, RELATIVE_MEDIUM, RELATIVE_LONG or RELATIVE_FULL. As currently implemented, relative date formatting only affects the formatting of dates within a limited range of calendar days before or after the current date, based on the CLDR type="day"/relative data: For example, in English, “Yesterday”, “Today”, and “Tomorrow”. Within this range, the specific relative style currently makes no difference. Outside of this range, relative dates are formatted using the corresponding non-relative style (SHORT, MEDIUM, etc.). Relative time styles are not currently supported, and behave just like the corresponding non-relative style.

NoFormatStyle | No style.

#### Instances

Instances details

Enum FormatStyle Source # |

Instance details

Defined in Data.Text.ICU.DateFormatter

Methods

succ :: FormatStyle -> FormatStyle Source #

pred :: FormatStyle -> FormatStyle Source #

toEnum :: Int -> FormatStyle Source #

fromEnum :: FormatStyle -> Int Source #

enumFrom :: FormatStyle -> [FormatStyle] Source #

enumFromThen :: FormatStyle -> FormatStyle -> [FormatStyle] Source #

enumFromTo :: FormatStyle -> FormatStyle -> [FormatStyle] Source #

enumFromThenTo :: FormatStyle -> FormatStyle -> FormatStyle -> [FormatStyle] Source #

Show FormatStyle Source # |
Instance details Defined in Data.Text.ICU.DateFormatter Methods showsPrec :: Int -> FormatStyle -> ShowS Source # show :: FormatStyle -> String Source # showList :: [FormatStyle] -> ShowS Source #
Eq FormatStyle Source # |
Instance details Defined in Data.Text.ICU.DateFormatter Methods (==) :: FormatStyle -> FormatStyle -> Bool Source # (/=) :: FormatStyle -> FormatStyle -> Bool Source #

data DateFormatSymbolType Source #

The possible types of date format symbols.

Constructors

Eras | The era names, for example AD.
Months | The month names, for example February.
ShortMonths | The short month names, for example Feb.
Weekdays | The CLDR-style format "wide" weekday names, for example Monday.
ShortWeekdays | The CLDR-style format "abbreviated" (not "short") weekday names, for example "Mon." For the CLDR-style format "short" weekday names, use UDAT_SHORTER_WEEKDAYS.
AmPms | The AM/PM names, for example AM.
LocalizedChars | The localized characters.
EraNames | The long era names, for example Anno Domini.
NarrowMonths | The narrow month names, for example F.
NarrowWeekdays | The CLDR-style format "narrow" weekday names, for example M.
StandaloneMonths | Standalone context versions of months.
StandaloneWeekdays | The CLDR-style stand-alone "wide" weekday names.
StandaoneShortWeekdays | The CLDR-style stand-alone "abbreviated" (not "short") weekday names. For the CLDR-style stand-alone "short" weekday names, use UDAT_STANDALONE_SHORTER_WEEKDAYS.
StandaloneNarrowWeekdays | The CLDR-style stand-alone "narrow" weekday names.
Quarters | The quarters, for example 1st Quarter.
ShortQuarters | The short quarter names, for example Q1.
StandaloneQuarters | Standalone context versions of quarters.
ShorterWeekdays | The CLDR-style short weekday names, e.g. Su, Mo", etc. These are named SHORTER to contrast with the constants using SHORT above, which actually get the CLDR-style abbreviated versions of the corresponding names.
StandaloneShorterWeekdays | Standalone version of UDAT_SHORTER_WEEKDAYS.
CyclicYearsWide | Cyclic year names (only supported for some calendars, and only for FORMAT usage; udat_setSymbols not supported for UDAT_CYCLIC_YEARS_WIDE)
CyclicYearsAbbreviated | Cyclic year names (only supported for some calendars, and only for FORMAT usage)
CyclicYearsNarrow | Cyclic year names (only supported for some calendars, and only for FORMAT usage; udat_setSymbols not supported for UDAT_CYCLIC_YEARS_NARROW)
ZodiacNamesWide | Calendar zodiac names (only supported for some calendars, and only for FORMAT usage; udat_setSymbols not supported for UDAT_ZODIAC_NAMES_WIDE)
ZodiacNamesAbbreviated | Calendar zodiac names (only supported for some calendars, and only for FORMAT usage)
ZodiacNamesNarrow | Calendar zodiac names (only supported for some calendars, and only for FORMAT usage; udat_setSymbols not supported for UDAT_ZODIAC_NAMES_NARROW)
NarrowQuarters | The narrow quarter names, for example 1.
StandaloneNarrowQuarters | The narrow standalone quarter names, for example 1.

standardDateFormatter :: FormatStyle -> FormatStyle -> LocaleName -> Text -> IO DateFormatter Source #

Create a new `DateFormatter` from the standard styles.

    >>> import Data.Text
    >>> dfDe <- standardDateFormatter LongFormatStyle LongFormatStyle (Locale "de_DE") (pack "CET")

patternDateFormatter :: Text -> LocaleName -> Text -> IO DateFormatter Source #

Create a new `DateFormatter` using a custom pattern as described at https://unicode-org.github.io/icu/userguide/format_parse/datetime/#datetime-format-syntax. For examples the pattern "yyyy.MM.dd G `at` HH:mm:ss zzz" produces “1996.07.10 AD at 15:08:56 PDT” in English for the PDT time zone.

A date pattern is a string of characters, where specific strings of characters are replaced with date and time data from a calendar when formatting or used to generate data for a calendar when parsing.

The Date Field Symbol Table contains the characters used in patterns to show the appropriate formats for a given locale, such as yyyy for the year. Characters may be used multiple times. For example, if y is used for the year, "yy" might produce “99”, whereas "yyyy" produces “1999”. For most numerical fields, the number of characters specifies the field width. For example, if h is the hour, "h" might produce “5”, but "hh" produces “05”. For some characters, the count specifies whether an abbreviated or full form should be used, but may have other choices, as given below.

Two single quotes represents a literal single quote, either inside or outside single quotes. Text within single quotes is not interpreted in any way (except for two adjacent single quotes). Otherwise all ASCII letter from a to z and A to Z are reserved as syntax characters, and require quoting if they are to represent literal characters. In addition, certain ASCII punctuation characters may become variable in the future (eg `:` being interpreted as the time separator and `/` as a date separator, and replaced by respective locale-sensitive characters in display).

“Stand-alone” values refer to those designed to stand on their own independently, as opposed to being with other formatted values. “2nd quarter” would use the wide stand-alone format "qqqq", whereas “2nd quarter 2007” would use the regular format "QQQQ yyyy". For more information about format and stand-alone forms, see CLDR Calendar Elements.

The pattern characters used in the Date Field Symbol Table are defined by CLDR; for more information see CLDR Date Field Symbol Table.

👉 Note that the examples may not reflect current CLDR data.

dateSymbols :: DateFormatter -> DateFormatSymbolType -> [Text] Source #

Get relevant date related symbols, e.g. month and weekday names.

    >>> import Data.Text
    >>> dfDe <- standardDateFormatter LongFormatStyle LongFormatStyle (Locale "de_DE") (pack "CET")
    >>> dateSymbols dfDe Months
    ["Januar","Februar","M\228rz","April","Mai","Juni","Juli","August","September","Oktober","November","Dezember"]
    >>> dfAt <- standardDateFormatter LongFormatStyle LongFormatStyle (Locale "de_AT") (pack "CET")
    >>> dateSymbols dfAt Months
    ["J\228nner","Februar","M\228rz","April","Mai","Juni","Juli","August","September","Oktober","November","Dezember"]

formatCalendar :: DateFormatter -> Calendar -> Text Source #

Format a `Calendar` using a `DateFormatter`.

    >>> import Data.Text
    >>> dfDe <- standardDateFormatter LongFormatStyle LongFormatStyle (Locale "de_DE") (pack "CET")
    >>> c <- calendar (pack "CET") (Locale "de_DE") TraditionalCalendarType
    >>> formatCalendar dfDe c
    "13. Oktober 2021 um 12:44:09 GMT+2"