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

Contents

- Data
- High-level interface
  - Operations on calendars
  - Calendar field getters
  - Calendar field setters
  - Lenses
  - Time zone functions
- Low-level interface

Description

Calendar functions implemented as bindings to the International Components for Unicode (ICU) libraries.

Synopsis

- data Calendar = Calendar {
  - calendarForeignPtr :: ForeignPtr UCalendar
  }
- data CalendarType
  - = TraditionalCalendarType
  - | DefaultCalendarType
  - | GregorianCalendarType
- data SystemTimeZoneType
  - = AnyTimeZone
  - | CanonicalTimeZone
  - | CanonicalLocationTimeZone
- data CalendarField
  - = Era
  - | Year
  - | Month
  - | WeekOfYear
  - | WeekOfMonth
  - | DayOfMonth
  - | DayOfYear
  - | DayOfWeek
  - | DayOfWeekInMonth
  - | AmPm
  - | Hour
  - | HourOfDay
  - | Minute
  - | Second
  - | Millisecond
  - | ZoneOffset
  - | DstOffset
  - | YearWoY
  - | DoWLocal
  - | ExtendedYear
  - | JulianDay
  - | MillisecondsInDay
  - | IsLeapMonth
- type UCalendar = CInt
- roll :: Calendar -> [(CalendarField, Int)] -> Calendar
- add :: Calendar -> [(CalendarField, Int)] -> Calendar
- set1 :: Calendar -> CalendarField -> Int -> Calendar
- set :: Calendar -> [(CalendarField, Int)] -> Calendar
- get :: Calendar -> CalendarField -> Int
- era :: Calendar -> Int
- year :: Calendar -> Int
- month :: Calendar -> Int
- dayOfMonth :: Calendar -> Int
- dayOfYear :: Calendar -> Int
- dayOfWeek :: Calendar -> Int
- dayOfWeekInMonth :: Calendar -> Int
- amPm :: Calendar -> Int
- hour :: Calendar -> Int
- hourOfDay :: Calendar -> Int
- minute :: Calendar -> Int
- second :: Calendar -> Int
- millisecond :: Calendar -> Int
- zoneOffset :: Calendar -> Int
- dstOffset :: Calendar -> Int
- yearWoY :: Calendar -> Int
- doWLocal :: Calendar -> Int
- extendedYear :: Calendar -> Int
- julianDay :: Calendar -> Int
- millisecondsInDay :: Calendar -> Int
- isLeapMonth :: Calendar -> Bool
- day :: Calendar -> Day
- utcTime :: Calendar -> UTCTime
- setEra :: Calendar -> Int -> Calendar
- setYear :: Calendar -> Int -> Calendar
- setMonth :: Calendar -> Int -> Calendar
- setDayOfMonth :: Calendar -> Int -> Calendar
- setDayOfYear :: Calendar -> Int -> Calendar
- setDayOfWeek :: Calendar -> Int -> Calendar
- setDayOfWeekInMonth :: Calendar -> Int -> Calendar
- setAmPm :: Calendar -> Int -> Calendar
- setHour :: Calendar -> Int -> Calendar
- setHourOfDay :: Calendar -> Int -> Calendar
- setMinute :: Calendar -> Int -> Calendar
- setSecond :: Calendar -> Int -> Calendar
- setMillisecond :: Calendar -> Int -> Calendar
- setZoneOffset :: Calendar -> Int -> Calendar
- setDstOffset :: Calendar -> Int -> Calendar
- setYearWoY :: Calendar -> Int -> Calendar
- setDoWLocal :: Calendar -> Int -> Calendar
- setExtendedYear :: Calendar -> Int -> Calendar
- setJulianDay :: Calendar -> Int -> Calendar
- setMillisecondsInDay :: Calendar -> Int -> Calendar
- setDay :: Calendar -> Day -> Calendar
- _era :: Lens' Calendar Int
- _year :: Lens' Calendar Int
- _month :: Lens' Calendar Int
- _dayOfMonth :: Lens' Calendar Int
- _dayOfYear :: Lens' Calendar Int
- _dayOfWeek :: Lens' Calendar Int
- _dayOfWeekInMonth :: Lens' Calendar Int
- _amPm :: Lens' Calendar Int
- _hour :: Lens' Calendar Int
- _hourOfDay :: Lens' Calendar Int
- _minute :: Lens' Calendar Int
- _second :: Lens' Calendar Int
- _millisecond :: Lens' Calendar Int
- _zoneOffset :: Lens' Calendar Int
- _dstOffset :: Lens' Calendar Int
- _day :: Lens' Calendar Day
- timeZoneIDs :: SystemTimeZoneType -> IO [Text]
- timeZones :: IO [Text]
- calendar :: Text -> LocaleName -> CalendarType -> IO Calendar
- openTimeZoneIDEnumeration :: SystemTimeZoneType -> IO Enumerator
- openTimeZones :: IO Enumerator
- getField :: Calendar -> CalendarField -> IO Int
- setField :: Calendar -> CalendarField -> Int -> IO ()
- setDate :: Calendar -> Int -> Int -> Int -> IO ()
- setDateTime :: Calendar -> Int -> Int -> Int -> Int -> Int -> Int -> IO ()
- rollField :: Calendar -> CalendarField -> Int -> IO ()
- addField :: Calendar -> CalendarField -> Int -> IO ()
- setTimeZone :: Calendar -> Text -> IO ()

