class ICU::Calendar

Overview

Calendar

This class provides an interface to ICU's calendar functions, allowing for date and time calculations based on specific locales, time zones, and calendar systems (e.g., Gregorian, Buddhist).

Usage

# Create a Gregorian calendar for New York in English
calendar = ICU::Calendar.new("America/New_York", "en_US")

# Set the date to April 29, 2025
calendar.set(ICU::Calendar::DateField::Year, 2025)
calendar.set(ICU::Calendar::DateField::Month, 3) # Month is 0-indexed (April)
calendar.set(ICU::Calendar::DateField::DayOfMonth, 29)

# Get the day of the week
day_of_week = calendar.get(ICU::Calendar::DateField::DayOfWeek) # Sunday = 1, ..., Saturday = 7

# Add 5 days
calendar.add(ICU::Calendar::DateField::DayOfMonth, 5)
puts calendar.get(ICU::Calendar::DateField::DayOfMonth) # => 4 (May 4th)

# Get current time
now = ICU::Calendar.now # => Returns a Time object
calendar.set(now)

# Check if currently in DST
puts calendar.in_daylight_time?

See also

Defined in:

icu/calendar.cr

Constant Summary

DEFAULT_LOCALE = ""

Constructors

Instance Method Summary

Constructor Detail

def self.new(zone_id : String | Nil = nil, locale : String = DEFAULT_LOCALE, type : Type = Type::Default) #

Creates a new Calendar instance.

  • zone_id: The time zone ID (e.g., "America/New_York", "UTC").
  • locale: The locale ID (e.g., "en_US", "fr_FR").
  • type: The type of calendar to open (e.g., UCalendarType::Gregorian).

[View source]
def self.new(timezone : Time::Location, locale : String = DEFAULT_LOCALE, type : Type = Type::Default) #

Creates a new Calendar instance.

  • timezone: The time zone (e.g., Time::Location.load("Europe/Berlin")).
  • locale: The locale ID (e.g., "en_US", "fr_FR").
  • type: The type of calendar to open (e.g., UCalendarType::Gregorian).

[View source]
def self.new(time : Time, locale : String = DEFAULT_LOCALE, type : Type = Type::Default) #

Creates a new Calendar instance based on a Crystal Time object. The calendar's time zone is derived from the Time object's location.

  • time: The Crystal Time object to initialize the calendar with.
  • locale: The locale ID (e.g., "en_US"). Defaults to the system default ("").
  • type: The type of calendar (e.g., UCalendarType::Gregorian). Defaults to the locale's default (UCalendarType::Default).

[View source]

Instance Method Detail

def add(field : DateField, amount : Int32) : Nil #

Adds a signed amount to a specific calendar field, adjusting larger fields as necessary (e.g., adding 1 day to January 31st results in February 1st).

  • field: The DateField to modify.
  • amount: The signed amount to add to the field.

[View source]
def after?(target_time : Time) : Bool #

Checks if this calendar's current time is strictly after the target time, comparing with a granularity of seconds. Differences at the millisecond or nanosecond level are ignored. Uses ucal_get_field_difference internally by comparing fields from largest down to seconds.

  • target_time: The Time object to compare against.
  • Returns true if this calendar's time is strictly after target_time (at second granularity or larger fields), false otherwise.

[View source]
def before?(target_time : Time) : Bool #

Checks if this calendar's current time is strictly before the target time, comparing with a granularity of seconds. Differences at the millisecond or nanosecond level are ignored. Uses ucal_get_field_difference internally by comparing fields from largest down to seconds.

  • target_time: The Time object to compare against.
  • Returns true if this calendar's time is strictly before target_time (at second granularity or larger fields), false otherwise.

[View source]
def equivalent?(other : self) : Bool #

Checks if this calendar's configuration is equivalent to another calendar. It means they have the same configuration, including time zone, locale, calendar type, etc. The current date and time set on the calendars are not considered for equivalence by this method.

  • other: The other ICU::Calendar instance to compare with.
  • Returns true if the calendars are equivalent in configuration, false otherwise.

[View source]
def finalize #

[View source]
def get(field : DateField) : Int32 #

Gets the value for a specific calendar field.


[View source]
def get_millis : Int64 #

Gets the calendar's time as milliseconds since the epoch.

  • Returns the time in milliseconds since 1970-01-01 00:00:00 UTC as Int64.

[View source]
def get_time : Time #

Gets the calendar's time as a Crystal Time object


[View source]
def get_time_zone_id : String #

Gets the time zone ID associated with this calendar.

  • Returns the time zone ID (e.g., "America/New_York", "UTC") as a String.

[View source]
def in_daylight_time? : Bool #

Checks if the calendar's current date and time fall within daylight saving time for its associated time zone.


[View source]
def roll(field : DateField, amount : Int32) : Nil #

Rolls (increments or decrements) a specific calendar field by a signed amount without changing larger fields. For example, rolling the DayOfMonth field up from 31 might result in 1, without changing the Month.

  • field: The DateField to roll.
  • amount: The signed amount to roll the field by.

[View source]
def set(year : Int32, month : Int32, day : Int32, hour : Int32 = 0, minute : Int32 = 0, second : Int32 = 0) #

[View source]
def set(field : DateField, value : Int32) : Nil #

Sets the value for a specific calendar field.

Raises ValueError if the value is outside the valid range for the field.


[View source]
def set(date_time : Time) : Nil #

Sets the calendar's date and time based on a Crystal Time object.

Important: the time zone of the Time object is copied too


[View source]
def set_millis(ms_since_epoch : Int64) : Nil #

Sets the calendar's time from milliseconds since the epoch (equivalent to ICU's UDate).

  • epoch_ms: The time in milliseconds since 1970-01-01 00:00:00 UTC.

[View source]
def set_time_zone(zone_id : String) : Nil #

Sets the time zone associated with this calendar.

  • zone_id: The time zone ID string (e.g., "America/New_York", "UTC").

[View source]
def to_unsafe #

[View source]
def weekend?(year : Int32, month : Int32, day : Int32) : Bool #

Checks if the calendar's current date and time fall within a weekend for its associated locale.


[View source]
def weekend?(date : Time) : Bool #

Checks if the calendar's current date and time fall within a weekend for its associated locale.


[View source]
def weekend? : Bool #

Checks if the calendar's current date and time fall within a weekend for its associated locale.


[View source]