ffi-icu 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ffb113b9b98bd46355e3d6750fc1026d7732d06a8575bf2022aa073e72c532e
-  data.tar.gz: 43b5a202de5a08790c2a257a8a05f9867df2a5b42624cab157dbf20eaa85eb37
+  metadata.gz: 0f0256350b6cfd290356bcab5c7e501dcc55959f2a995dac452bb43756050788
+  data.tar.gz: 4fe1bd3bf83133f012f6d71d07ec997ceb9abae835e8b7be4bed6d8a7ea27bb1
 SHA512:
-  metadata.gz: 63fefe8619f8bfbad7ead9ac1ada9471074246b1a2d7c4af6cdb899250f464a07c8596bb55e836f44a128d1ce077b939404b2ad85c612298cc65a66bc1fe92f8
-  data.tar.gz: 06e98c3af40a060bbbd2a19a9e5b95fcea49d1d75316a1f2ea639d91d88721886fe079ad3e4952ac8750cdfbf62e5dc4550b0893c3583c1896764c46d1c3fd46
+  metadata.gz: 8560b297f442ceb1548dc9214e7875cc050f2ca60bf9b9d7c8cc35ea1c2afcebbab52f139a294e610d6272049c2ca8de58fff1a9c8b42efded0088f7e6bf7a97
+  data.tar.gz: 18fd3d1b2c0f83ba1bc246381e41e72a77d8db495db2d1a0690b82c4d2cff7f00dbae88ab66f786d2d83c9445a925c1ddea2e6f7e6b235410344ac82a9a54fec

data/Gemfile

@@ -3,11 +3,10 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
+  gem 'minitest', '~> 6.0'
+  gem 'minitest-mock', '~> 5.27'
   gem 'rake', '>= 12.3.3'
-  gem 'rspec', '~> 3.13'
   gem 'rubocop', '~> 1.86'
   gem 'rubocop-minitest', '~> 0.39'
   gem 'rubocop-packaging', '~> 0.6'
-  gem 'rubocop-rspec', '~> 3.9'
-  gem 'rubocop-rspec_rails', '~> 2.32'
 end

data/README.md

@@ -1,248 +1,404 @@
 # ffi-icu
 
-FFI wrappers for [International Components for Unicode (ICU)][icu].
-ICU provides comprehensive localization and security features.
-Majority personal computing devices, server operating systems and web browsers use ICU.
-ICU builds on top of Unicode's Common Locale Data Repository (CLDR).
+Ruby FFI wrappers for [International Components for Unicode (ICU)][icu].
+ICU provides Unicode text processing, character encoding detection, and
+locale-aware formatting. Its locale data comes from the
+[Common Locale Data Repository (CLDR)][cldr].
 
-## Gem
+## Installation
 
