human_number 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3464be66cdbc375a6612c468bc7aeffdff928b8bc1af7857d2f261440f4a3f7f
-  data.tar.gz: 6ddf79c2ddd6cf5595b70a798cb035b730a7c5c6ba7c7e5d2dff726993d934c4
+  metadata.gz: 7ab664232472a72c0114441a528ec9e72b1287d2cb0123d993b24324aeaa4f6f
+  data.tar.gz: '080aabbc217c4fc67ca01d4d9aa99791d8826e96bb83c2adb418ac09d7d6e27f'
 SHA512:
-  metadata.gz: 178108029dc2a438d5a19dc5f66c9b2850d6dd593072c8ceade307549d58749cb809d73094306cd64b8bcfe870bfc3823a0c945d1454c8cc2aef4c703f2a34cd
-  data.tar.gz: c562f9d5ea7abe1bff8b31b6889a5df768f755a62490e7ea2aa6bbaef312e08feb2e29ffc1aa61f9f01f2f35ca452104d5e46dc1ccd7487c12c439196f59f10b
+  metadata.gz: d1ad60597131895ef985c4f513d9f14842fa05b64310e947631dd1f34bdf5eb9c823cce3643534ffb06aa7c93015eec7118a5569c03d76263040c1127274d825
+  data.tar.gz: e12a574d465e336e25e95151dd007afe9a2065f8fec9652f7a59824fe1094120b75f5c8f715ae2d4948587037fbf5b162a6897cbec0753e6f6848879770133dc

data/lib/human_number/formatters/number.rb

@@ -34,7 +34,7 @@ module HumanNumber
         #
         # @api private
         def format(number, locale:, abbr_units:, max_digits:, min_unit:, trim_zeros:)
-          locale = locale.to_sym
+          locale = (locale || I18n.locale).to_sym
 
           # Direct delegation to appropriate system class
           system_class = determine_system_class(locale)
@@ -48,6 +48,28 @@ module HumanNumber
           )
         end
 
+        # Formats a number using Rails' currency precision rules for the given currency.
+        # This ensures consistent precision regardless of display locale.
+        #
+        # @param number [Numeric] The number to format
+        # @param currency_code [String] ISO 4217 currency code
+        # @param locale [Symbol] Display locale (for context)
+        # @param options [Hash] Additional formatting options passed to number_to_currency
+        # @return [String] Formatted number with currency-appropriate precision
+        def format_with_currency_precision(number, currency_code:, locale:, **options)
+          locale = (locale || I18n.locale).to_sym
+
+          # Use currency's native locale for precision rules unless overridden
+          precision_locale = LocaleSupport.currency_precision_locale(currency_code, locale)
+
+          # Prepare options for number_to_currency
+          currency_options = options.dup
+          currency_options[:locale] = precision_locale
+          currency_options[:format] = "%n" # Always format as just the number (no currency symbol)
+
+          number_to_currency(number, **currency_options) || ZERO_STRING
+        end
+
         # Default options for human number formatting
         def default_options
           {
@@ -68,24 +90,6 @@ module HumanNumber
           }.freeze
         end
 
-        # Formats a number using Rails' currency precision rules for the given currency.
-        # This ensures consistent precision regardless of display locale.
-        #
-        # @param number [Numeric] The number to format
-        # @param currency_code [String] ISO 4217 currency code
-        # @param locale [Symbol] Display locale (for context)
-        # @return [String] Formatted number with currency-appropriate precision
-        def format_with_currency_precision(number, currency_code:, locale:)
-          locale = locale.to_sym
-
-          # Use currency's native locale for precision rules
-          precision_locale = LocaleSupport.currency_precision_locale(currency_code, locale)
-
-          I18n.with_locale(precision_locale) do
-            number_to_currency(number, format: "%n", locale: precision_locale)
-          end
-        end
-
         private
 
         def determine_system_class(locale)

data/lib/human_number/rails/helpers.rb

@@ -7,75 +7,49 @@ module HumanNumber
     # These helpers provide convenient access to HumanNumber functionality
     # within Rails views and controllers with Rails-friendly parameter handling.
     module Helpers
-      # Formats a number with intelligent, locale-aware abbreviations.
-      #
-      # This is a Rails helper wrapper around HumanNumber.human_number that provides
-      # Rails-friendly parameter handling with optional locale detection.
+      # Rails helper for formatting numbers with intelligent abbreviations.
       #
       # @param number [Numeric] The number to format
       # @param locale [Symbol, String, nil] The locale for formatting (default: current I18n locale)
       # @param options [Hash] Additional formatting options
-      # @option options [Boolean] :abbr_units (true) Use abbreviated unit symbols
-      # @option options [Integer, nil] :max_digits (1) Maximum significant digits
-      # @option options [Integer, nil] :min_unit (nil) Minimum unit threshold
-      # @option options [Boolean] :trim_zeros (true) Remove trailing decimal zeros
-      #
-      # @return [String] The formatted number string
       #
       # @example Basic usage in views
