accept_language 2.1.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1d4f90fc40c062ac4f250c1c3b8ac8540796b232cf63b7d5c25b5e2e3c9124e
-  data.tar.gz: 150bb9def9e5f4799c432df6d6c364fedf88132b117d28e79a6ed44f467dcc70
+  metadata.gz: a993b9e4d4792701b09a650afb27011ff9a94ba104362a8c542d01ee389ca5e9
+  data.tar.gz: 129990017c1827e87e95847d8f8f42fb8c85b2d5b8146da5e6aeecb6ac7853ea
 SHA512:
-  metadata.gz: 537d924a23dc3c0fe8fb523556a6da653e16471b6b8ca94e0ee57f36fa1d6842103e380c3ea1e2dbd468b06a65a698ecdbf8923235f4eac0031a52801ba446f8
-  data.tar.gz: 8e48f57d2f0a4005483d29cf5503accc39eecffe19f78e8848dfa216422d1b2792f50cc5199c938674a483ef90ca20127fbfe452c0eebae9e30b36d7b8dc0bc2
+  metadata.gz: 2cf1e95c98cf16c78b33f7db1e666ce834f62d436a1fc84ffee28df36dfbe41a1595710cc539e7cdbc63431c13d51b55065fdcf037a01114cc639451de33498d
+  data.tar.gz: 63c161793225af35b1c5f73364dee830ba1429a2cc02e431c3422da2cf9e60edb76b9f601535f9cdb3afb982ff9d28b5f3c148a2fc8bad8320deba65115b1d23

data/README.md

@@ -1,6 +1,6 @@
 # AcceptLanguage
 