# Data

data Calendar Source #

Constructors

Calendar |

Fields

- calendarForeignPtr :: ForeignPtr UCalendar

#### Instances

Instances details

Show Calendar Source # |
Instance details Defined in Data.Text.ICU.Calendar Methods showsPrec :: Int -> Calendar -> ShowS Source # show :: Calendar -> String Source # showList :: [Calendar] -> ShowS Source #

data CalendarType Source #

Constructors

TraditionalCalendarType |
DefaultCalendarType |
GregorianCalendarType |

#### Instances

Instances details

Read CalendarType Source # |
Instance details Defined in Data.Text.ICU.Calendar Methods readsPrec :: Int -> ReadS CalendarType Source # readList :: ReadS [CalendarType] Source # readPrec :: ReadPrec CalendarType Source # readListPrec :: ReadPrec [CalendarType] Source #
Show CalendarType Source # |
Instance details Defined in Data.Text.ICU.Calendar Methods showsPrec :: Int -> CalendarType -> ShowS Source # show :: CalendarType -> String Source # showList :: [CalendarType] -> ShowS Source #
Eq CalendarType Source # |
Instance details Defined in Data.Text.ICU.Calendar Methods (==) :: CalendarType -> CalendarType -> Bool Source # (/=) :: CalendarType -> CalendarType -> Bool Source #

data SystemTimeZoneType Source #

Constructors

AnyTimeZone |
CanonicalTimeZone |
CanonicalLocationTimeZone |

#### Instances

Instances details

Read SystemTimeZoneType Source # |
Instance details Defined in Data.Text.ICU.Calendar Methods readsPrec :: Int -> ReadS SystemTimeZoneType Source # readList :: ReadS [SystemTimeZoneType] Source # readPrec :: ReadPrec SystemTimeZoneType Source # readListPrec :: ReadPrec [SystemTimeZoneType] Source #
Show SystemTimeZoneType Source # |
Instance details Defined in Data.Text.ICU.Calendar Methods showsPrec :: Int -> SystemTimeZoneType -> ShowS Source # show :: SystemTimeZoneType -> String Source # showList :: [SystemTimeZoneType] -> ShowS Source #
Eq SystemTimeZoneType Source # |
Instance details Defined in Data.Text.ICU.Calendar Methods (==) :: SystemTimeZoneType -> SystemTimeZoneType -> Bool Source # (/=) :: SystemTimeZoneType -> SystemTimeZoneType -> Bool Source #

data CalendarField Source #

All the fields that comprise a `Calendar`.

Constructors

Era | Field indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar. This is a calendar-specific value.
Year | Field indicating the year. This is a calendar-specific value.
Month | Field indicating the month. This is a calendar-specific value. The first month of the year is JANUARY; the last depends on the number of months in a year. Note: Calendar month is 0-based.
WeekOfYear | Field indicating the week number within the current year. The first week of the year, as defined by UCAL_FIRST_DAY_OF_WEEK and UCAL_MINIMAL_DAYS_IN_FIRST_WEEK attributes, has value 1. Subclasses define the value of UCAL_WEEK_OF_YEAR for days before the first week of the year.
WeekOfMonth | Field indicating the week number within the current month. The first week of the month, as defined by UCAL_FIRST_DAY_OF_WEEK and UCAL_MINIMAL_DAYS_IN_FIRST_WEEK attributes, has value 1. Subclasses define the value of WEEK_OF_MONTH for days before the first week of the month.
DayOfMonth | Field indicating the day of the month. This is a synonym for DAY_OF_MONTH. The first day of the month has value 1.
DayOfYear | Field indicating the day number within the current year. The first day of the year has value 1.
DayOfWeek | Field indicating the day of the week. This field takes values SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, and SATURDAY. Note: Calendar day-of-week is 1-based. Clients who create locale resources for the field of first-day-of-week should be aware of this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY.