-[Rubygem](http://rubygems.org/gems/ffi-icu "ffi-icu")
+ffi-icu requires Ruby 3.2 or newer and the ICU shared libraries.
+On Linux, use the ICU packages supplied by a major distribution, such as Debian,
+Ubuntu, or Fedora. Install ICU from your distribution's supported repositories
+before installing the gem.
 
+### Debian and Ubuntu
+
+```sh
+sudo apt update
+sudo apt install libicu-dev
 ```
+
+The `libicu-dev` package installs the matching ICU runtime libraries as dependencies.
+See the official [Debian package][debian-icu] and [Ubuntu package][ubuntu-icu] pages.
+
+### Fedora
+
+```sh
+sudo dnf install libicu
+```
+
+See the official [Fedora libicu package][fedora-icu] page.
+
+### Install the gem
+
+```sh
 gem install ffi-icu
 ```
 
-## Dependencies
+The gem is published on [RubyGems][rubygems]. Load it before running the examples:
 
-ICU.
+```ruby
+require('ffi-icu')
+```
+
+### ICU in a custom directory
 
-If you get messages that the library or functions are not found, you can set some environment variables to tell ffi-icu where to find it, e.g.:
+ffi-icu normally discovers the distribution's ICU libraries automatically.
+If you need to override discovery, set `FFI_ICU_LIB` to the directory containing
+the shared libraries before loading the gem:
 
 ```sh
-$ export FFI_ICU_LIB="icui18n.so"
-$ export FFI_ICU_VERSION_SUFFIX="_3_8"
-$ ruby -r ffi-icu program.rb
+export FFI_ICU_LIB=/opt/icu/lib
+ruby my_script.rb
 ```
 
-# Features
+The library detects ICU's versioned function names automatically.
+
+## Features
+
+Localized output, including punctuation and spaces, can vary with the installed
+ICU and CLDR versions. Duration and list formatting require ICU 67 or newer.
 
-## Character Encoding Detection
+### Character Encoding Detection
 
-Examples:
+Detect an encoding and inspect the confidence score:
 
 ```ruby
-match = ICU::CharDet.detect(str)
+match = ICU::CharDet.detect('æåø')
 match.name       # => "UTF-8"
 match.confidence # => 80
 ```
 
-or
+Reuse a detector for multiple inputs:
 
 ```ruby
 detector = ICU::CharDet::Detector.new
-detector.detect(str) => #<struct ICU::CharDet::Detector::Match ...>
+detector.detect('æåø').name # => "UTF-8"
+detector.detect_all('foo bar').is_a?(Array) # => true
 ```
 
-* speed
+### Locale-Aware Collation
 
-## Locale Sensitive Collation
+Sort strings using a locale's collation rules:
 
-Examples:
+```ruby
+ICU::Collation.collate('nb', ['å', 'æ', 'ø']) # => ["æ", "ø", "å"]
+```
+
+Reuse a collator to compare and sort strings:
 
 ```ruby
-ICU::Collation.collate("nb", %w[å æ ø]) == %w[æ ø å] #=> true
+collator = ICU::Collation::Collator.new('nb')
+collator.compare('a', 'b')  # => -1
+collator.greater?('z', 'a') # => true
+collator.collate(['å', 'æ', 'ø']) # => ["æ", "ø", "å"]
 ```
 
-or
+### Text Boundary Analysis
+
+Find word boundaries or extract the substrings between them:
 
 ```ruby
-collator = ICU::Collation::Collator.new("nb")
-collator.compare("a", "b")  #=> -1
-collator.greater?("z", "a") #=> true
-collator.collate(%w[å æ ø]) #=> ["æ", "ø", "å"]
+iterator = ICU::BreakIterator.new(:word, 'en_US')
+iterator.text = 'This is a sentence.'
+iterator.to_a # => [0, 4, 5, 7, 8, 9, 10, 18, 19]
+iterator.substrings # => ["This", " ", "is", " ", "a", " ", "sentence", "."]
 ```
 
-## Text Boundary Analysis
+Boundary offsets use UTF-16 code units. Use `substrings` to extract text without
+converting those offsets to Ruby string indexes.
+
+### Number and Currency Formatting
 
-Examples:
+Format numbers, percentages, and currency amounts:
 
 ```ruby
-iterator = ICU::BreakIterator.new(:word, "en_US")
-iterator.text = "This is a sentence."
-iterator.to_a  #=> [0, 4, 5, 7, 8, 9, 10, 18, 19]
+ICU::NumberFormatting.format_number('en', 1_000) # => "1,000"
+ICU::NumberFormatting.format_number('de-DE', 1_234.56) # => "1.234,56"
+ICU::NumberFormatting.format_currency('en', 123.45, 'USD') # => "$123.45"
+ICU::NumberFormatting.format_percent('en', 0.53) # => "53%"
+ICU::NumberFormatting.spell('en_US', 1_000) # => "one thousand"
+ICU::NumberFormatting.format_number('en', BigDecimal('10000.123')) # => "10,000.123"
 ```
 
-## Number/Currency Formatting
+Reuse a formatter for repeated calls. The French Canadian example uses a
+non-breaking space (`\u00A0`) as its thousands separator:
 
-Examples:
+```ruby
+number_formatter = ICU::NumberFormatting.create('fr-CA')
+number_formatter.format(1_000) # => "1\u00A0000"
+number_formatter.format(1_000.123) # => "1\u00A0000,123"
+
+currency_formatter = ICU::NumberFormatting.create('en-US', :currency)
+currency_formatter.format(1_234.56, 'USD') # => "$1,234.56"
+```
+
+For anything the presets above do not cover, pass an
+[ICU number skeleton](https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html)
+(ICU >= 62):
 
 ```ruby
-# class method interface
-ICU::NumberFormatting.format_number("en", 1_000) #=> "1,000"
-ICU::NumberFormatting.format_number("de-DE", 1234.56) #=> "1.234,56"
-ICU::NumberFormatting.format_currency("en", 123.45, 'USD') #=> "$123.45"
-ICU::NumberFormatting.format_percent("en", 0.53, 'USD') #=> "53%"
-ICU::NumberFormatting.spell("en_US", 1_000) #=> "one thousand"
+ICU::NumberFormatting.format_with_skeleton('en', 1_234, 'compact-short') # => "1.2K"
+ICU::NumberFormatting.format_with_skeleton('en', 0.1234, 'percent scale/100 .0') # => "12.3%"
+
+formatter = ICU::NumberFormatting.create_with_skeleton('en', 'precision-integer')
+formatter.format(999.6) # => "1,000"
+```
+
+### Currency Metadata
 
-# reusable formatting objects
-numf = ICU::NumberFormatting.create('fr-CA')
-numf.format(1000) #=> "1 000"
+Look up ISO 4217 codes, localized names, symbols, and decimal digits:
 
-curf = ICU::NumberFormatting.create('en-US', :currency)
-curf.format(1234.56, 'USD') #=> "$1,234.56"
+```ruby
+ICU::Currency.for_locale('en_US') # => "USD"
+ICU::Currency.for_locale('de_DE') # => "EUR"
+ICU::Currency.available(:common).include?('USD') # => true
+
+usd = ICU::Currency.new('usd')
+usd.code # => "USD"
+usd.symbol('en_US') # => "$"
+usd.name('en') # => "US Dollar"
+usd.plural_name('en', 'other') # => "US dollars"
+usd.fraction_digits # => 2
+usd.fraction_digits(:cash) # => 2
+usd.numeric_code # => 840
+
+ICU::Currency.new('JPY').fraction_digits # => 0
+ICU::Currency.symbol('EUR', 'en_US') # => "€"
 ```
 
-## Message Formatting
+`narrow_symbol(locale)` requires ICU 61 or newer. `numeric_code` requires ICU 49 or newer.
 
-Message formatting supports ICU MessageFormat patterns using numbered arguments:
+### Message Formatting
+
+Use numbered arguments for ICU MessageFormat patterns, including plurals and selects:
 
 ```ruby
 formatter = ICU::MessageFormatting.create(
   '{0, plural, one {# item} other {# items}}',
   locale: 'en-US'
 )
+formatter.format([1]) # => "1 item"
+formatter.format([2]) # => "2 items"
 
-formatter.format([2]) #=> "2 items"
+ICU::MessageFormatting.format('Hello, {0}!', locale: 'en-US', arguments: ['Ada'])
+# => "Hello, Ada!"
 ```
 
-Patterns can also be validated without formatting a message:
+Validate a pattern before formatting:
 
 ```ruby
-ICU::MessageFormatting.validate('{0, select, male {He} female {She} other {They}}', locale: 'en-US')
-#=> true
+pattern = '{0, select, male {He} female {She} other {They}}'
+ICU::MessageFormatting.validate(pattern, locale: 'en-US') # => true
+ICU::MessageFormatting.valid?('{0, plural', locale: 'en-US') # => false
 ```
 
-The current API uses ICU's C MessageFormat API and therefore resolves numbered arguments only. Named arguments are not resolved by this API, and rich-text tags require a separate compatibility layer. Supported Ruby argument types are `String`, `Integer`, `Float`, and `BigDecimal`.
+`validate` raises `ICU::MessageFormatting::InvalidPatternError` for an invalid
+pattern. The error exposes the pattern, locale, line, and offset. Use `valid?`
+when you want a boolean result.
 
-## Time Formatting/Parsing
+Arguments must be an array of numbered values. Supported types are `String`,
+`Integer`, `Float`, and `BigDecimal`. Use strings for simple and select arguments,
+and numbers for numeric arguments. Named arguments and rich-text tags are not supported.
 
-Examples:
+### Time Formatting and Parsing
 
-```ruby
-# class method interface
-f = ICU::TimeFormatting.format(Time.mktime(2015, 11, 12, 15, 21, 16), {:locale => 'cs_CZ', :zone => 'Europe/Prague', :date => :short, :time => :short})
-f #=> "12.11.15 15:21"
+Set the time zone explicitly for predictable output:
 
-# reusable formatting objects
-formatter = ICU::TimeFormatting.create(:locale => 'cs_CZ', :zone => 'Europe/Prague', :date => :long, :time => :none)
-formatter.format(Time.now)  #=> "25. února 2015"
+```ruby
+time = Time.utc(2015, 11, 12, 14, 21)
+ICU::TimeFormatting.format(
+  time,
+  locale: 'cs_CZ', zone: 'Europe/Prague', date: :short, time: :short
+)
+# => "12.11.15 15:21"
 ```
 
+Reuse a formatter for formatting and parsing:
+
 ```ruby
-# reusable formatting objects
-formatter = ICU::TimeFormatting.create(:locale => 'cs_CZ', :zone => 'Europe/Prague', :date => :long, :time => :none)
-formatter.parse("25. února 2015") #=> Wed Feb 25 00:00:00 +0100 2015
+formatter = ICU::TimeFormatting.create(
+  locale: 'cs_CZ', zone: 'Europe/Prague', date: :long, time: :none
+)
+formatter.format(Time.utc(2015, 2, 25)) # => "25. února 2015"
+formatter.parse('25. února 2015').utc.to_s # => "2015-02-24 23:00:00 UTC"
 ```
 
-For skeleton formatting, visit the [Unicode date field symbol table](https://unicode-org.github.io/icu/userguide/format_parse/datetime/#date-field-symbol-table) page to help find the pattern characters to use.
+Use a skeleton to request date fields and let ICU choose the locale's pattern.
+See the [Unicode date field symbol table][date-fields] for supported symbols:
 
 ```ruby
-formatter = ICU::TimeFormatting.create(:locale => 'cs_CZ', :date => :pattern, :time => :pattern, :skeleton => 'MMMMY')
-formatter.format(Time.now)  #=> "únor 2015"
-
-formatter = ICU::TimeFormatting.create(:locale => 'cs_CZ', :date => :pattern, :time => :pattern, :skeleton => 'Y')
-formatter.format(Time.now)  #=> "2015"
+formatter = ICU::TimeFormatting.create(
+  locale: 'cs_CZ', zone: 'UTC', date: :pattern, time: :pattern, skeleton: 'MMMMy'
+)
+formatter.format(Time.utc(2015, 2, 25)) # => "únor 2015"
 ```
 
-## Duration Formatting
+Choose an hour cycle with `h11`, `h12`, `h23`, or `h24`, or use `:locale` for the
+locale's default:
 
 ```ruby
-# What the various styles look like
-formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :long)
-formatter.format({hours: 8, minutes: 40, seconds: 35})  #=> "8 hours, 40 minutes, 35 seconds"
+ICU::TimeFormatting.format(
+  Time.utc(2021, 4, 1, 12, 5),
+  locale: 'en_AU', zone: 'UTC', date: :none, time: :short, hour_cycle: 'h23'
+)
+# => "12:05"
+```
 
-formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :short)
-formatter.format({hours: 8, minutes: 40, seconds: 35})  #=> "8 hrs, 40 mins, 35 secs"
+### Duration Formatting
 
-formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :narrow)
-formatter.format({hours: 8, minutes: 40, seconds: 35})  #=> "8h 40min. 35s."
-formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :digital)
-formatter.format({hours: 8, minutes: 40, seconds: 35})  #=> "8:40:35"
+Duration formatting requires ICU 67 or newer. Choose `:long`, `:short`, `:narrow`,
+or `:digital`:
 
-# How digital & non-digital formats deal with units > hours
-formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :narrow)
-formatter.format({days: 2, hours: 8, minutes: 40, seconds: 35})  #=> "2d 8h 40min. 35s."
-formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :digital)
-formatter.format({days: 2, hours: 8, minutes: 40, seconds: 35})  #=> "2d 8:40:35"
+```ruby
+fields = { hours: 8, minutes: 40, seconds: 35 }
+ICU::DurationFormatting.format(fields, locale: 'en-AU', style: :long)
+# => "8 hours, 40 minutes, 35 seconds"
+ICU::DurationFormatting.format(fields, locale: 'en-AU', style: :short)
+# => "8 hrs, 40 mins, 35 secs"
+ICU::DurationFormatting.format(fields, locale: 'en-AU', style: :narrow)
+# => "8h 40m 35s"
+ICU::DurationFormatting.format(fields, locale: 'en-AU', style: :digital)
+# => "8:40:35"
+```
 
-# Missing or zero parts are omitted
-formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :long)
-formatter.format({days: 2, minutes: 40, seconds:0})  #=> "2 days, 40 minutes"
+Reuse a formatter when the locale and style stay the same. Larger units remain
+outside the digital clock, and missing or zero fields are omitted:
 
+```ruby
 formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :digital)