-A lightweight, thread-safe Ruby library for parsing `Accept-Language` HTTP headers as defined in [RFC 2616](https://tools.ietf.org/html/rfc2616#section-14.4), with full support for [BCP 47](https://tools.ietf.org/html/bcp47) language tags.
+A lightweight, thread-safe Ruby library for parsing the `Accept-Language` HTTP header as defined in [RFC 2616](https://tools.ietf.org/html/rfc2616#section-14.4), with full support for [BCP 47](https://tools.ietf.org/html/bcp47) language tags.
 
 [![Version](https://img.shields.io/github/v/tag/cyril/accept_language.rb?label=Version&logo=github)](https://github.com/cyril/accept_language.rb/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/cyril/accept_language.rb/main)
@@ -8,14 +8,6 @@ A lightweight, thread-safe Ruby library for parsing `Accept-Language` HTTP heade
 ![RuboCop](https://github.com/cyril/accept_language.rb/actions/workflows/rubocop.yml/badge.svg?branch=main)
 [![License](https://img.shields.io/github/license/cyril/accept_language.rb?label=License&logo=github)](https://github.com/cyril/accept_language.rb/raw/main/LICENSE.md)
 
-## Features
-
-- Thread-safe
-- No framework dependencies
-- Case-insensitive matching
-- BCP 47 language tag support
-- Wildcard and exclusion handling
-
 ## Installation
 
 ```ruby
@@ -25,69 +17,145 @@ gem "accept_language"
 ## Usage
 
 ```ruby
-AcceptLanguage.parse("en-GB, en;q=0.9").match(:en, :"en-GB")
-# => :"en-GB"
+AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7").match(:en, :da)
+# => :da
 ```
 
+## Behavior
+
 ### Quality values
 
-Quality values (q-values) indicate preference order from 0 to 1:
+Quality values (q-values) express relative preference, ranging from `0` (unacceptable) to `1` (most preferred). When omitted, the default is `1`.
 
 ```ruby
 parser = AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7")
 
-parser.match(:en, :da)      # => :da
-parser.match(:en, :"en-GB") # => :"en-GB"
-parser.match(:fr)           # => nil
+parser.match(:en, :da)      # => :da  (q=1 > q=0.8)
+parser.match(:en, :"en-GB") # => :"en-GB"  (q=0.8 > q=0.7)
+parser.match(:ja)           # => nil  (no match)
+```
+
+Per RFC 2616 Section 3.9, valid q-values have at most three decimal places: `0`, `0.7`, `0.85`, `1.000`. Invalid q-values are ignored.
+
+### Identical quality values
+
+When multiple languages share the same q-value, the order of declaration in the header determines priority—the first declared language is preferred:
+
+```ruby
+AcceptLanguage.parse("en;q=0.8, fr;q=0.8").match(:en, :fr)
+# => :en  (declared first)
+
+AcceptLanguage.parse("fr;q=0.8, en;q=0.8").match(:en, :fr)
+# => :fr  (declared first)
 ```
 
-### Language variants
+### Prefix matching
 
-A generic language tag matches its regional variants, but not the reverse:
+Per RFC 2616 Section 14.4, a language-range matches any language-tag that exactly equals the range or begins with the range followed by `-`:
 
 ```ruby
-AcceptLanguage.parse("fr").match(:"fr-CH")    # => :"fr-CH"
-AcceptLanguage.parse("fr-CH").match(:fr)      # => nil
+AcceptLanguage.parse("zh").match(:"zh-TW")
+# => :"zh-TW"  ("zh" matches "zh-TW")
+
+AcceptLanguage.parse("zh-TW").match(:zh)
+# => nil  ("zh-TW" does not match "zh")
+```
+
+Note that prefix matching follows hyphen boundaries—`zh` does not match `zhx`:
+
+```ruby
+AcceptLanguage.parse("zh").match(:zhx)
+# => nil  ("zhx" is a different language code)
 ```
 
-### Wildcards and exclusions
+### Wildcards
 
-The wildcard `*` matches any language. A q-value of 0 explicitly excludes a language:
+The wildcard `*` matches any language not matched by another range:
 
 ```ruby
-AcceptLanguage.parse("de-DE, *;q=0.5").match(:fr)  # => :fr
-AcceptLanguage.parse("*, en;q=0").match(:en)       # => nil
-AcceptLanguage.parse("*, en;q=0").match(:fr)       # => :fr
+AcceptLanguage.parse("de, *;q=0.5").match(:ja)
+# => :ja  (matched by wildcard)
+
+AcceptLanguage.parse("de, *;q=0.5").match(:de, :ja)
+# => :de  (explicit match preferred over wildcard)
 ```
 
-### Case sensitivity
+### Exclusions
 
-Matching is case-insensitive but preserves the case of the available language tag:
+A q-value of `0` explicitly excludes a language:
 
 ```ruby
-AcceptLanguage.parse("en-GB").match("en-gb") # => "en-gb"
-AcceptLanguage.parse("en-gb").match("en-GB") # => "en-GB"
+AcceptLanguage.parse("*, en;q=0").match(:en)
+# => nil  (English excluded)
+
+AcceptLanguage.parse("*, en;q=0").match(:ja)
+# => :ja  (matched by wildcard)
 ```
 
-### BCP 47 support
+Exclusions apply to prefix matches:
+
+```ruby
+AcceptLanguage.parse("*, en;q=0").match(:"en-GB")
+# => nil  (en-GB excluded via "en" prefix)
+```
 
-This library supports [BCP 47](https://tools.ietf.org/html/bcp47) language tags, including:
+### Case insensitivity
 
-- **Script subtags**: `zh-Hans` (Simplified Chinese), `zh-Hant` (Traditional Chinese)
-- **Region subtags**: `en-US`, `pt-BR`
-- **Variant subtags**: `sl-nedis` (Slovenian Nadiza dialect), `de-1996` (German orthography reform)
+Matching is case-insensitive per RFC 2616, but the original case of available language tags is preserved:
 
 ```ruby
-# Script variants
-AcceptLanguage.parse("zh-Hans").match(:"zh-Hans-CN", :"zh-Hant-TW")
-# => :"zh-Hans-CN"
+AcceptLanguage.parse("EN-GB").match(:"en-gb")
+# => :"en-gb"
 
-# Orthography variants (numeric subtags)
+AcceptLanguage.parse("en-gb").match(:"EN-GB")
+# => :"EN-GB"
+```
+
+### BCP 47 language tags
+
+Full support for [BCP 47](https://tools.ietf.org/html/bcp47) language tags:
+
+```ruby
+# Script subtags
+AcceptLanguage.parse("zh-Hant").match(:"zh-Hant-TW", :"zh-Hans-CN")
+# => :"zh-Hant-TW"
+
+# Variant subtags
 AcceptLanguage.parse("de-1996, de;q=0.9").match(:"de-CH-1996", :"de-CH")
 # => :"de-CH-1996"
 ```
 
-## Rails integration
+## Integration examples
+
+### Rack
+
+```ruby
+# config.ru
+class LocaleMiddleware
+  def initialize(app, available_locales:, default_locale:)
+    @app = app
+    @available_locales = available_locales
+    @default_locale = default_locale
+  end
+
+  def call(env)
+    locale = detect_locale(env) || @default_locale
+    env["rack.locale"] = locale
+    @app.call(env)
+  end
+
+  private
+
+  def detect_locale(env)
+    header = env["HTTP_ACCEPT_LANGUAGE"]
+    return unless header
+
+    AcceptLanguage.parse(header).match(*@available_locales)
+  end
+end
+```
+
+### Ruby on Rails
 
 ```ruby
 # app/controllers/application_controller.rb
@@ -118,13 +186,15 @@ end
 
 ## Documentation
 
-- [API Documentation](https://rubydoc.info/github/cyril/accept_language.rb/main)
+- [API documentation](https://rubydoc.info/github/cyril/accept_language.rb/main)
+- [RFC 2616 Section 14.4](https://tools.ietf.org/html/rfc2616#section-14.4)
+- [BCP 47](https://tools.ietf.org/html/bcp47)
 - [Language negotiation with Ruby](https://dev.to/cyri_/language-negotiation-with-ruby-5166)
 - [Rubyで言語ネゴシエーション](https://qiita.com/cyril/items/45dc233edb7be9d614e7)
 
 ## Versioning
 
-This library follows [Semantic Versioning 2.0.0](https://semver.org/).
+This library follows [Semantic Versioning 2.0](https://semver.org/).
 
 ## License
 

data/lib/accept_language/matcher.rb

@@ -1,61 +1,280 @@
 # frozen_string_literal: true
 
 module AcceptLanguage
-  # Matches Accept-Language header values against application-supported languages to determine
-  # the optimal language choice. Handles quality values, wildcards, and language tag matching
-  # according to RFC 2616 specifications.
+  # = Language Preference Matcher
+  #
+  # Matcher implements the language matching algorithm defined in RFC 2616
+  # Section 14.4. It takes parsed language preferences (from {Parser}) and
+  # determines the optimal language choice from a set of available languages.
+  #
+  # == Overview
+  #
+  # The matching process balances multiple factors:
+  #
+  # 1. **Quality values**: Higher q-values indicate stronger user preference
+  # 2. **Declaration order**: Tie-breaker when q-values are equal
+  # 3. **Prefix matching**: Allows +en+ to match +en-US+, +en-GB+, etc.
+  # 4. **Wildcards**: The +*+ range matches any otherwise unmatched language
+  # 5. **Exclusions**: Languages with +q=0+ are explicitly unacceptable
+  #
+  # == RFC 2616 Section 14.4 Compliance
+  #
+  # This implementation follows the Accept-Language matching rules:
+  #
+  # > A language-range matches a language-tag if it exactly equals the tag,
+  # > or if it exactly equals a prefix of the tag such that the first tag
+  # > character following the prefix is "-".
+  #
+  # This means:
+  # - +en+ matches +en+, +en-US+, +en-GB+, +en-Latn-US+
+  # - +en-US+ matches only +en-US+ (not +en+ or +en-GB+)
+  # - +en+ does NOT match +eng+ (no hyphen boundary)
+  #
+  # == Quality Value Semantics
+  #
+  # Quality values have specific meanings per RFC 2616:
+  #
+  # - +q=1+ (or omitted): Most preferred
+  # - +0 < q < 1+: Acceptable with relative preference
+  # - +q=0+: Explicitly NOT acceptable
+  #
+  # The +q=0+ case is special: it doesn't just indicate low preference, it
+  # completely excludes the language from consideration. This is used with
+  # wildcards to express "any language except X":
+  #
+  #   Accept-Language: *, en;q=0
+  #
+  # == Wildcard Behavior
+  #
+  # The wildcard +*+ matches any language not explicitly matched by another
+  # language-range. When processing a wildcard:
+  #
+  # 1. Collect all explicitly listed language tags (excluding the wildcard)
+  # 2. Find available languages that don't match any explicit tag
+  # 3. Return the first such language
+  #
+  # This ensures explicit preferences always take priority over the wildcard.
+  #
+  # == Internal Design
+  #
+  # The Matcher separates languages into two categories during initialization:
+  #
+  # - **preferred_langtags**: Languages with q > 0, sorted by descending quality
+  # - **excluded_langtags**: Languages with q = 0 (explicitly unacceptable)
+  #
+  # This separation optimizes the matching algorithm by allowing quick
+  # filtering of excluded languages before attempting matches.
+  #
+  # == Thread Safety
+  #
+  # Matcher instances are immutable after initialization. Both +preferred_langtags+
+  # and +excluded_langtags+ are frozen, making instances safe for concurrent use.
   #
   # @api private
-  # @note This class is intended for internal use by {Parser} and should not be instantiated directly.
+  # @note This class is used internally by {Parser#match} and should not be
+  #   instantiated directly. Use {AcceptLanguage.parse} followed by
+  #   {Parser#match} instead.
+  #
+  # @example Internal usage (via Parser)
+  #   # Don't do this:
+  #   matcher = AcceptLanguage::Matcher.new("en" => 1000, "fr" => 800)
+  #
+  #   # Do this instead:
+  #   AcceptLanguage.parse("en, fr;q=0.8").match(:en, :fr)
+  #
+  # @see Parser#match
+  # @see https://tools.ietf.org/html/rfc2616#section-14.4 RFC 2616 Section 14.4
   class Matcher
+    # The hyphen character used as a subtag delimiter in BCP 47 language tags.
+    #
+    # Per RFC 2616 Section 14.4, prefix matching must respect hyphen boundaries.
+    # A language-range matches a language-tag only if the character immediately
+    # following the prefix is a hyphen.
+    #
     # @api private
+    # @return [String] "-"
+    HYPHEN = "-"
+
+    # Error message raised when an available language tag is not a Symbol.
+    #
+    # This guards against accidental non-Symbol values in the available languages
+    # array, which would cause unexpected behavior during matching.
+    #
+    # @api private
+    # @return [String]
+    LANGTAG_TYPE_ERROR = "Language tag must be a Symbol"
+
+    # The wildcard character that matches any language not explicitly listed.
+    #
+    # Per RFC 2616 Section 14.4, the wildcard has special semantics:
+    # - It matches any language not matched by other ranges
+    # - +*;q=0+ makes all unlisted languages unacceptable
+    # - It has lower effective priority than explicit language tags
+    #
+    # @api private
+    # @return [String] "*"
     WILDCARD = "*"
 
+    # Language tags explicitly marked as unacceptable (+q=0+).
+    #
+    # These tags are filtered out from available languages before any
+    # matching occurs. Exclusions apply via prefix matching, so excluding
+    # +en+ also excludes +en-US+, +en-GB+, etc.
+    #
+    # @note The wildcard +*+ is never added to this set, even when +*;q=0+
+    #   is specified. Wildcard exclusion is handled implicitly: when +*;q=0+
+    #   and no other languages have +q > 0+, the preferred_langtags list is
+    #   empty, resulting in no matches.
+    #
+    # @api private
+    # @return [Set<String>] downcased language tags with q=0
+    #
+    # @example
+    #   # For "*, en;q=0, de;q=0"
+    #   matcher.excluded_langtags
+    #   # => #<Set: {"en", "de"}>
+    attr_reader :excluded_langtags
+
+    # Language tags sorted by preference (descending quality value).
+    #
+    # This array contains only tags with +q > 0+, ordered from most preferred
+    # to least preferred. When quality values are equal, the original
+    # declaration order from the Accept-Language header is preserved.
+    #
+    # The stable sort guarantee ensures deterministic matching: given the
+    # same header and available languages, the result is always the same.
+    #
     # @api private
-    attr_reader :excluded_langtags, :preferred_langtags
+    # @return [Array<String>] downcased language tags, highest quality first
+    #
+    # @example
+    #   # For "fr;q=0.8, en, de;q=0.9"
+    #   # Sorted: en (q=1), de (q=0.9), fr (q=0.8)
+    #   matcher.preferred_langtags
+    #   # => ["en", "de", "fr"]
+    attr_reader :preferred_langtags
 
+    # Creates a new Matcher instance from parsed language preferences.
+    #
+    # The initialization process:
+    #
+    # 1. Separates excluded tags (+q=0+) from preferred tags (+q > 0+)
+    # 2. Sorts preferred tags by descending quality value
+    # 3. Preserves original order for tags with equal quality (stable sort)
+    #
+    # == Exclusion Rules
+    #
+    # Only specific language tags with +q=0+ are added to the exclusion set.
+    # The wildcard +*+ is explicitly NOT added even when +*;q=0+ is present,
+    # because:
+    #
+    # - Adding +*+ to exclusions would break prefix matching logic
+    # - +*;q=0+ semantics are: "no unlisted language is acceptable"
+    # - This is achieved by having an empty preferred_langtags (no wildcards)
+    #
+    # == Stable Sorting
+    #
+    # Ruby's +sort_by+ is stable since Ruby 2.0, meaning elements with equal
+    # sort keys maintain their relative order. This ensures that when multiple
+    # languages have the same quality value, the first one declared in the
+    # Accept-Language header wins.
+    #
     # @api private
+    # @param languages_range [Hash{String => Integer}] language tags mapped to
+    #   quality values (0-1000), as produced by {Parser}
+    #
+    # @example
+    #   Matcher.new("en" => 1000, "fr" => 800, "de" => 0)
+    #   # preferred_langtags: ["en", "fr"]
+    #   # excluded_langtags: #<Set: {"de"}>
     def initialize(**languages_range)
       @excluded_langtags = ::Set[]
-      langtags = []
-
-      languages_range.select do |langtag, quality|
-        if quality.zero?
-          # Exclude specific language tags, but NOT the wildcard.
-          # When "*;q=0" is specified, all non-listed languages become
-          # unacceptable implicitly (they won't match any preferred_langtags).
-          # Adding "*" to excluded_langtags would break prefix_match? logic.
-          @excluded_langtags << langtag unless wildcard?(langtag)
-        else
-          level = (quality * 1_000).to_i
-          langtags[level] = langtag
-        end
+
+      languages_range.each do |langtag, quality|
+        next unless quality.zero? && !wildcard?(langtag)
+
+        # Exclude specific language tags, but NOT the wildcard.
+        # When "*;q=0" is specified, all non-listed languages become
+        # unacceptable implicitly (they won't match any preferred_langtags).
+        # Adding "*" to excluded_langtags would break prefix_match? logic.
+        @excluded_langtags << langtag
       end
 
-      @preferred_langtags = langtags.compact.reverse
+      # Sort by descending quality. Ruby's sort_by is stable, so languages
+      # with identical quality values preserve their original order from
+      # the Accept-Language header (first declared = higher priority).
+      @preferred_langtags = languages_range
+                            .reject { |_, quality| quality.zero? }
+                            .sort_by { |_, quality| -quality }
+                            .map(&:first)
     end
 
+    # Finds the best matching language from the available options.
+    #
+    # == Algorithm
+    #
+    # 1. **Filter**: Remove available languages that match any excluded tag
+    # 2. **Match**: For each preferred tag (in quality order):
+    #    - If it's a wildcard, return the first available language not
+    #      matching any other preferred tag
+    #    - Otherwise, return the first available language that matches
+    #      via exact match or prefix match
+    # 3. **Result**: Return the first match found, or +nil+ if none
+    #
+    # == Return Value
+    #
+    # The returned value preserves the exact form (case) of the matched
+    # element from +available_langtags+. This is important for direct use
+    # with APIs like +I18n.locale=+ that may be case-sensitive.
+    #
     # @api private
+    # @param available_langtags [Array<Symbol>] languages to match against
+    # @return [Symbol, nil] the best matching language, or +nil+
+    # @raise [TypeError] if any available language tag is not a Symbol
+    #
+    # @example Basic matching
+    #   matcher = Matcher.new("en" => 1000, "fr" => 800)
+    #   matcher.call(:en, :fr, :de)
+    #   # => :en
+    #
+    # @example Prefix matching
+    #   matcher = Matcher.new("en" => 1000)
+    #   matcher.call(:"en-US", :"en-GB")
+    #   # => :"en-US"
+    #
+    # @example With exclusion
+    #   matcher = Matcher.new("*" => 500, "en" => 0)
+    #   matcher.call(:en, :fr)
+    #   # => :fr
     def call(*available_langtags)
-      raise ::ArgumentError, "Language tags cannot be nil" if available_langtags.any?(&:nil?)
-
       filtered_tags = drop_unacceptable(*available_langtags)
-      return nil if filtered_tags.empty?
+      return if filtered_tags.empty?
 
       find_best_match(filtered_tags)
     end
 
     private
 
+    # Iterates through preferred languages to find the first match.
+    #
+    # @param available_langtags [Set<String>] pre-filtered available tags
+    # @return [Symbol, nil] the matched tag or nil
     def find_best_match(available_langtags)
       preferred_langtags.each do |preferred_tag|
         match = match_langtag(preferred_tag, available_langtags)
-        return match if match
+        return :"#{match}" unless match.nil?
       end
 
       nil
     end
 
+    # Attempts to match a single preferred tag against available languages.
+    #
+    # Handles both wildcard and specific language tags differently.
+    #
+    # @param preferred_tag [String] the preferred language tag to match
+    # @param available_langtags [Set<String>] available tags to search
+    # @return [String, nil] the matched tag or nil
     def match_langtag(preferred_tag, available_langtags)
       if wildcard?(preferred_tag)
         any_other_langtag(*available_langtags)
@@ -64,44 +283,105 @@ module AcceptLanguage
       end
     end
 
+    # Finds an available language that matches via exact or prefix match.
+    #
+    # @param preferred_tag [String] the preferred tag (downcased)
+    # @param available_langtags [Set<String>] available tags
+    # @return [String, nil] the first matching tag or nil
     def find_matching_tag(preferred_tag, available_langtags)
-      available_langtags.find { |tag| prefix_match?(preferred_tag, String(tag.downcase)) }
+      available_langtags.find { |tag| prefix_match?(preferred_tag, tag) }
     end
 
+    # Finds an available language for wildcard matching.
+    #
+    # Returns the first available language that doesn't match any explicitly
+    # listed preferred language tag. This implements the RFC 2616 semantics
+    # where +*+ matches "any language not matched by another range".
+    #
+    # @param available_langtags [Array<String>] available tags
+    # @return [String, nil] the first non-matching tag or nil
     def any_other_langtag(*available_langtags)
       langtags = preferred_langtags - [WILDCARD]
 
       available_langtags.find do |available_langtag|
-        available_downcased = available_langtag.downcase
-        langtags.none? { |tag| prefix_match?(tag, String(available_downcased)) }
+        langtags.none? { |tag| prefix_match?(tag, available_langtag) }
       end
     end
 
+    # Removes explicitly excluded languages from the available set.
+    #
+    # Uses prefix matching for exclusions, so excluding +en+ also excludes
+    # +en-US+, +en-GB+, etc.
+    #
+    # @param available_langtags [Array<Symbol>] all available tags
+    # @return [Set<String>] tags not matching any exclusion
+    # @raise [TypeError] if any tag is not a Symbol
     def drop_unacceptable(*available_langtags)
       available_langtags.each_with_object(::Set[]) do |available_langtag, langtags|
+        raise ::TypeError, LANGTAG_TYPE_ERROR unless available_langtag.is_a?(::Symbol)
+
+        available_langtag = "#{available_langtag}"
         langtags << available_langtag unless unacceptable?(available_langtag)
       end
     end
 
+    # Checks if a language tag is explicitly excluded.
+    #
+    # @param langtag [String] the tag to check (as string)
+    # @return [Boolean] true if the tag matches any exclusion
     def unacceptable?(langtag)
-      langtag_downcased = langtag.downcase
-      excluded_langtags.any? { |excluded_tag| prefix_match?(excluded_tag, String(langtag_downcased)) }
+      excluded_langtags.any? { |excluded_tag| prefix_match?(excluded_tag, langtag) }
     end
 
+    # Checks if a value is the wildcard character.
+    #
+    # @param value [String] the value to check
+    # @return [Boolean] true if the value is "*"
     def wildcard?(value)
       value.eql?(WILDCARD)
     end
 
-    # Implements RFC 2616 Section 14.4 prefix matching rule:
-    # "A language-range matches a language-tag if it exactly equals the tag,
-    # or if it exactly equals a prefix of the tag such that the first tag
-    # character following the prefix is '-'."
+    # Implements RFC 2616 Section 14.4 prefix matching rule.
+    #
+    # From the specification:
+    #
+    # > A language-range matches a language-tag if it exactly equals the tag,
+    # > or if it exactly equals a prefix of the tag such that the first tag
+    # > character following the prefix is "-".
+    #
+    # This rule ensures that language ranges match at subtag boundaries:
+    #
+    # - +en+ matches +en+ (exact)
+    # - +en+ matches +en-US+ (prefix + hyphen)
+    # - +en+ does NOT match +eng+ (no hyphen after prefix)
+    # - +en-US+ does NOT match +en+ (prefix is longer than tag)
     #
-    # @param prefix [String] The language-range to match (downcased)
-    # @param tag [String] The language-tag to test (downcased)
+    # Matching is case-insensitive per RFC 2616, using +casecmp?+ for
+    # efficient comparison without allocating new strings.
+    #
+    # @param prefix [String] the language-range to match (downcased)
+    # @param tag [String] the language-tag to test (any case)
     # @return [Boolean] true if prefix matches tag per RFC 2616 rules
+    #
+    # @example Exact matches
+    #   prefix_match?("en", "en")       # => true
+    #   prefix_match?("en", "EN")       # => true
+    #   prefix_match?("en-us", "en-US") # => true
+    #
+    # @example Prefix matches
+    #   prefix_match?("en", "en-us")    # => true
+    #   prefix_match?("en", "en-GB")    # => true
+    #   prefix_match?("zh", "zh-Hant-TW") # => true
+    #
+    # @example Non-matches
+    #   prefix_match?("en-us", "en")    # => false (prefix longer than tag)
+    #   prefix_match?("en", "eng")      # => false (no hyphen boundary)
+    #   prefix_match?("en", "fr")       # => false (different language)
     def prefix_match?(prefix, tag)
-      tag == prefix || tag.start_with?("#{prefix}-")
+      return true if tag.casecmp?(prefix)
+      return false if tag.length <= prefix.length
+
+      tag[0, prefix.length].casecmp?(prefix) && tag[prefix.length] == HYPHEN
     end
   end
 end