Faster ruby-units

[smathieu]

Why

Our application makes heavy use of this excellent gem. The performance of the gem was however a bottleneck to our application.

This version is what we now run in production without known issue. This is a pretty major rewrite of the library and might now be in line with the direction you want to take this gem. If so, feel free to close this PR. I however wanted to take the time to put up a PR for this as this might be useful to others.

Summary

Major performance overhaul of ruby-units, replacing regex-based unit parsing with hash-based architecture and adding an optional C extension for hot-path acceleration. All 1173 tests pass in both C and pure Ruby (RUBY_UNITS_PURE=1) modes. Still compatible with JRuby via pure ruby mode.

Ruby-level optimizations

• Hash-based tokenizer (resolve_unit_token) replaces the 375-entry regex alternation for unit resolution
• compute_base_scalar_fast / compute_signature_fast avoid creating intermediate Unit objects during initialization
• Lazy to_base caching on the instance — computed once, then memoized
• batch_define defers regex cache invalidation during definition loading (cold start)
• eliminate_terms uses a count_units helper to avoid dup/flatten allocations
• convert_to uses unit_array_scalar for direct scalar computation without intermediate arrays
• Same-unit fast path for +/- skips base conversion when numerator/denominator match exactly
• Cache lookup uses Hash#key? (O(1)) instead of Array#include? (O(n))
• units() fast path returns cached @unit_name for default arguments

C extension (~870 lines, optional)

Accelerates finalize_initialization, eliminate_terms, and convert_to scalar math. Falls back to pure Ruby for temperature units and when the extension is unavailable (JRuby, RUBY_UNITS_PURE=1, etc.).

Key C-level techniques:

• Direct ivar access (rb_ivar_get) instead of rb_funcall for Definition properties (~300-700ns savings per call)
• Hash lookup (rb_hash_aref) instead of Ruby method dispatch for definitions
• Symbol pointer comparison for kind matching (symbols are singletons)
• Temperature detection via strncmp in C, returning false to signal Ruby fallback
• Pre-cached rb_intern IDs for all method/ivar lookups
• Single-pass hash fetching — definitions/prefix_values/unit_values fetched once and passed to all helpers

Performance vs master

Benchmarked on Ruby 4.0.1, aarch64-linux. Numbers are iterations/second (higher is better).

Unit creation (uncached — cache cleared each iteration)

Benchmark	master	this branch	Speedup
`Unit.new("1 m")`	799	33,096	41x
`Unit.new("1 km")`	343	30,056	88x
`Unit.new("1 kg*m/s^2")`	811	23,614	29x
`Unit.new("1.5e-3 mm")`	241	16,355	68x
`Unit.new("1/2 cup")`	304	8,932	29x
`Unit.new("6'4"")`	131	2,793	21x
`Unit.new("8 lbs 8 oz")`	131	3,475	27x
`Unit.new("37 degC")`	339	18,790	55x

Unit creation (cached / constructor variants)

Benchmark	master	this branch	Speedup
cached `"1 m"`	38,890	45,674	1.2x
cached `"5 kg*m/s^2"`	14,334	24,008	1.7x
`Unit.new(1)`	133,897	978,401	7.3x
`Unit.new(scalar:, numerator:, ...)`	77,574	426,421	5.5x

Unit conversions

Benchmark	master	this branch	Speedup
m → km	3,380	17,008	5.0x
km → m	10,434	14,380	1.4x
mph → m/s	11,071	13,294	1.2x
degC → degF	3,446	13,933	4.0x
`to_base` (km)	19,658	13,038,463	663x

Arithmetic

Benchmark	master	this branch	Speedup
`5m + 3m`	17,380	42,839	2.5x
`5m - 3m`	21,567	44,034	2.0x
`5m * 2kg`	20,362	39,689	1.9x
`5m / 10s`	15,601	32,742	2.1x
`(5m) ** 2`	17,065	27,977	1.6x
`5m * 3`	22,008	32,808	1.5x

Complexity scaling (uncached, batch of units per iteration)

Benchmark	master	this branch	Speedup
simple (m, kg, s)	122	4,000	33x
medium (km, kPa, MHz)	54	3,939	73x
complex (kg*m/s^2)	130	3,904	30x
very complex	108	2,735	25x

🤖 Generated with Claude Code