Class: ICU4X::DateTimeFormat

Inherits:
Object
  • Object
show all
Defined in:
lib/icu4x/yard_docs.rb

Overview

Formats dates and times according to locale-specific conventions.

DateTimeFormat supports various date and time styles and calendar systems. You can use either style options (date_style, time_style) or component options (year, month, day, weekday, hour, minute, second), but not both.

Examples:

Format a date with style

formatter = ICU4X::DateTimeFormat.new(locale, date_style: :long)
formatter.format(Time.now)  #=> "January 1, 2026"

Format date and time with styles

formatter = ICU4X::DateTimeFormat.new(locale, date_style: :short, time_style: :short)
formatter.format(Time.now)  #=> "1/1/26, 12:00 PM"

Format with component options

formatter = ICU4X::DateTimeFormat.new(locale, year: :numeric, month: :numeric, day: :numeric)
formatter.format(Time.now)  #=> "Dec 28, 2025"

Use Japanese calendar

formatter = ICU4X::DateTimeFormat.new(locale, date_style: :long, calendar: :japanese)
formatter.format(Time.now)  #=> "令和8年1月1日"

Han decimal numerals via locale extension

locale = ICU4X::Locale.parse("ja-JP-u-nu-hanidec")
formatter = ICU4X::DateTimeFormat.new(locale, provider: provider, date_style: :long)
formatter.format(Time.utc(2025, 12, 28))  #=> "二〇二五年一二月二八日"

Instance Method Summary collapse

Constructor Details

#initialize(locale, provider: nil, date_style: nil, time_style: nil, year: nil, month: nil, day: nil, weekday: nil, hour: nil, minute: nil, second: nil, time_zone: nil, calendar: :gregory, hour_cycle: nil, hour12: nil) ⇒ DateTimeFormat

Creates a new DateTimeFormat instance.

You must specify either style options (date_style/time_style) or component options (year, month, day, weekday, hour, minute, second). These are mutually exclusive.

Examples:

With style options

formatter = ICU4X::DateTimeFormat.new(locale, date_style: :long, time_style: :short)

With component options

formatter = ICU4X::DateTimeFormat.new(locale, year: :numeric, month: :long, day: :numeric)

With 24-hour format using hour_cycle

formatter = ICU4X::DateTimeFormat.new(locale, time_style: :short, hour_cycle: :h23)
formatter.format(Time.utc(2025, 1, 1, 0, 30))  #=> "00:30:00"

With 12-hour format using hour12

formatter = ICU4X::DateTimeFormat.new(locale, time_style: :short, hour12: true)
formatter.format(Time.utc(2025, 1, 1, 14, 30))  #=> "2:30:00 PM"

Parameters:

  • locale (Locale) —

    the locale for formatting

  • provider (DataProvider, nil) (defaults to: nil) —

    data provider (uses default if nil)

  • date_style (Symbol, nil) (defaults to: nil) —

    date format style: ‘:full`, `:long`, `:medium`, or `:short`

  • time_style (Symbol, nil) (defaults to: nil) —

    time format style: ‘:full`, `:long`, `:medium`, or `:short`

  • year (Symbol, nil) (defaults to: nil) —

    year component: ‘:numeric` or `:two_digit`

  • month (Symbol, nil) (defaults to: nil) —

    month component: ‘:numeric`, `:two_digit`, `:long`, `:short`, or `:narrow`

  • day (Symbol, nil) (defaults to: nil) —

    day component: ‘:numeric` or `:two_digit`

  • weekday (Symbol, nil) (defaults to: nil) —

    weekday component: ‘:long`, `:short`, or `:narrow`

  • hour (Symbol, nil) (defaults to: nil) —

    hour component: ‘:numeric` or `:two_digit`

  • minute (Symbol, nil) (defaults to: nil) —

    minute component: ‘:numeric` or `:two_digit`

  • second (Symbol, nil) (defaults to: nil) —

    second component: ‘:numeric` or `:two_digit`

  • time_zone (String, nil) (defaults to: nil) —

    IANA time zone identifier (e.g., “America/New_York”)

  • calendar (Symbol) (defaults to: :gregory) —

    calendar system to use

  • hour_cycle (Symbol, nil) (defaults to: nil) —

    hour cycle: ‘:h11` (0-11), `:h12` (1-12), or `:h23` (0-23)

  • hour12 (Boolean, nil) (defaults to: nil) —

    ‘true` for 12-hour format, `false` for 24-hour format

Raises:

  • (ArgumentError) —

    if both style and component options are specified

  • (DataError) —

    if data for the locale is unavailable



587
588
589
590
 
# File 'lib/icu4x/yard_docs.rb', line 587

def initialize(locale, provider: nil, date_style: nil, time_style: nil,
year: nil, month: nil, day: nil, weekday: nil,
hour: nil, minute: nil, second: nil,
time_zone: nil, calendar: :gregory, hour_cycle: nil, hour12: nil); end

Instance Method Details

#format(time) ⇒ String

Formats a time value according to the configured options.

Parameters:

  • time (Time, #to_time) —

    the time to format (or any object responding to #to_time)

Returns:

  • (String) —

    the formatted date/time string



597
 
# File 'lib/icu4x/yard_docs.rb', line 597

def format(time); end

#format_to_parts(time) ⇒ Array<FormattedPart>

Formats a time value and returns an array of parts.

Each part contains a type and value, allowing for custom styling or processing of individual components.

Examples:

parts = formatter.format_to_parts(Time.utc(2025, 1, 31))
# => [
#   #<ICU4X::FormattedPart type=:month value="January">,
#   #<ICU4X::FormattedPart type=:literal value=" ">,
#   #<ICU4X::FormattedPart type=:day value="31">,
#   #<ICU4X::FormattedPart type=:literal value=", ">,
#   #<ICU4X::FormattedPart type=:year value="2025">
# ]

Reconstruct the formatted string

parts.map(&:value).join  #=> "January 31, 2025"

Japanese calendar with era

formatter = ICU4X::DateTimeFormat.new(locale, date_style: :long, calendar: :japanese)
parts = formatter.format_to_parts(Time.utc(2025, 1, 31))
era_part = parts.find { |p| p.type == :era }
era_part.value  #=> "令和"

Parameters:

  • time (Time, #to_time) —

    the time to format (or any object responding to #to_time)

Returns:



626
 
# File 'lib/icu4x/yard_docs.rb', line 626

def format_to_parts(time); end

#resolved_options ⇒ Hash

Returns the resolved options for this instance.

Returns:

  • (Hash) —

    options hash with keys:

    • ‘:locale` [String] the resolved locale identifier

    • ‘:calendar` [Symbol] the calendar system

    • ‘:date_style` [Symbol] the date style (if style options used)

    • ‘:time_style` [Symbol] the time style (if style options used)

    • ‘:year` [Symbol] the year component (if component options used)

    • ‘:month` [Symbol] the month component (if component options used)

    • ‘:day` [Symbol] the day component (if component options used)

    • ‘:weekday` [Symbol] the weekday component (if component options used)

    • ‘:hour` [Symbol] the hour component (if component options used)

    • ‘:minute` [Symbol] the minute component (if component options used)

    • ‘:second` [Symbol] the second component (if component options used)

    • ‘:time_zone` [String] the time zone (if set)

    • ‘:hour_cycle` [Symbol] the hour cycle (if set)



645
 
# File 'lib/icu4x/yard_docs.rb', line 645

def resolved_options; end