text-icu-0.8.0.3: Bindings to the ICU library
Copyright(c) 2021 Torsten Kemps-Benedix
LicenseBSD-style
Maintainerbos@serpentine.com
Stabilityexperimental
PortabilityGHC
Safe HaskellSafe-Inferred
LanguageHaskell98

Data.Text.ICU.Calendar

Description

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

Synopsis

Data

data Calendar Source #

Instances

Instances details
Show Calendar Source # 
Instance details

Defined in Data.Text.ICU.Calendar

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.

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

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

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

Set the day part of the calendar from a Day.

Lenses

Time zone functions

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

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

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