Copyright	(C) 2016 Jason Johnson
License	BSD-style (see the file LICENSE)
Maintainer	Jason Johnson <jason.johnson.081@gmail.com>
Stability	experimental
Portability	POSIX, Windows
Safe Haskell	Safe-Inferred
Language	Haskell2010

Data.HodaTime.Locale

Contents

Locale
Built-in locales
Reading the machine's locale
Inspecting a locale

Description

Provides culture-specific names (month and weekday names, AM/PM designators) and layout strings for dates and times. A Locale can be read from the operating system's locale database — in the same spirit as the time-zone support, the data lives on the machine and is read on demand rather than being bundled — or you can use one of the built-in locales (enUS, deDE, jaJP) when you want a fixed, pure one with no IO.

Locale is abstract: you never construct one yourself, you obtain it from currentLocale, localeByName or a built-in, and then hand it to the culture-aware patterns. Those live in Data.HodaTime.Pattern.Locale (whole-layout patterns — localeDatePattern / localeTimePattern) and in Data.HodaTime.Pattern.CalendarDate / Data.HodaTime.Pattern.LocalTime (individual name fields — pMMMM', pdddd', ppp').

Getting a locale

Expand

Three ways to obtain one — a built-in (pure, no IO), a specific installed locale by name, or the machine's own current locale — each then handed to a culture-aware pattern:

import Data.HodaTime.Locale (deDE, localeByName, currentLocale)
import Data.HodaTime.Pattern (format)
import Data.HodaTime.Pattern.Locale (localeDatePattern)

-- a built-in: pure, formats the German way (15.03.2020)
fromBuiltin = do
  p <- localeDatePattern deDE
  pure (format p someDate)

-- a named locale installed on the machine
fromName = do
  loc <- localeByName "de_DE.UTF-8"
  p   <- localeDatePattern loc
  pure (format p someDate)

-- whatever the machine's LC_TIME is set to
fromCurrent = do
  loc <- currentLocale
  p   <- localeDatePattern loc
  pure (format p someDate)

Synopsis

data Locale
enUS :: Locale
deDE :: Locale
jaJP :: Locale
currentLocale :: IO Locale
localeByName :: String -> IO Locale
newtype LocaleException = LocaleNotFound String
localeId :: Locale -> String
monthNames :: Locale -> [String]
monthNamesShort :: Locale -> [String]
dayNames :: Locale -> [String]
dayNamesShort :: Locale -> [String]
amName :: Locale -> String
pmName :: Locale -> String

Locale

data Locale Source #

The culture-specific names used when formatting and parsing dates and times, as read from the operating system's locale database (see Data.HodaTime.Locale).

The month and weekday name lists describe the Gregorian calendar, which is all the operating system's LC_TIME category knows about. The lists are ordered to line up directly with the calendar enumerations: monthNames is January-first (indexed by fromEnum of the month) and dayNames is Sunday-first (indexed by fromEnum of the DayOfWeek, which also starts at Sunday).

The raw*Format fields hold the operating system's own layout strings as POSIX strftime strings, consumed by localeDatePattern and friends in Data.HodaTime.Pattern.Locale. On POSIX they come straight from D_FMT / T_FMT / D_T_FMT; on Windows they are translated from the Windows picture strings (e.g. dd.MM.yyyy) by windowsPictureToStrftime.

Instances

Instances details

Show Locale Source #
Instance details Defined in Data.HodaTime.Locale.Internal Methods showsPrec :: Int -> Locale -> ShowS # show :: Locale -> String # showList :: [Locale] -> ShowS #
Eq Locale Source #
Instance details Defined in Data.HodaTime.Locale.Internal Methods (==) :: Locale -> Locale -> Bool # (/=) :: Locale -> Locale -> Bool #

Built-in locales

enUS :: Locale Source #

A built-in United States English locale (en_US), offered so patterns can be produced without reading the machine. Mirrors the en_US LC_TIME data: month-first dates and a 12-hour %r time.

deDE :: Locale Source #

A built-in German locale (de_DE): day-first dates, 24-hour time, and \(as on a real @de_DE@\) empty AM/PM designators.

jaJP :: Locale Source #

A built-in Japanese locale (ja_JP): 年/月/日-punctuated numeric dates and 午前/午後 AM/PM designators.

Reading the machine's locale

currentLocale :: IO Locale Source #

Read the process's current locale, as selected by the environment (LC_ALL / LC_TIME / LANG), falling back to the POSIX C locale.

localeByName :: String -> IO Locale Source #

Read a specific locale by name, e.g. "de_DE.UTF-8". Throws LocaleNotFound if it is not installed.

newtype LocaleException Source #

Thrown by localeByName when the requested locale is not installed on the machine.

Constructors

LocaleNotFound String

Instances

Instances details

Exception LocaleException Source #
Instance details Defined in Data.HodaTime.Locale Methods toException :: LocaleException -> SomeException # fromException :: SomeException -> Maybe LocaleException # displayException :: LocaleException -> String #
Show LocaleException Source #
Instance details Defined in Data.HodaTime.Locale Methods showsPrec :: Int -> LocaleException -> ShowS # show :: LocaleException -> String # showList :: [LocaleException] -> ShowS #

Inspecting a locale

localeId :: Locale -> String Source #

The identifier this locale was loaded from (e.g. "de_DE.UTF-8"), or the short code of a built-in.

monthNames :: Locale -> [String] Source #

Full month names, January-first (12 entries for the Gregorian calendar).

monthNamesShort :: Locale -> [String] Source #

Abbreviated month names, January-first.

dayNames :: Locale -> [String] Source #

Full weekday names, Sunday-first (7 entries).

dayNamesShort :: Locale -> [String] Source #

Abbreviated weekday names, Sunday-first.

amName :: Locale -> String Source #

The AM designator (may be empty in 24-hour cultures such as German).

pmName :: Locale -> String Source #

The PM designator (may be empty in 24-hour cultures such as German).