DayOfWeekInMonth

Field indicating the ordinal number of the day of the week within the current month. Together with the DAY_OF_WEEK field, this uniquely specifies a day within a month. Unlike WEEK_OF_MONTH and WEEK_OF_YEAR, this field's value does not depend on getFirstDayOfWeek() or getMinimalDaysInFirstWeek(). DAY_OF_MONTH 1 through 7 always correspond to DAY_OF_WEEK_IN_MONTH 1; 8 through 15 correspond to DAY_OF_WEEK_IN_MONTH 2, and so on. DAY_OF_WEEK_IN_MONTH 0 indicates the week before DAY_OF_WEEK_IN_MONTH 1. Negative values count back from the end of the month, so the last Sunday of a month is specified as DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1. Because negative values count backward they will usually be aligned differently within the month than positive values. For example, if a month has 31 days, DAY_OF_WEEK_IN_MONTH -1 will overlap DAY_OF_WEEK_IN_MONTH 5 and the end of 4.

AmPm | Field indicating whether the HOUR is before or after noon. E.g., at 10:04:15.250 PM the AM_PM is PM.
Hour | Field indicating the hour of the morning or afternoon. HOUR is used for the 12-hour clock. E.g., at 10:04:15.250 PM the HOUR is 10.
HourOfDay | Field indicating the hour of the day. HOUR_OF_DAY is used for the 24-hour clock. E.g., at 10:04:15.250 PM the HOUR_OF_DAY is 22.
Minute | Field indicating the minute within the hour. E.g., at 10:04:15.250 PM the UCAL_MINUTE is 4.
Second | Field indicating the second within the minute. E.g., at 10:04:15.250 PM the UCAL_SECOND is 15.
Millisecond | Field indicating the millisecond within the second. E.g., at 10:04:15.250 PM the UCAL_MILLISECOND is 250.
ZoneOffset | Field indicating the raw offset from GMT in milliseconds.
DstOffset | Field indicating the daylight savings offset in milliseconds.
YearWoY | Field indicating the extended year corresponding to the UCAL_WEEK_OF_YEAR field. This may be one greater or less than the value of UCAL_EXTENDED_YEAR.
DoWLocal | Field indicating the localized day of week. This will be a value from 1 to 7 inclusive, with 1 being the localized first day of the week.
ExtendedYear | Year of this calendar system, encompassing all supra-year fields. For example, in Gregorian/Julian calendars, positive Extended Year values indicate years AD, 1 BC = 0 extended, 2 BC = -1 extended, and so on.
JulianDay | Field indicating the modified Julian day number. This is different from the conventional Julian day number in two regards. First, it demarcates days at local zone midnight, rather than noon GMT. Second, it is a local number; that is, it depends on the local time zone. It can be thought of as a single number that encompasses all the date-related fields.

MillisecondsInDay

Ranges from 0 to 23:59:59.999 (regardless of DST). This field behaves exactly like a composite of all time-related fields, not including the zone fields. As such, it also reflects discontinuities of those fields on DST transition days. On a day of DST onset, it will jump forward. On a day of DST cessation, it will jump backward. This reflects the fact that it must be combined with the DST_OFFSET field to obtain a unique local time value.

IsLeapMonth | Whether or not the current month is a leap month (0 or 1). See the Chinese calendar for an example of this.

#### Instances

Instances details

Read CalendarField Source # |
Instance details Defined in Data.Text.ICU.Calendar Methods readsPrec :: Int -> ReadS CalendarField Source # readList :: ReadS [CalendarField] Source # readPrec :: ReadPrec CalendarField Source # readListPrec :: ReadPrec [CalendarField] Source #
Show CalendarField Source # |
Instance details Defined in Data.Text.ICU.Calendar Methods showsPrec :: Int -> CalendarField -> ShowS Source # show :: CalendarField -> String Source # showList :: [CalendarField] -> ShowS Source #
Eq CalendarField Source # |
Instance details Defined in Data.Text.ICU.Calendar Methods (==) :: CalendarField -> CalendarField -> Bool Source # (/=) :: CalendarField -> CalendarField -> Bool Source #

type UCalendar = CInt Source #

# High-level interface

## Operations on calendars

roll Source #

Arguments