-formatter.format({hours: 2, minutes: 40})  #=> "2:40"
+formatter.format({ days: 2, hours: 8, minutes: 40, seconds: 35 }) # => "2d 8:40:35"
+formatter.format({ hours: 2, minutes: 40 }) # => "2:40"
+formatter.format({ minutes: 40, seconds: 7 }) # => "40:07"
 
-formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :digital)
-formatter.format({minutes: 40, seconds: 7})  #=> "40:07"
+formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :long)
+formatter.format({ days: 2, minutes: 40, seconds: 0 }) # => "2 days, 40 minutes"
+```
 
-# Sub-second parts are folded into seconds for digital display
-formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :digital)
-formatter.format({hours: 5, minutes: 7, seconds: 23, milliseconds: 98, microseconds: 997})  #=> "5:07:23.098997"
+Digital formatting folds milliseconds, microseconds, and nanoseconds into seconds.
+Supplying a smaller unit preserves its trailing zeros:
 
-# Zero-extension of sub-second parts in digital style
-formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :digital)
-formatter.format({hours: 5, minutes: 7, seconds: 23, milliseconds: 400})  #=> "5:07:23.400"
+```ruby
 formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :digital)
-formatter.format({hours: 5, minutes: 7, seconds: 23, milliseconds: 400, microseconds: 700})  #=> "5:07:23.400700"
+formatter.format({ hours: 5, minutes: 7, seconds: 23, milliseconds: 98, microseconds: 997 })
+# => "5:07:23.098997"
+formatter.format({ hours: 5, minutes: 7, seconds: 23, milliseconds: 400 })
+# => "5:07:23.400"
+formatter.format({ hours: 5, minutes: 7, seconds: 23, milliseconds: 400, microseconds: 700 })
+# => "5:07:23.400700"
+```
+
+Fractional parts are truncated except on the smallest supplied unit, which must
+be seconds or smaller to retain a fraction:
 
-# All fractional parts except the last are truncated
+```ruby
 formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'en-AU', style: :long)
