human_number 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b40f4d307a6d79e38dd1e45276c6df0334d28081dfb3cdddce89d943732e9aab
-  data.tar.gz: f25564f84991e593d68de48fd88b79e1ef64baaa473d962428b5008b61a25c93
+  metadata.gz: 93e874d0c4c80b94891c99059eea6c14bc1d6f9d3931c6d589559f6282b2b835
+  data.tar.gz: 4eb1a4bc258bb90a25d4ebb908c115cf2aa2ecca7878cf3faacc028d3e418432
 SHA512:
-  metadata.gz: 030e86e5855e634e6aafb8940834f58a290276a7c2096e1da12b44eb9bbd667803c1a2239822d091f69aa6fb1165c4eb4187268e0911ee6a78a407f80c1ba6c1
-  data.tar.gz: 612b2da8d6f9abbd5d06695701e5b2943879d4a8610885f717f2acfe28577fba1e082597a1dee03c07464e58e4996cf00a3c78e54b8def050cdfa1750a74395d
+  metadata.gz: 1102a52bea931b847a7886904e05497cbab49d4d770fefd9bb0d6b1d6f9538283e0b8a7e99e363a2e76b48d8af40022b56b5791d160e9943ca98df9b6fca355c
+  data.tar.gz: 5dbffd0891fc1945b8a20b2ed569671aa8836c78a1026711b667a2ab0adebb0d798ec89e8e9f1895da98dd704290a3575454fbc34359db36c1549cd7131b529d

data/CHANGELOG.md

@@ -5,111 +5,58 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2025-08-25
+
+### Added
+- `HumanNumber.number_system(locale:)` - Detects number system (`:default`, `:east_asian`, `:indian`) by locale
+- `HumanNumber.currency_number_system(currency_code:)` - Detects number system by currency code
+- New `HumanNumber::NumberSystem` module with centralized system logic
+
+### Changed
+- Moved system classes (`DefaultSystem`, `EastAsianSystem`, `IndianSystem`) to `NumberSystem` module
+- Reduced `number.rb` formatter from 475 to 93 lines (80% reduction)
+- Updated I18n test patterns to use `I18n.with_locale` for thread safety
+- Enhanced README with new API documentation and examples
+
+## [0.1.10] - 2025-08-19
+
+### Changed
+- **BREAKING CHANGE**: Changed `max_digits` default from `2` to `nil` 
+- Numbers now show complete breakdown by default (`"1M 234K 567"` instead of `"1.2M"`)
+- Previous abbreviated behavior available with explicit `max_digits: 2`
+
 ## [0.1.9] - 2025-08-05
 
 ### Changed
-- **East Asian separator formatting**: Japanese numbers now use culturally appropriate spacing
-  - Japanese: `'12億3456万7890円'` (no spaces between units)
-  - Korean/Chinese: `'12억 3456만 7890원'` (spaces maintained as default)
-- **Locale-based separator configuration**: Added `number.human.decimal_units.separator` for customizable unit separators
+- Japanese numbers use culturally appropriate spacing (no spaces between units)
+- Korean/Chinese maintain spaces between units as default
+- Added `number.human.decimal_units.separator` for customizable separators
 
 ## [0.1.8] - 2025-08-05
 
 ### Fixed
-- **I18n fallback contamination**: Resolved currency symbol cross-contamination where Korean won symbols (원) appeared for other currencies like CAD due to I18n fallback behavior
-- **Translation missing errors**: Fixed missing translation errors for various currency/locale combinations
-- **Rails configuration warnings**: Eliminated Rails configuration warnings in test environment
+- I18n fallback currency symbol contamination (Korean won symbols appearing for other currencies)
+- Missing translation errors for various currency/locale combinations
+- Rails configuration warnings in test environment
 
 ### Changed
-- **Currency native locale mappings**: Corrected CURRENCY_NATIVE_LOCALES to use only accurate locale associations (e.g., CAD now maps to en-CA/fr-CA only, not generic en/fr)
-- **Locale file organization**: Moved locale files from `config/locales/` to `lib/locales/` for better gem structure
-
-### Improved
-- **Rails-i18n integration**: Enhanced loading order and initialization to prevent locale conflicts
-- **Test infrastructure**: Updated RSpec mocks and test expectations for better reliability
-- **I18n isolation**: Added `fallback: false` parameter to prevent cross-locale pollution
+- Corrected CURRENCY_NATIVE_LOCALES mappings for accuracy
+- Moved locale files from `config/locales/` to `lib/locales/`
 
 ## [0.1.0] - 2025-07-31
 
 ### Added
