icu4x 0.8.1 → 0.9.0

data/lib/icu4x/yard_docs.rb

@@ -390,6 +390,27 @@
 #       #
 #       def select(number); end
 #
+#       # Selects the plural category for a range of numbers.
+#       #
+#       # This is equivalent to JavaScript's `Intl.PluralRules.selectRange()`.
+#       # The result depends on both the start and end values according to
+#       # locale-specific range plural rules.
+#       #
+#       # @param start_value [Integer, Float] the start of the range
+#       # @param end_value [Integer, Float] the end of the range
+#       # @return [Symbol] one of `:zero`, `:one`, `:two`, `:few`, `:many`, or `:other`
+#       #
+#       # @example
+#       #   rules.select_range(1, 5)   #=> :other (in English, "1-5 items")
+#       #   rules.select_range(0, 1)   #=> :other (in English)
+#       #
+#       # @example Russian plural ranges
+#       #   ru_rules = ICU4X::PluralRules.new(ICU4X::Locale.parse("ru"), provider: provider)
+#       #   ru_rules.select_range(1, 2)  #=> :few
+#       #   ru_rules.select_range(1, 5)  #=> :many
+#       #
+#       def select_range(start_value, end_value); end
+#
 #       # Returns all plural categories available for this locale.
 #       #
 #       # @return [Array<Symbol>] array of category symbols
@@ -425,6 +446,11 @@
 #     #   formatter = ICU4X::NumberFormat.new(locale, style: :percent)
 #     #   formatter.format(0.42)  #=> "42%"
 #     #
+#     # @example Han decimal numerals via locale extension
+#     #   locale = ICU4X::Locale.parse("ja-JP-u-nu-hanidec")
+#     #   formatter = ICU4X::NumberFormat.new(locale, provider: provider)
+#     #   formatter.format(1234)  #=> "一,二三四"
+#     #
 #     class NumberFormat
 #       # Creates a new NumberFormat instance.
 #       #
@@ -458,6 +484,32 @@
 #       #
 #       def format(number); end
 #
+#       # Formats a number and returns an array of parts.
+#       #
+#       # Each part contains a type and value, allowing for custom styling
+#       # or processing of individual components.
+#       #
+#       # @param number [Integer, Float, BigDecimal] the number to format
+#       # @return [Array<FormattedPart>] array of formatted parts
+#       #
+#       # @note For `style: :percent` and `style: :currency`, the current ICU4X
+#       #   experimental formatters do not provide part annotations. These styles
+#       #   return a single `:literal` part containing the entire formatted string.
+#       #
+#       # @example
+#       #   parts = formatter.format_to_parts(-1234.56)
+#       #   # => [
+#       #   #   #<ICU4X::FormattedPart type=:minus_sign value="-">,
+#       #   #   #<ICU4X::FormattedPart type=:integer value="1,234">,
+#       #   #   #<ICU4X::FormattedPart type=:decimal value=".">,
+#       #   #   #<ICU4X::FormattedPart type=:fraction value="56">
+#       #   # ]
+#       #
+#       # @example Reconstruct the formatted string
+#       #   parts.map(&:value).join  #=> "-1,234.56"
+#       #
+#       def format_to_parts(number); end
+#
 #       # Returns the resolved options for this instance.
 #       #
 #       # @return [Hash] options hash with keys:
@@ -476,36 +528,73 @@
 #     # 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.
 #     #
-#     # @example Format a date
+#     # @example Format a date with style
 #     #   formatter = ICU4X::DateTimeFormat.new(locale, date_style: :long)
 #     #   formatter.format(Time.now)  #=> "January 1, 2026"
 #     #
-#     # @example Format date and time
+#     # @example 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"
 #     #
+#     # @example Format with component options
+#     #   formatter = ICU4X::DateTimeFormat.new(locale, year: :numeric, month: :numeric, day: :numeric)
+#     #   formatter.format(Time.now)  #=> "Dec 28, 2025"
+#     #
 #     # @example Use Japanese calendar
 #     #   formatter = ICU4X::DateTimeFormat.new(locale, date_style: :long, calendar: :japanese)
 #     #   formatter.format(Time.now)  #=> "令和8年1月1日"
 #     #
