Document performance overhead in README

[dblock]

What

Adds a new Performance subsection under Benchmarks in README.md, documenting the actual overhead of Ruby::Enum's basic operations vs. plain Ruby equivalents, backed by a new benchmark script.

Benchmarks added

benchmarks/basic.rb (rake benchmark:basic) compares, over 1,000,000 iterations:

• Constant access: Colors::RED vs. a plain Ruby constant
• Key → value lookup: Colors.value(:RED) vs. Hash#[]
• Value → key lookup: Colors.key('red') vs. Hash#key
• Existence checks: Colors.key?(:RED) vs. Hash#key?
• Enumerating: Colors.keys/Colors.values vs. Hash#keys/Hash#values

Sample results (may vary by machine)

--- Constant access ---
Ruby::Enum constant (Colors::RED): 0.0167
plain Ruby constant (PlainConstants::RED): 0.0165

--- Key to value lookup ---
Ruby::Enum (Colors.value(:RED)): 0.0633
plain Hash (PLAIN_HASH[:RED]): 0.0211

--- Comparison ---
Ruby::Enum constant access is 1.01x plain Ruby constant access
Ruby::Enum .value is 3.0x plain Hash#[]

README

The new Performance section summarizes:

• Constant access has no measurable overhead.
• Hash-backed lookups (value, key, key?, value?, keys, values) carry roughly 3-5x overhead vs. a plain Hash, due to method dispatch/object wrapping.
• This overhead does not grow with subclass depth, thanks to the memoization added in Memoize merged enum hashes to fix superclass-lookup performance regression #60 (see rake benchmark:inheritance).
• Ruby::Enum::Case is the one notable outlier, at 50-100x slower than a native case statement (see rake benchmark:case), since it's the only feature involving lambda construction/evaluation at call time.

Testing

• bundle exec rake (rubocop + rspec): 69 examples, 0 failures, rubocop clean (25 files)
• rake benchmark:basic run manually to generate the numbers above

[github-actions]

Danger Report

No issues found.

View run