:: Calendar |
-> [(CalendarField, Int)] | The field and the signed amount to add to this field. If the amount causes the value to exceed to maximum or minimum values for that field, the field is pinned to a permissible value.
-> Calendar |

Add a specified signed amount to a particular field in a Calendar.

See `rollField` for further details.

    >>> import qualified Data.Text as T
    >>> c1 <- calendar (T.pack "CET") (Locale "de_DE") TraditionalCalendarType
    >>> show c1
    2021-10-12 17:53:26
    >>> let c2 = roll c1 [(Hour, 2)]
    >>> show c2
    2021-10-12 19:53:26
    >>> let c3 = roll c1 [(Hour, 12)]
    >>> show c3
    2021-10-12 17:53:26
    >>> let c4 = add c1 [(Hour, 12)]
    >>> show c4
    2021-10-13 5:53:26

add Source #

Arguments

:: Calendar | The `Calendar` to which to add.
-> [(CalendarField, Int)] | Field type and the signed amount to add to field. If the amount causes the value to exceed to maximum or minimum values for that field, other fields are modified to preserve the magnitude of the change.
-> Calendar |

Add a specified signed amount to a particular field in a Calendar.

See `addField` for further details and see `rollField` for examples and differences compared to rolling.

set1 :: Calendar -> CalendarField -> Int -> Calendar Source #

Set the value of one field of a calendar to a certain value. All fields are represented as 32-bit integers.

set :: Calendar -> [(CalendarField, Int)] -> Calendar Source #

Set the value of a list of fields of a calendar to certain values. All fields are represented as 32-bit integers.

get :: Calendar -> CalendarField -> Int Source #

Get the value of a specific field in the calendar.

## Calendar field getters

era :: Calendar -> Int Source #

Return the era of the calendar. The values are calendar specific and are usually 0 (some ancient era) and 1 (current era).

    >>> import qualified Data.Text as T
    >>> c1 <- calendar (T.pack "CET") (Locale "de_DE") TraditionalCalendarType
    >>> era c1
    1

year :: Calendar -> Int Source #

Return the year of the calendar. The values are calendar specific.

    >>> import qualified Data.Text as T
    >>> c1 <- calendar (T.pack "CET") (Locale "de_DE") TraditionalCalendarType
    >>> year c1
    2021

month :: Calendar -> Int Source #

Return the month of the calendar. The values are calendar specific and 0-based.

    >>> import qualified Data.Text as T
    >>> c1 <- calendar (T.pack "CET") (Locale "de_DE") TraditionalCalendarType
    >>> month c1
    9
    >>> day c1
    2021-10-12

dayOfMonth :: Calendar -> Int Source #

dayOfYear :: Calendar -> Int Source #

dayOfWeek :: Calendar -> Int Source #

dayOfWeekInMonth :: Calendar -> Int Source #

amPm :: Calendar -> Int Source #

hour :: Calendar -> Int Source #

hourOfDay :: Calendar -> Int Source #

minute :: Calendar -> Int Source #

second :: Calendar -> Int Source #

millisecond :: Calendar -> Int Source #

zoneOffset :: Calendar -> Int Source #

dstOffset :: Calendar -> Int Source #

yearWoY :: Calendar -> Int Source #

doWLocal :: Calendar -> Int Source #

extendedYear :: Calendar -> Int Source #

julianDay :: Calendar -> Int Source #

millisecondsInDay :: Calendar -> Int Source #

isLeapMonth :: Calendar -> Bool Source #

day :: Calendar -> Day Source #

Convert the day part of the calendar to a `Day`.

    >>> import qualified Data.Text as T
    >>> c1 <- calendar (T.pack "CET") (Locale "de_DE") TraditionalCalendarType
    >>> show c1
    2021-10-12 18:00:50
    >>> day c1
    2021-10-12

utcTime :: Calendar -> UTCTime Source #

Convert the day and time part of the calendar to a `UTCTime`.

    >>> import qualified Data.Text as T
    >>> c1 <- calendar (T.pack "CET") (Locale "de_DE") TraditionalCalendarType
    >>> show c1
    2021-10-12 18:00:50
    >>> utcTime c1
    2021-10-12 16:00:50.544999999998 UTC

## Calendar field setters

setEra :: Calendar -> Int -> Calendar Source #

setYear :: Calendar -> Int -> Calendar Source #

setMonth :: Calendar -> Int -> Calendar Source #

setDayOfMonth :: Calendar -> Int -> Calendar Source #