-formatter.format({days: 2, hours: 7.3, minutes: 40.9, seconds:0.43})  #=> "2 days, 7 hours, 40 minutes, 0.43 seconds"
+formatter.format({ days: 2, hours: 7.3, minutes: 40.9, seconds: 0.43 })
+# => "2 days, 7 hours, 40 minutes, 0.43 seconds"
+```
 
-# With RU locale
-formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'ru', style: :long)
-formatter.format({hours: 1, minutes: 2, seconds: 3})  #=> "1 час 2 минуты 3 секунды"
+Unit names and separators follow the requested locale:
+
+```ruby
 formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'ru', style: :long)
-formatter.format({hours: 10, minutes: 20, seconds: 30})  #=> "10 часов 20 минут 30 секунд"
-formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'ru', style: :narrow)
-formatter.format({hours: 1, minutes: 2, seconds: 3})  #=> "1 ч 2 мин 3 с"
+formatter.format({ hours: 1, minutes: 2, seconds: 3 }) # => "1 час 2 минуты 3 секунды"
+formatter.format({ hours: 10, minutes: 20, seconds: 30 }) # => "10 часов 20 минут 30 секунд"
+
 formatter = ICU::DurationFormatting::DurationFormatter.new(locale: 'ru', style: :narrow)
-formatter.format({hours: 10, minutes: 20, seconds: 30})  #=> "10 ч 20 мин 30 с"
+formatter.format({ hours: 1, minutes: 2, seconds: 3 }) # => "1 ч 2 мин 3 с"
 ```
 
-## Transliteration
+### Transliteration
 
-Example:
+Convert between scripts or reuse a transliterator for multiple inputs:
 
 ```ruby
 ICU::Transliteration.transliterate('Traditional-Simplified', '沈從文') # => "沈从文"