-      #   <%= human_number(1234567) %>                    #=> "1.2M"
-      #   <%= human_number(50000, locale: :ko) %>         #=> "5만"
-      #   <%= human_number(1234567, max_digits: 2) %>     #=> "1.23M"
+      #   <%= human_number(1234567) %>            #=> "1.2M"
+      #   <%= human_number(50000, locale: :ko) %> #=> "5만"
       #
-      # @see HumanNumber.human_number Main implementation
+      # @see HumanNumber.human_number For detailed documentation and all available options
       def human_number(number, locale: I18n.locale, **options)
         HumanNumber.human_number(number, locale:, **options)
       end
 
-      # Formats a currency amount using standard Rails currency formatting.
-      #
-      # This helper provides Rails-friendly parameter handling for currency formatting
-      # with automatic locale detection and parameter normalization.
+      # Rails helper for formatting currency amounts with standard precision.
       #
       # @param number [Numeric] The amount to format
       # @param currency_code [String] ISO 4217 currency code (e.g., 'USD', 'EUR')
       # @param locale [Symbol, String, nil] Display locale (default: current I18n locale)
-      #
-      # @return [String] The formatted currency string
+      # @param options [Hash] Additional formatting options
       #
       # @example Basic usage in views
-      #   <%= currency(1234.56, currency_code: 'USD') %>           #=> "$1,234.56"
-      #   <%= currency(50000, currency_code: 'KRW', locale: :ko) %> #=> "50,000원"
-      #   <%= currency(1234.99, currency_code: 'JPY') %>           #=> "1,235円"
+      #   <%= currency(1234.56, currency_code: 'USD') %>    #=> "$1,234.56"
+      #   <%= currency(50000, currency_code: 'KRW') %>      #=> "50,000원"
       #
-      # @see HumanNumber.currency Main implementation
-      def currency(number, currency_code:, locale: I18n.locale)
-        HumanNumber.currency(number, currency_code:, locale:)
+      # @see HumanNumber.currency For detailed documentation and all available options
+      def currency(number, currency_code:, locale: I18n.locale, **options)
+        HumanNumber.currency(number, currency_code:, locale:, **options)
       end
 
-      # Formats a currency amount with intelligent, locale-aware abbreviations.
-      #
-      # This helper combines human-readable number formatting with currency symbols,
-      # providing Rails-friendly access to abbreviated currency formatting.
+      # Rails helper for formatting currency amounts with intelligent abbreviations.
       #
       # @param number [Numeric] The amount to format
       # @param currency_code [String] ISO 4217 currency code (e.g., 'USD', 'EUR')
       # @param locale [Symbol, String, nil] Locale for formatting (default: current I18n locale)
       # @param options [Hash] Additional formatting options
-      # @option options [Boolean] :abbr_units (true) Use abbreviated unit symbols
-      # @option options [Integer, nil] :max_digits (1) Maximum significant digits
-      # @option options [Integer, nil] :min_unit (nil) Minimum unit threshold
-      # @option options [Boolean] :trim_zeros (true) Remove trailing decimal zeros
-      #
-      # @return [String] The formatted currency string with abbreviations
       #
       # @example Basic usage in views
-      #   <%= human_currency(1234567, currency_code: 'USD') %>                    #=> "$1.2M"
-      #   <%= human_currency(50000, currency_code: 'KRW', locale: :ko) %>         #=> "5만원"
-      #   <%= human_currency(1234567, currency_code: 'USD', max_digits: 2) %>     #=> "$1.23M"
-      #   <%= human_currency(1000000, currency_code: 'USD', abbr_units: false) %> #=> "$1 million"
+      #   <%= human_currency(1234567, currency_code: 'USD') %>      #=> "$1.2M"
+      #   <%= human_currency(50000, currency_code: 'KRW') %>        #=> "5만원"
       #
-      # @see HumanNumber.human_currency Main implementation
+      # @see HumanNumber.human_currency For detailed documentation and all available options
       def human_currency(number, currency_code:, locale: I18n.locale, **options)
         HumanNumber.human_currency(number, currency_code:, locale:, **options)
       end

data/lib/human_number/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HumanNumber
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/human_number.rb

@@ -66,7 +66,6 @@ module HumanNumber
     #
     # @note Complete mode (max_digits: nil) shows full precision across multiple units
     # @see Formatters::Number.format The underlying formatter implementation
-    # @since 1.0.0
     def human_number(number, locale: I18n.locale, **options)
       validate_number_input!(number)
       validate_locale!(locale)
@@ -76,23 +75,41 @@ module HumanNumber
       Formatters::Number.format(number, locale:, **final_options)
     end
 