+#     # @example 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))  #=> "二〇二五年一二月二八日"
+#     #
 #     class 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.
+#       #
 #       # @param locale [Locale] the locale for formatting
 #       # @param provider [DataProvider, nil] data provider (uses default if nil)
 #       # @param date_style [Symbol, nil] date format style: `:full`, `:long`, `:medium`, or `:short`
 #       # @param time_style [Symbol, nil] time format style: `:full`, `:long`, `:medium`, or `:short`
+#       # @param year [Symbol, nil] year component: `:numeric` or `:two_digit`
+#       # @param month [Symbol, nil] month component: `:numeric`, `:two_digit`, `:long`, `:short`, or `:narrow`
+#       # @param day [Symbol, nil] day component: `:numeric` or `:two_digit`
+#       # @param weekday [Symbol, nil] weekday component: `:long`, `:short`, or `:narrow`
+#       # @param hour [Symbol, nil] hour component: `:numeric` or `:two_digit`
+#       # @param minute [Symbol, nil] minute component: `:numeric` or `:two_digit`
+#       # @param second [Symbol, nil] second component: `:numeric` or `:two_digit`
 #       # @param time_zone [String, nil] IANA time zone identifier (e.g., "America/New_York")
 #       # @param calendar [Symbol] calendar system to use
+#       # @param hour_cycle [Symbol, nil] hour cycle: `:h11` (0-11), `:h12` (1-12), or `:h23` (0-23)
+#       # @param hour12 [Boolean, nil] `true` for 12-hour format, `false` for 24-hour format
 #       # @return [DateTimeFormat] a new instance
+#       # @raise [ArgumentError] if both style and component options are specified
 #       # @raise [DataError] if data for the locale is unavailable
 #       #
-#       # @example
+#       # @example With style options
 #       #   formatter = ICU4X::DateTimeFormat.new(locale, date_style: :long, time_style: :short)
 #       #
+#       # @example With component options
+#       #   formatter = ICU4X::DateTimeFormat.new(locale, year: :numeric, month: :long, day: :numeric)
+#       #
+#       # @example 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"
+#       #
+#       # @example 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"
+#       #
 #       def initialize(locale, provider: nil, date_style: nil, time_style: nil,
-#                      time_zone: nil, calendar: :gregory); end
+#                      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
 #
 #       # Formats a time value according to the configured options.
 #       #
@@ -514,14 +603,51 @@
 #       #
 #       def format(time); end
 #
+#       # 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.
+#       #
+#       # @param time [Time, #to_time] the time to format (or any object responding to #to_time)
+#       # @return [Array<FormattedPart>] array of formatted parts
+#       #
+#       # @example
+#       #   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">
+#       #   # ]
+#       #
+#       # @example Reconstruct the formatted string
+#       #   parts.map(&:value).join  #=> "January 31, 2025"
+#       #
+#       # @example 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  #=> "令和"
+#       #
+#       def format_to_parts(time); end
+#
 #       # Returns the resolved options for this instance.
 #       #
 #       # @return [Hash] options hash with keys:
 #       #   - `:locale` [String] the resolved locale identifier
 #       #   - `:calendar` [Symbol] the calendar system
-#       #   - `:date_style` [Symbol] the date style (if set)
-#       #   - `:time_style` [Symbol] the time style (if set)
+#       #   - `: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)
 #       #
 #       def resolved_options; end
 #     end
@@ -538,6 +664,11 @@
 #     #   formatter.format(-1, :day)   #=> "yesterday"
 #     #   formatter.format(0, :day)    #=> "today"
 #     #
+#     # @example Han decimal numerals via locale extension
+#     #   locale = ICU4X::Locale.parse("ja-u-nu-hanidec")
+#     #   formatter = ICU4X::RelativeTimeFormat.new(locale, provider: provider)
+#     #   formatter.format(-3, :day)  #=> "三 日前"
+#     #
 #     class RelativeTimeFormat
 #       # Creates a new RelativeTimeFormat instance.
 #       #