+
+transliterator = ICU::Transliteration::Transliterator.new('Latin-ASCII')
+transliterator.transliterate('café') # => "cafe"
 ```
 
-## List Formatting
+Apply a sequence of custom transliteration rules:
 
-Join items with locale-aware separators and conjunctions:
+```ruby
+ICU::Transliteration.translit('NFD; [:Nonspacing Mark:] Remove; NFC', 'âêîôû') # => "aeiou"
+```
+
+### Unicode Normalization
+
+Compose canonically equivalent text into NFC, or check whether it is already normalized:
+
+```ruby
+normalizer = ICU::Normalizer.new(nil, 'nfc', :compose)
+normalizer.normalize("A\u030A") # => "Å"
+normalizer.normalized?('Å') # => true
+normalizer.normalized?("A\u030A") # => false
+```
+
+Use `:decompose` with `'nfc'` for NFD. Use `'nfkc'` with `:compose` or `:decompose`
+for compatibility normalization (NFKC or NFKD):
 
 ```ruby
-ICU::ListFormatting.format(['Alice', 'Bob', 'Jane'], locale: 'en', style: :and)
-# => "Alice, Bob, and Jane"
+normalizer = ICU::Normalizer.new(nil, 'nfkc', :compose)
+normalizer.normalize('ffi') # => "ffi"
+```
+
+A convenience method also supports one-off normalization:
 
-ICU::ListFormatting.format(['Alice', 'Bob', 'Jane'], locale: 'fr', style: :and)
-# => "Alice, Bob et Jane"
+```ruby
+ICU::Normalization.normalize('Å', :nfd) # => "A\u030A"
+ICU::Normalization.normalize("A\u030A", :nfc) # => "Å"
 ```
 
-Supported styles are:
+### List Formatting
 
-- `:and`: the default
-- `:or`
-- `:unit`: ICU's units list type
+List formatting requires ICU 67 or newer. Join strings with locale-aware
+separators and conjunctions:
 
-Only ICU's wide width is exposed. Styles must be symbols, and items must be strings. The Ruby/FFI layer converts Ruby strings to ICU's UTF-16 `UChar` values before calling ICU. List formatting requires ICU 67 or newer.
+```ruby
+ICU::ListFormatting.format(['Alice', 'Bob', 'Jane'], locale: 'en') # => "Alice, Bob, and Jane"
+ICU::ListFormatting.format(['Alice', 'Bob', 'Jane'], locale: 'fr', style: :and) # => "Alice, Bob et Jane"
+ICU::ListFormatting.format(['Alice', 'Bob', 'Jane'], locale: 'en', style: :or) # => "Alice, Bob, or Jane"
+ICU::ListFormatting.format(['Alice', 'Bob', 'Jane'], locale: 'en', style: :unit) # => "Alice, Bob, Jane"
+```
 
-## Locale
+The default style is `:and`. Styles must be symbols, and all items must be strings.
+The formatter uses ICU's wide list width.
 
-Examples:
+### Locale
+
+Look up localized names and choose display-name contexts:
 
 ```ruby
 locale = ICU::Locale.new('en-US')