-    # Formats a currency amount using standard Rails currency formatting.
+    # Formats a currency amount with standard precision and symbol placement.
     #
-    # This method applies currency-specific precision rules (e.g., 2 decimals for USD,
-    # 0 decimals for JPY/KRW) based on the currency's native locale, ensuring
-    # consistent precision regardless of the display locale.
+    # This method provides currency formatting with automatic precision rules based on
+    # international standards, ensuring consistent display across different locales:
+    # - **Currency-specific precision**: 2 decimals for USD/EUR, 0 for JPY/KRW
+    # - **Native locale rules**: Precision determined by currency's origin locale
+    # - **Cross-locale consistency**: USD shows 2 decimals regardless of display locale
+    # - **Symbol placement**: Follows locale-specific conventions ($1,234 vs 1,234원)
     #
     # @param number [Numeric] The amount to format
     # @param currency_code [String] ISO 4217 currency code (e.g., 'USD', 'EUR', 'KRW', 'JPY')
-    # @param locale [Symbol, String] Display locale for formatting rules
+    # @param locale [Symbol, String] Display locale for formatting rules (default: current I18n locale)
+    #   Determines delimiter, separator, and symbol placement conventions
+    #
+    # @option options [Integer] :precision Decimal precision level. Overrides currency-specific precision
+    # @option options [Symbol] :round_mode Rounding mode (see BigDecimal.mode). Defaults to :default
+    # @option options [String] :separator Decimal separator. Defaults to locale-specific separator
+    # @option options [String] :delimiter Thousands delimiter. Defaults to locale-specific delimiter
+    # @option options [Boolean] :strip_insignificant_zeros (false) Remove trailing decimal zeros
+    #
+    # @note Only numeric formatting options are supported. Currency symbols and formats are
+    #   automatically determined by ISO 4217 standards and locale conventions.
     #
     # @return [String] The formatted currency string
     #
-    # @example Standard currency formatting
+    # @example Basic currency formatting
     #   HumanNumber.currency(1234.56, currency_code: 'USD', locale: :en) #=> "$1,234.56"
     #   HumanNumber.currency(50000, currency_code: 'KRW', locale: :ko)   #=> "50,000원"
     #   HumanNumber.currency(1234.99, currency_code: 'JPY', locale: :ja) #=> "1,235円"
     #
+    # @example Custom precision and formatting
+    #   HumanNumber.currency(1234.56, currency_code: 'USD', precision: 1)                    #=> "$1,234.6"
+    #   HumanNumber.currency(1234.56, currency_code: 'USD', delimiter: " ")                  #=> "$1 234.56"
+    #   HumanNumber.currency(1234.50, currency_code: 'USD', strip_insignificant_zeros: true) #=> "$1,234.5"
+    #
     # @example Cross-locale precision consistency
     #   # USD always shows 2 decimals regardless of display locale
     #   HumanNumber.currency(1234.56, currency_code: 'USD', locale: :ko) #=> "$1,234.56"
@@ -100,16 +117,20 @@ module HumanNumber
     #   # JPY always shows 0 decimals regardless of display locale
     #   HumanNumber.currency(1234.56, currency_code: 'JPY', locale: :en) #=> "1,235円"
     #
-    # @note Precision is determined by currency's native locale, not display locale
+    # @example Edge cases
+    #   HumanNumber.currency(0, currency_code: 'USD')      #=> "$0.00"
+    #   HumanNumber.currency(-1234.56, currency_code: 'USD') #=> "-$1,234.56"
+    #
+    # @note Precision is determined by currency's native locale unless overridden via :precision option
+    # @see #human_currency For currency formatting with intelligent abbreviations (K/M/B)
     # @see Formatters::Number.format_with_currency_precision Currency precision logic
     # @see Formatters::Currency.format Currency symbol and format application
-    # @since 1.0.0
-    def currency(number, currency_code:, locale: I18n.locale)
+    def currency(number, currency_code:, locale: I18n.locale, **options)
       validate_number_input!(number)
       validate_currency_code!(currency_code)
       validate_locale!(locale)
 
-      formatted_number = Formatters::Number.format_with_currency_precision(number, currency_code:, locale:)
+      formatted_number = Formatters::Number.format_with_currency_precision(number, currency_code:, locale:, **options)
       Formatters::Currency.format(formatted_number, currency_code:, locale:)
     end
 
@@ -153,7 +174,6 @@ module HumanNumber
     # @note Combines human number formatting with currency-specific symbol placement
     # @see #human_number For detailed number formatting options
     # @see #currency For standard currency formatting without abbreviations
-    # @since 1.0.0
     def human_currency(number, currency_code:, locale: I18n.locale, **options)
       validate_number_input!(number)
       validate_currency_code!(currency_code)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: human_number
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Your Name