-
-#### Core Number Formatting
-- **Human-readable number formatting** with intelligent, culturally-appropriate abbreviations
-- **Three cultural number systems** automatically selected by locale:
-  - **Western System**: K/M/B/T (thousand/million/billion/trillion) for English, German, French, Spanish, Italian, Portuguese, Russian, Dutch, Swedish, Danish, Norwegian
-  - **East Asian System**: 만/억/조 (Korean) and 万/億/兆 (Japanese/Chinese) for ko, ja, zh, zh-CN, zh-TW locales
-  - **Indian System**: thousand/lakh/crore for Hindi, Urdu, Bengali, and Indian English (hi, ur, bn, en-IN)
-
-#### Currency Formatting
-- **ISO 4217 currency code support** with native locale precision rules
-- **Cross-locale consistency**: USD always shows 2 decimals, JPY shows 0, regardless of display locale
-- **40+ currency mappings** with native locale associations for accurate formatting
-- **Human-readable currency formatting** combining cultural abbreviations with currency symbols
-
-#### API Methods
-- `HumanNumber.human_number(number, **options)` - Formats numbers with cultural abbreviations
-- `HumanNumber.currency(number, currency_code:, locale:)` - Standard currency formatting
-- `HumanNumber.human_currency(number, currency_code:, locale:, **options)` - Currency with abbreviations
-
-#### Formatting Options
-- **Precision control**: `max_digits` parameter for significant digit control (1-4 digits or nil for complete mode)
-- **Unit preferences**: `abbr_units` to choose between abbreviated (K/M) vs full words (thousand/million)
-- **Minimum thresholds**: `min_unit` to prevent abbreviation below specified amounts
-- **Zero trimming**: `trim_zeros` to control trailing decimal zero display
-- **Complete mode**: `max_digits: nil` shows full breakdown across multiple units (e.g., "1M 234K 567")
-
-#### Rails Integration
-- **Automatic Rails detection** and helper loading via Railtie
-- **View helpers**: `human_number`, `currency`, `human_currency` with Rails-friendly parameter handling
-- **I18n integration**: Automatic locale detection from `I18n.locale`
-
-#### Locale Data System
-- **Hybrid locale approach**: Combines rails-i18n for base formatting with custom locale files for unit symbols
-- **14 custom locale files**: bn, de, en-GB, en-IN, en, es, fr, hi, ja, ko, ur, zh-CN, zh-TW, zh
-- **Rails-i18n structure**: `number.human.decimal_units.units` for unit translations
-- **Automatic locale file loading** from `config/locales/` directory
-
-#### Architecture & Performance
-- **Configuration-free design**: No global state, explicit parameters for predictable behavior
-- **Direct class methods**: Zero object instantiation overhead for optimal performance
-- **Thread-safe implementation**: No shared mutable state between calls
-- **Two-stage formatting**: Clean separation between number formatting and currency application
-- **Efficient I18n**: Leverages Rails I18n caching mechanisms
-
-#### Standards Compliance
-- **Microsoft Globalization documentation** compliance for cultural number formatting
-- **Unicode CLDR standards** for locale-specific formatting rules
-- **ISO 4217 standard** for currency codes and precision rules
-- **rails-i18n integration** for verified locale data
-
-#### Development Infrastructure
-- **Comprehensive test suite**: 106 test examples with 100% code coverage
-- **RuboCop compliance**: Complete adherence to Ruby style guidelines
-- **Rake tasks**: Integrated testing and linting workflow
-- **Gem packaging**: Ready for RubyGems distribution
-
-#### Dependencies
-- **Runtime dependencies**: `actionview` (>= 5.2), `i18n` (>= 1.6, < 2), `rails-i18n` (>= 5.1)
-- **Ruby requirement**: >= 3.1.0
-- **Development dependencies**: `rspec`, `rubocop`, `simplecov`, `yard`
-
-### Technical Details
-
-#### Number System Architecture
-- **DefaultSystem**: Handles Western locales with standard thousand/million/billion/trillion units
-- **EastAsianSystem**: Implements East Asian counting with ten-thousand (만/万) and hundred-million (억/億) bases
-- **IndianSystem**: Supports Indian numbering with lakh (100,000) and crore (10,000,000) units
-
-#### Currency Precision System
-- **LocaleSupport module**: Centralized currency-to-locale mapping for consistent precision
-- **Native locale detection**: Automatic selection of appropriate formatting locale for each currency
-- **Precision inheritance**: Currency formatting inherits precision rules from native locales
-
-#### Formatter Pattern
-- **Formatters::Number**: Core number formatting with intelligent unit system selection
-- **Formatters::Currency**: Currency symbol and format string application
-- **Clean separation**: Number formatting independent of currency concerns
-
+- Human-readable number formatting with cultural abbreviations
+- Three number systems: Western (K/M/B/T), East Asian (만/억/조), Indian (lakh/crore)
+- ISO 4217 currency code support with native locale precision
+- API methods: `human_number`, `currency`, `human_currency`
+- Rails integration with automatic helper loading
+- Configuration-free design with explicit parameters
+- 14 custom locale files with rails-i18n integration
+- Thread-safe implementation
+
+[0.2.0]: https://github.com/ether-moon/human_number/releases/tag/v0.2.0
+[0.1.10]: https://github.com/ether-moon/human_number/releases/tag/v0.1.10
 [0.1.9]: https://github.com/ether-moon/human_number/releases/tag/v0.1.9
 [0.1.8]: https://github.com/ether-moon/human_number/releases/tag/v0.1.8
 [0.1.0]: https://github.com/ether-moon/human_number/releases/tag/v0.1.0