setDayOfYear :: Calendar -> Int -> Calendar Source #

setDayOfWeek :: Calendar -> Int -> Calendar Source #

setDayOfWeekInMonth :: Calendar -> Int -> Calendar Source #

setAmPm :: Calendar -> Int -> Calendar Source #

setHour :: Calendar -> Int -> Calendar Source #

setHourOfDay :: Calendar -> Int -> Calendar Source #

setMinute :: Calendar -> Int -> Calendar Source #

setSecond :: Calendar -> Int -> Calendar Source #

setMillisecond :: Calendar -> Int -> Calendar Source #

setZoneOffset :: Calendar -> Int -> Calendar Source #

setDstOffset :: Calendar -> Int -> Calendar Source #

setYearWoY :: Calendar -> Int -> Calendar Source #

setDoWLocal :: Calendar -> Int -> Calendar Source #

setExtendedYear :: Calendar -> Int -> Calendar Source #

setJulianDay :: Calendar -> Int -> Calendar Source #

setMillisecondsInDay :: Calendar -> Int -> Calendar Source #

setDay :: Calendar -> Day -> Calendar Source #

Set the day part of the calendar from a `Day`.

## Lenses

_era :: Lens' Calendar Int Source #

_year :: Lens' Calendar Int Source #

_month :: Lens' Calendar Int Source #

_dayOfMonth :: Lens' Calendar Int Source #

_dayOfYear :: Lens' Calendar Int Source #

_dayOfWeek :: Lens' Calendar Int Source #

_dayOfWeekInMonth :: Lens' Calendar Int Source #

_amPm :: Lens' Calendar Int Source #

_hour :: Lens' Calendar Int Source #

_hourOfDay :: Lens' Calendar Int Source #

_minute :: Lens' Calendar Int Source #

_second :: Lens' Calendar Int Source #

_millisecond :: Lens' Calendar Int Source #

_zoneOffset :: Lens' Calendar Int Source #

_dstOffset :: Lens' Calendar Int Source #

_day :: Lens' Calendar Day Source #

## Time zone functions

timeZoneIDs :: SystemTimeZoneType -> IO [Text] Source #

timeZones :: IO [Text] Source #

List of all time zones.

# Low-level interface

calendar :: Text -> LocaleName -> CalendarType -> IO Calendar Source #

Open a Calendar.

A Calendar may be used to convert a millisecond value to a year, month, and day.

Note: When unknown TimeZone ID is specified or if the TimeZone ID specified is "Etc/Unknown", the Calendar returned by the function is initialized with GMT zone with TimeZone ID UCAL_UNKNOWN_ZONE_ID ("EtcUnknown") without any errorswarnings. If you want to check if a TimeZone ID is valid prior to this function, use ucal_getCanonicalTimeZoneID.

    >>> import qualified Data.Text as T
    >>> c <- calendar (T.pack "CET") (Locale "de_DE") TraditionalCalendarType
    >>> show c
    2021-10-12 17:37:43

openTimeZoneIDEnumeration :: SystemTimeZoneType -> IO Enumerator Source #

openTimeZones :: IO Enumerator Source #

Create an enumeration over all time zones.

getField :: Calendar -> CalendarField -> IO Int Source #

Get the value of a specific calendar field.

    >>> import qualified Data.Text as T
    >>> c <- calendar (T.pack "CET") (Locale "de_DE") TraditionalCalendarType
    >>> getField c Year
    2021

setField :: Calendar -> CalendarField -> Int -> IO () Source #

setDate :: Calendar -> Int -> Int -> Int -> IO () Source #

setDateTime :: Calendar -> Int -> Int -> Int -> Int -> Int -> Int -> IO () Source #

rollField :: Calendar -> CalendarField -> Int -> IO () Source #

Add a specified signed amount to a particular field in a Calendar.

This will not modify more significant fields in the calendar. Rolling by a positive value always means moving forward in time (unless the limit of the field is reached, in which case it may pin or wrap), so for Gregorian calendar, starting with 100 BC and rolling the year by +1 results in 99 BC. When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around. When eras only have a limit at one end, then attempting to roll the year past that limit will result in pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for era 0 (that is the only way to represent years before the calendar epoch).

addField :: Calendar -> CalendarField -> Int -> IO () Source #

Add a specified signed amount to a particular field in a Calendar.

This can modify more significant fields in the calendar. Adding a positive value always means moving forward in time, so for the Gregorian calendar, starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces the numeric value of the field itself).

setTimeZone :: Calendar -> Text -> IO () Source #