-locale.display_country('en-US') #=> "United States"
-locale.display_language('es') #=> "inglés"
-locale.display_name('es') #=> "inglés (Estados Unidos)"
-locale.display_name_with_context('en-US', [:length_short]) #=> "English (US)"
-locale.display_name_with_context('en-US', [:length_full])  #=> "English (United States)"
+locale.display_country('en-US') # => "United States"
+locale.display_language('es') # => "inglés"
+locale.display_name('es') # => "inglés (Estados Unidos)"
+locale.display_name_with_context('en-US', [:length_short]) # => "English (US)"
+locale.display_name_with_context('en-US', [:length_full]) # => "English (United States)"
+
+ICU::Locale.new('fa-AF').display_name_with_context('en', [:dialect_names]) # => "Dari"
+```
+
+Convert BCP 47 language tags to ICU locale IDs or add likely subtags:
 
-dari = ICU::Locale.new('fa-AF')
-dari.display_name_with_context('en', [:dialect_names]) #=> "Dari"
+```ruby
+locale = ICU::Locale.for_language_tag('en-US')
+locale.id # => "en_US"
+locale.to_language_tag # => "en-US"
+ICU::Locale.new('en').with_likely_subtags.to_s # => "en_Latn_US"
 ```
 
+## Benchmarks
+
+Benchmarks live in [`benchmark/`](benchmark/README.md) with a separate Gemfile.
+
 [icu]: https://github.com/unicode-org/icu
+[cldr]: https://cldr.unicode.org/
+[rubygems]: https://rubygems.org/gems/ffi-icu
+[debian-icu]: https://packages.debian.org/stable/libicu-dev
+[ubuntu-icu]: https://packages.ubuntu.com/search?keywords=libicu-dev
+[fedora-icu]: https://packages.fedoraproject.org/pkgs/icu/libicu/
+[date-fields]: https://unicode-org.github.io/icu/userguide/format_parse/datetime/#date-field-symbol-table

data/Rakefile

@@ -4,18 +4,14 @@ require 'rake'
 require 'bundler'
 Bundler::GemHelper.install_tasks
 
-require 'rspec/core/rake_task'
-RSpec::Core::RakeTask.new(:spec) do |spec|
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rspec_opts = '--backtrace'
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test' << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.warning = false
 end
 
-RSpec::Core::RakeTask.new(:rcov) do |spec|
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rcov = true
-end
-
-task default: :spec
+task default: :test
 
 begin
   require('yard')

data/lib/ffi-icu/duration_formatting.rb

@@ -262,32 +262,8 @@ module ICU
         result.string
       end
 
-      def number_formatter(skeleton)
-        @number_formatters[skeleton] ||= begin
-          skeleton_uchar = UCharPointer.from_utf8(skeleton)
-          FFI::AutoPointer.new(
-            Lib.check_error do |error|
-              Lib.unumf_openForSkeletonAndLocale(skeleton_uchar, skeleton_uchar.length_in_uchars,
-                                                 @locale, error)
-            end,
-            Lib.method(:unumf_close)
-          )
-        end
-      end
-
       def format_number(value, skeleton)
-        formatter = number_formatter(skeleton)
-        result = FFI::AutoPointer.new(
-          Lib.check_error { |error| Lib.unumf_openResult(error) },
-          Lib.method(:unumf_closeResult)
-        )
-        value_str = value.to_s
-        Lib.check_error do |error|
-          Lib.unumf_formatDecimal(formatter, value_str, value_str.size, result, error)
-        end
-        Lib::Util.read_uchar_buffer(0) do |buf, error|
-          Lib.unumf_resultToString(result, buf, buf.length_in_uchars, error)
-        end
+        (@number_formatters[skeleton] ||= NumberFormatting::SkeletonFormatter.new(@locale, skeleton)).format(value)
       end
 
       def format_list(values)

data/lib/ffi-icu/lib.rb

@@ -497,22 +497,27 @@ module ICU
     attach_function :ubrk_following,      "ubrk_following#{suffix}",      [:pointer, :int32_t], :int32_t
     attach_function :ubrk_isBoundary,     "ubrk_isBoundary#{suffix}",     [:pointer, :int32_t], :int32_t
 
+    # UNUM_FORMAT_STYLE_COUNT is deprecated: "The numeric value may change over time, see ICU ticket #12420."
     enum :number_format_style, [
-      :pattern_decimal,
-      :decimal,
-      :currency,
-      :percent,
-      :scientific,
-      :spellout,
-      :ordinal,
-      :duration,
-      :numbering_system,
-      :pattern_rule_based,
-      :currency_iso,
-      :currency_plural,
-      :format_style_count,
-      :default,
-      :ignore
+      :pattern_decimal, 0,
+      :decimal, 1,
+      :currency, 2,
+      :percent, 3,
+      :scientific, 4,
+      :spellout, 5,
+      :ordinal, 6,
+      :duration, 7,
+      :numbering_system, 8,
+      :pattern_rule_based, 9,
+      :currency_iso, 10,
+      :currency_plural, 11,
+      :currency_accounting, 12,
+      :cash_currency, 13,
+      :decimal_compact_short, 14,
+      :decimal_compact_long, 15,
+      :currency_standard, 16,
+      :default, 1, # UNUM_DEFAULT = UNUM_DECIMAL
+      :ignore, 0 # UNUM_IGNORE = UNUM_PATTERN_DECIMAL
     ]
     enum :number_format_attribute, [
       :parse_int_only, :grouping_used, :decimal_always_show, :max_integer_digits, :min_integer_digits, :integer_digits,

data/lib/ffi-icu/message_formatting.rb

@@ -34,8 +34,8 @@ module ICU
       create(pattern, locale:).format(arguments)
     end
 
-    # rubocop:disable-next Naming/PredicateMethod
-    def self.validate(pattern, locale:)
+    # Raises on invalid patterns; use valid? for a predicate.
+    def self.validate(pattern, locale:) # rubocop:disable Naming/PredicateMethod
       create(pattern, locale:)
       true
     end

data/lib/ffi-icu/number_formatting.rb

@@ -15,6 +15,10 @@ module ICU
       end
     end
 
+    def self.create_with_skeleton(locale, skeleton)
+      SkeletonFormatter.new(locale, skeleton)
+    end
+
     def self.clear_default_options
       @default_options.clear
     end
@@ -35,6 +39,10 @@ module ICU
       create(locale, :currency, options).format(number, currency)
     end
 
+    def self.format_with_skeleton(locale, number, skeleton)
+      create_with_skeleton(locale, skeleton).format(number)
+    end
+
     def self.spell(locale, number, options = {})
       create(locale, :spellout, options).format(number)
     end
@@ -48,6 +56,11 @@ module ICU
       private
 
       def make_formatter(type, locale)
+        if type == :pattern_rule_based
+          raise(ArgumentError, 'The pattern_rule_based style needs custom rules, which ffi-icu does not support; ' \
+                               'ICU::NumberFormatting.create_with_skeleton covers most other formats')
+        end
+
         ptr = Lib.check_error do |error|
           Lib.unum_open(type, FFI::MemoryPointer.new(4), 0, locale, FFI::MemoryPointer.new(4), error)
         end
@@ -149,5 +162,33 @@ module ICU
         end
       end
     end
+
+    class SkeletonFormatter
+      def initialize(locale, skeleton)
+        unless Lib.respond_to?(:unumf_openForSkeletonAndLocale)
+          raise('ICU::NumberFormatting::SkeletonFormatter requires ICU >= 62')
+        end
+
+        skeleton_uchar = UCharPointer.from_utf8(skeleton)
+        @f = FFI::AutoPointer.new(
+          Lib.check_error do |error|
+            Lib.unumf_openForSkeletonAndLocale(skeleton_uchar, skeleton_uchar.length_in_uchars, locale, error)
+          end,
+          Lib.method(:unumf_close)
+        )
+      end
+
+      def format(number)
+        decimal = number.to_s
+        result = FFI::AutoPointer.new(
+          Lib.check_error { |error| Lib.unumf_openResult(error) },
+          Lib.method(:unumf_closeResult)
+        )
+        Lib.check_error { |error| Lib.unumf_formatDecimal(@f, decimal, decimal.bytesize, result, error) }
+        Lib::Util.read_uchar_buffer(0) do |buffer, error|
+          Lib.unumf_resultToString(result, buffer, buffer.length_in_uchars, error)
+        end
+      end
+    end
   end
 end

data/lib/ffi-icu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ICU
-  VERSION = '0.7.0'
+  VERSION = '0.8.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ffi-icu
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Erick Guan