data/README.md

@@ -123,6 +123,76 @@ HumanNumber.human_currency(1_234_567, currency_code: 'USD', locale: :en, max_dig
 HumanNumber.human_currency(1_234_567, currency_code: 'USD', locale: :en, max_digits: nil) #=> "$1M 234K 567"
 ```
 
+### System Detection Methods
+
+#### `HumanNumber.number_system(locale:)`
+
+Determines which number system is used for a given locale. Returns a symbol indicating the cultural number formatting system.
+
+```ruby
+# Western/Default system (K/M/B/T)
+HumanNumber.number_system(locale: :en)    #=> :default
+HumanNumber.number_system(locale: :fr)    #=> :default
+HumanNumber.number_system(locale: :de)    #=> :default
+
+# East Asian system (만/억/조 or 万/億/兆)  
+HumanNumber.number_system(locale: :ko)    #=> :east_asian
+HumanNumber.number_system(locale: :ja)    #=> :east_asian
+HumanNumber.number_system(locale: :zh)    #=> :east_asian
+
+# Indian system (thousand/lakh/crore)
+HumanNumber.number_system(locale: :hi)    #=> :indian
+HumanNumber.number_system(locale: :'en-IN') #=> :indian
+
+# Defaults to current I18n.locale when not specified
+HumanNumber.number_system #=> (uses I18n.locale)
+```
+
+**Return Values:**
+- `:default` - Western system using K/M/B/T (thousand/million/billion/trillion)
+- `:east_asian` - Asian system using 만/억/조 or 万/億/兆 patterns  
+- `:indian` - South Asian system using thousand/lakh/crore
+
+#### `HumanNumber.currency_number_system(currency_code:)`
+
+Determines which number system is used for a given currency code. Returns a symbol indicating the culturally appropriate formatting system for that currency's region.
+
+```ruby
+# Default system currencies
+HumanNumber.currency_number_system(currency_code: 'USD') #=> :default
+HumanNumber.currency_number_system(currency_code: 'EUR') #=> :default
+HumanNumber.currency_number_system(currency_code: 'GBP') #=> :default
+
+# East Asian system currencies
+HumanNumber.currency_number_system(currency_code: 'KRW') #=> :east_asian  # Korean Won
+HumanNumber.currency_number_system(currency_code: 'JPY') #=> :east_asian  # Japanese Yen
+HumanNumber.currency_number_system(currency_code: 'CNY') #=> :east_asian  # Chinese Yuan
+
+# Indian system currencies
+HumanNumber.currency_number_system(currency_code: 'INR') #=> :indian      # Indian Rupee
+
+# Case-insensitive and handles whitespace
+HumanNumber.currency_number_system(currency_code: 'krw')   #=> :east_asian
+HumanNumber.currency_number_system(currency_code: ' USD ') #=> :default
+```
+
+**Practical Usage:**
+These methods are useful for understanding which formatting system will be applied, or for building custom formatting logic:
+
+```ruby
+# Check system before formatting
+system = HumanNumber.number_system(locale: :ko)
+if system == :east_asian
+  puts "Will use 만/억/조 units"
+  result = HumanNumber.human_number(50_000, locale: :ko) #=> "5만"
+end
+
+# Currency-aware system detection
+currency_system = HumanNumber.currency_number_system(currency_code: 'KRW')
+locale_system = HumanNumber.number_system(locale: :ko)
+puts "Consistent systems!" if currency_system == locale_system #=> true
+```
+
 ### Rails Integration
 
 In Rails applications, helper methods are automatically available:
@@ -300,10 +370,33 @@ $ rake  # Runs both spec and rubocop
 
 To add support for a new locale:
 
-1. Add locale to appropriate number system in `lib/human_number/formatters/number.rb`
-2. Create locale file in `config/locales/` with unit translations
-3. Add currency mapping to `CURRENCY_NATIVE_LOCALES` if applicable
-4. Add comprehensive tests
+1. Add locale to appropriate system mapping in `lib/human_number/number_system.rb`:
+   - Update `LOCALE_SYSTEM_MAPPING` to include the new locale
+   - If needed, add currency mapping to `CURRENCY_SYSTEM_MAPPING`
+2. Create locale file in `config/locales/` with unit translations following rails-i18n structure
+3. Add currency precision mapping to `CURRENCY_NATIVE_LOCALES` in `lib/human_number/locale_support.rb` if applicable  
+4. Add comprehensive tests covering the new locale in both `spec/human_number_spec.rb` and `spec/human_number/number_system_spec.rb`
+
+**Example:** Adding Portuguese (Brazil) support:
+```ruby
+# In lib/human_number/number_system.rb
+LOCALE_SYSTEM_MAPPING = {
+  east_asian: %i[ko ja zh zh-CN zh-TW].freeze,
+  indian: %i[hi ur bn en-IN].freeze,
+  # Add pt-BR to default system (no entry needed)
+}.freeze
+
+# In config/locales/pt-BR.yml  
+pt-BR:
+  number:
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "K"
+          million: "M" 
+          billion: "B"
+          trillion: "T"
+```
 
 ## License