@@ -563,6 +694,26 @@
 #       #
 #       def format(value, unit); end
 #
+#       # Formats a relative time value and returns an array of parts.
+#       #
+#       # @param value [Integer] the relative time value (negative for past, positive for future)
+#       # @param unit [Symbol] time unit: `:second`, `:minute`, `:hour`, `:day`,
+#       #   `:week`, `:month`, `:quarter`, or `:year`
+#       # @return [Array<FormattedPart>] array of formatted parts
+#       #
+#       # @note The current ICU4X experimental RelativeTimeFormatter does not
+#       #   provide separate part annotations for the numeric value. The entire
+#       #   formatted string is returned as a single `:literal` part.
+#       #
+#       # @example
+#       #   parts = formatter.format_to_parts(-3, :day)
+#       #   # => [#<ICU4X::FormattedPart type=:literal value="3 days ago">]
+#       #
+#       # @example Reconstruct the formatted string
+#       #   parts.map(&:value).join  #=> "3 days ago"
+#       #
+#       def format_to_parts(value, unit); end
+#
 #       # Returns the resolved options for this instance.
 #       #
 #       # @return [Hash] options hash with keys:
@@ -606,6 +757,29 @@
 #       #
 #       def format(list); end
 #
+#       # Formats a list of strings and returns an array of parts.
+#       #
+#       # Each part contains a type and value, allowing for custom styling
+#       # or processing of individual components.
+#       #
+#       # @param list [Array<String>] the list items to format
+#       # @return [Array<FormattedPart>] array of formatted parts
+#       #
+#       # @example
+#       #   parts = formatter.format_to_parts(["Apple", "Banana", "Cherry"])
+#       #   # => [
+#       #   #   #<ICU4X::FormattedPart type=:element value="Apple">,
+#       #   #   #<ICU4X::FormattedPart type=:literal value=", ">,
+#       #   #   #<ICU4X::FormattedPart type=:element value="Banana">,
+#       #   #   #<ICU4X::FormattedPart type=:literal value=", and ">,
+#       #   #   #<ICU4X::FormattedPart type=:element value="Cherry">
+#       #   # ]
+#       #
+#       # @example Reconstruct the formatted string
+#       #   parts.map(&:value).join  #=> "Apple, Banana, and Cherry"
+#       #
+#       def format_to_parts(list); end
+#
 #       # Returns the resolved options for this instance.
 #       #
 #       # @return [Hash] options hash with keys:

data/lib/icu4x.rb

@@ -54,6 +54,28 @@ module ICU4X
   class DataGeneratorError < Error; end
 end
 
+# Define FormattedPart data class for format_to_parts methods
+module ICU4X
+  FormattedPart = Data.define(:type, :value)
+end
+
+# Enhance the FormattedPart data class
+module ICU4X
+  # Represents a part of a formatted string.
+  #
+  # Used by format_to_parts methods in DateTimeFormat, NumberFormat,
+  # ListFormat, and RelativeTimeFormat.
+  #
+  # @!attribute [r] type
+  #   @return [Symbol] The part type (e.g., :integer, :literal, :year)
+  # @!attribute [r] value
+  #   @return [String] The formatted value
+  class FormattedPart
+    # @return [String] Human-readable representation
+    def inspect = "#<ICU4X::FormattedPart type=#{type.inspect} value=#{value.inspect}>"
+  end
+end
+
 # Define Segment data class for Segmenter
 module ICU4X
   class Segmenter

data/sig/icu4x.rbs

@@ -18,6 +18,14 @@ module ICU4X
   class DataGeneratorError < Error
   end
 
+  class FormattedPart
+    attr_reader type: Symbol
+    attr_reader value: String
+
+    def self.[]: (Symbol type, String value) -> FormattedPart
+    def self.new: (type: Symbol, value: String) -> FormattedPart
+  end
+
   class DataProvider
     def self.from_blob: (Pathname path, ?priority: :language | :region) -> DataProvider
   end
@@ -28,7 +36,8 @@ module ICU4X
   end
 
   class Locale
