class ICU::DateTimeFormatter

Overview

DateTime Formatter

This class provides a facility for formatting and parsing dates and times according to locale-specific conventions or custom patterns.

It wraps the ICU UDateFormat functionality.

Usage

# Using styles
dtf = ICU::DateTimeFormatter.new("en_US", date_style: ICU::DateTimeFormatter::FormatStyle::Short, time_style: ICU::DateTimeFormatter::FormatStyle::Short)
time = Time.utc(2023, 10, 27, 15, 30, 45)
dtf.format(time)                             # => "10/27/23, 3:30 PM" (example, actual output depends on ICU data)
parsed_time = dtf.parse("10/27/23, 3:30 PM") # => Time object

# Using a pattern
dtf_pattern = ICU::DateTimeFormatter.new("fr_FR", pattern: "yyyy.MM.dd 'at' HH:mm:ss zzz")
dtf_pattern.format(time) # => "2023.10.27 at 15:30:45 UTC" (example)

See also

Defined in:

icu/datetime_formatter.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new(locale : String, *, date_style : FormatStyle, time_style : FormatStyle, timezone : String | Nil = nil) #

Creates a new DateTimeFormatter using predefined styles.

dtf = ICU::DateTimeFormatter.new("en_US", date_style: ICU::DateTimeFormatter::FormatStyle::Short, time_style: ICU::DateTimeFormatter::FormatStyle::Short)
dtf_fr = ICU::DateTimeFormatter.new("fr_FR", date_style: ICU::DateTimeFormatter::FormatStyle::Long, time_style: ICU::DateTimeFormatter::FormatStyle::Long, timezone: "Europe/Paris")
dtf_date_only = ICU::DateTimeFormatter.new("de_DE", date_style: ICU::DateTimeFormatter::FormatStyle::Medium, time_style: ICU::DateTimeFormatter::FormatStyle::None)

[View source]
def self.new(locale : String, *, pattern : String, timezone : String | Nil = nil) #

Creates a new DateTimeFormatter using a custom pattern.

The pattern syntax follows the LDML specification.

dtf = ICU::DateTimeFormatter.new("en_GB", pattern: "dd MMM yyyy HH:mm:ss ZZZZ")
dtf_tz = ICU::DateTimeFormatter.new("ja_JP", pattern: "GGGGy年M月d日 H時m分s秒 zzzz", timezone: "Asia/Tokyo")

See also


[View source]

Instance Method Detail

def calendar=(calendar : ICU::Calendar) : Nil #

Sets the calendar to be used by this formatter.

dtf = ICU::DateTimeFormatter.new("en_US")
gregorian_cal = ICU::Calendar.new("en_US@calendar=gregorian")
dtf.calendar = gregorian_cal

[View source]
def finalize #

[View source]
def format(datetime : Time) : String #

Formats a Time object into a string according to the formatter's locale and pattern/style.

dtf = ICU::DateTimeFormatter.new("en_US", date_style: ICU::DateTimeFormatter::FormatStyle::Medium, time_style: ICU::DateTimeFormatter::FormatStyle::Short)
time = Time.utc(2023, 10, 27, 15, 30, 0)
dtf.format(time) # => "Oct 27, 2023, 3:30 PM" (example)

[View source]
def format(calendar : ICU::Calendar) : String #

Formats the date/time represented by an ICU::Calendar object into a string.

Note: This method might modify the calendar object if its fields are not fully calculated, but it won't change the logical date and time held by the calendar.

cal = ICU::Calendar.new("en_US")
cal.set(2023, 9, 27, 15, 30, 45) # Month is 0-based (9 = October)
dtf = ICU::DateTimeFormatter.new("en_US", pattern: "yyyy-MM-dd HH:mm:ss")
dtf.format(cal) # => "2023-10-27 15:30:45" (example)

[View source]
def lenient=(is_lenient : Bool) : Nil #

Sets whether the formatter should use lenient parsing.

dtf = ICU::DateTimeFormatter.new("en_US", pattern: "yy/MM/dd")
dtf.lenient = true
dtf.parse("23/04/05") # Likely succeeds
dtf.lenient = false
# dtf.parse("2023/04/05") # Would likely fail if lenient is false

[View source]
def lenient? : Bool #

Checks if the formatter uses lenient parsing.

Lenient parsing allows the parser to use heuristics to interpret inputs that don't precisely match the pattern. Strict parsing requires exact matches.

dtf = ICU::DateTimeFormatter.new("en_US", pattern: "yyyy-MM-dd")
dtf.lenient? # => true (usually the default)
dtf.lenient = false
dtf.lenient? # => false

[View source]
def parse(text : String, calendar : ICU::Calendar) : Nil #

Parses a string and sets the fields of the provided ICU::Calendar object.

The calendar's date/time will be updated based on the parsed string. Raises ICU::Error if parsing fails or if the entire string is not parsed (in strict mode).

cal = ICU::Calendar.new("en_US")
dtf = ICU::DateTimeFormatter.new("en_US", pattern: "yyyy-MM-dd")
dtf.parse("2024-01-15", cal)
puts cal.get(ICU::Calendar::DateField::Year)  # => 2024
puts cal.get(ICU::Calendar::DateField::Month) # => 0 (January)

[View source]
def parse(text : String) : Time #

Parses a string into a Time object according to the formatter's locale and pattern/style.

Raises ICU::Error if parsing fails or if the entire string is not parsed (in strict mode).

dtf = ICU::DateTimeFormatter.new("en_US", date_style: ICU::DateTimeFormatter::FormatStyle::Short, time_style: ICU::DateTimeFormatter::FormatStyle::Short)
parsed_time = dtf.parse("10/27/23, 3:30 PM")
puts parsed_time.year # => 2023

[View source]
def pattern(localized : Bool = false) : String #

Returns the pattern string used by this formatter.

If localized is true, the pattern should be localized.

dtf = ICU::DateTimeFormatter.new("en_US", date_style: ICU::DateTimeFormatter::FormatStyle::Short, time_style: ICU::DateTimeFormatter::FormatStyle::Short)
dtf.pattern # => "M/d/yy, h:mm a" (example)

[View source]
def pattern=(pattern : String) : Nil #

Configures a new pattern for the formatter (not localized)

dtf = ICU::DateTimeFormatter.new("en_US", date_style: ICU::DateTimeFormatter::FormatStyle::Short, time_style: ICU::DateTimeFormatter::FormatStyle::Short)
dtf.pattern = "EEEE, MMMM d, yyyy 'at' h:mm:ss a zzzz"
puts dtf.pattern # => "EEEE, MMMM d, yyyy 'at' h:mm:ss a zzzz"

[View source]
def set_pattern(pattern : String, localized : Bool = false) : Nil #

Configures a new pattern for the formatter.

If localized is true, the pattern is interpreted as potentially containing localized characters (e.g., localized month or day names). Applying an invalid pattern might cause subsequent format/parse calls to fail.

dtf = ICU::DateTimeFormatter.new("en_US", date_style: ICU::DateTimeFormatter::FormatStyle::Short, time_style: ICU::DateTimeFormatter::FormatStyle::Short)
dtf.set_pattern("EEEE, MMMM d, yyyy 'at' h:mm:ss a zzzz", true)
puts dtf.pattern # => "EEEE, MMMM d, yyyy 'at' h:mm:ss a zzzz"

[View source]