-    def self.parse: (String locale_str) -> Locale
+    def self.parse_bcp47: (String locale_str) -> Locale
+    alias self.parse self.parse_bcp47
     def self.parse_posix: (String posix_str) -> Locale
 
     def language: () -> String?
@@ -49,6 +58,7 @@ module ICU4X
     def self.new: (Locale locale, ?provider: DataProvider, ?type: plural_rule_type) -> PluralRules
 
     def select: (Integer | Float number) -> plural_category
+    def select_range: (Integer | Float start_value, Integer | Float end_value) -> plural_category
     def categories: () -> Array[plural_category]
     def resolved_options: () -> { locale: String, type: plural_rule_type }
   end
@@ -59,6 +69,14 @@ module ICU4X
   type date_style = :full | :long | :medium | :short
   type time_style = :full | :long | :medium | :short
   type datetime_calendar = :gregory | :japanese | :buddhist | :chinese | :hebrew | :islamic | :persian | :indian | :ethiopian | :coptic | :roc | :dangi
+  type hour_cycle = :h11 | :h12 | :h23
+  type year_style = :numeric | :two_digit
+  type month_style = :numeric | :two_digit | :long | :short | :narrow
+  type day_style = :numeric | :two_digit
+  type weekday_style = :long | :short | :narrow
+  type hour_style = :numeric | :two_digit
+  type minute_style = :numeric | :two_digit
+  type second_style = :numeric | :two_digit
 
   class NumberFormat
     def self.new: (
@@ -74,6 +92,7 @@ module ICU4X
     ) -> NumberFormat
 
     def format: (Integer | Float | BigDecimal number) -> String
+    def format_to_parts: (Integer | Float | BigDecimal number) -> Array[FormattedPart]
     def resolved_options: () -> {
       locale: String,
       style: number_format_style,
@@ -92,17 +111,35 @@ module ICU4X
       ?provider: DataProvider,
       ?date_style: date_style,
       ?time_style: time_style,
+      ?year: year_style,
+      ?month: month_style,
+      ?day: day_style,
+      ?weekday: weekday_style,
+      ?hour: hour_style,
+      ?minute: minute_style,
+      ?second: second_style,
       ?time_zone: String,
-      ?calendar: datetime_calendar
+      ?calendar: datetime_calendar,
+      ?hour_cycle: hour_cycle,
+      ?hour12: bool
     ) -> DateTimeFormat
 
     def format: (Time time) -> String
+    def format_to_parts: (Time time) -> Array[FormattedPart]
     def resolved_options: () -> {
       locale: String,
       calendar: datetime_calendar,
       ?date_style: date_style,
       ?time_style: time_style,
-      ?time_zone: String
+      ?year: year_style,
+      ?month: month_style,
+      ?day: day_style,
+      ?weekday: weekday_style,
+      ?hour: hour_style,
+      ?minute: minute_style,
+      ?second: second_style,
+      ?time_zone: String,
+      ?hour_cycle: hour_cycle
     }
   end
 
@@ -119,6 +156,7 @@ module ICU4X
     ) -> RelativeTimeFormat
 
     def format: (Integer value, relative_time_unit unit) -> String
+    def format_to_parts: (Integer value, relative_time_unit unit) -> Array[FormattedPart]
     def resolved_options: () -> {
       locale: String,
       style: relative_time_format_style,
@@ -141,6 +179,7 @@ module ICU4X
     ) -> ListFormat
 
     def format: (Array[String] list) -> String
+    def format_to_parts: (Array[String] list) -> Array[FormattedPart]
     def resolved_options: () -> {
       locale: String,
       type: list_format_type,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: icu4x
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.0
 platform: ruby
 authors:
 - OZAWA Sakuro
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-12 00:00:00.000000000 Z
+date: 2026-02-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable
@@ -72,6 +72,7 @@ files:
 - ext/icu4x/src/list_format.rs
 - ext/icu4x/src/locale.rs
 - ext/icu4x/src/number_format.rs
+- ext/icu4x/src/parts_collector.rs
 - ext/icu4x/src/plural_rules.rs
 - ext/icu4x/src/relative_time_format.rs
 - ext/icu4x/src/segmenter.rs