transform_values (Ruby Hash Method)

Reference entry · last updated September 20, 2026

transform_values is a method on Ruby's Hash class that returns a new Hash whose keys are unchanged and whose values are the results of applying a block to each original value.[1] Its in-place counterpart is transform_values!.

h = {foo: 0, bar: 1, baz: 2}
h.transform_values { |value| value * 100 }
# => {:foo=>0, :bar=>100, :baz=>200}

Previous version, archived September 20, 2026

First principles and definitions

A Hash maps unique keys to values and iterates over entries in insertion order.[1]

The transform_values block receives each value and returns its replacement. On a Hash, map yields each key-value pair as a two-element Array and returns an Array of block results.[1]

Ruby added transform_values and transform_values! in version 2.4.[2]

Signature and behavior

transform_values {|value| ... }  →  new_hash
transform_values                 →  new_enumerator

With a block, the method returns a new Hash. The block receives each value in turn, and the result pairs every original key with the block's output.[1]

Keys and order are preserved. The result has the same keys as the receiver, in the same insertion order.
The result is a separate Hash. Replacing an entry in the result leaves the original entry intact. Values are not deep-copied, so mutable objects can remain shared.
The default is dropped. The returned Hash has a nil default even when the receiver was built with a default value or a default proc. The implementation sets the new Hash's default to nil.

Mutating a shared value through the result also changes the value seen through the original Hash. The block can mutate an original value directly, too.[1]

original = {items: [1]}
result = original.transform_values { |value| value }
result[:items] << 2
original # => {:items=>[1, 2]}

Without a block, the method returns a new Enumerator, which can be driven with each or combined with other Enumerable methods.[1]

h = {foo: 0, bar: 1, baz: 2}
e = h.transform_values
e.each { |value| value * 100 }
# => {:foo=>0, :bar=>100, :baz=>200}

transform_values!

transform_values! {|value| ... }  →  self
transform_values!                 →  new_enumerator

The bang variant replaces each value in the receiver with the block's result and returns the receiver. It mutates the Hash in place, so any other reference to the same object observes the new values.[1] Without a block, it returns an Enumerator and defers mutation. Calling each with a block on that Enumerator replaces values in the original Hash.

h = {foo: 0, bar: 1, baz: 2}
h.transform_values! { |value| value * 100 }
h # => {:foo=>0, :bar=>100, :baz=>200}

h = {foo: 1}
e = h.transform_values!
h # => {:foo=>1}
e.each { |value| value * 100 }
h # => {:foo=>100}

Several Hash and Enumerable methods transform entries. They differ in which component the block sees and in what the method returns.

Method	Block sees	Result
`transform_values`	Value	New Hash, keys unchanged
`transform_values!`	Value	Same Hash, values replaced
`transform_keys`	Key	New Hash, values unchanged
`map`	Key-value pair	Array of block results
`each_value`	Value	Same Hash, no replacement
`select` / `reject`	Key-value pair	New Hash of kept or dropped entries

transform_keys is the key-side counterpart: it rebuilds the map with new keys and the original values. When a block must change both components, or when the result should be an Array rather than a Hash, map is the method that fits.[1]

Cost

For n entries, transform_values has O(n) traversal overhead, plus the total cost of the block calls. The new Hash structure uses O(n) additional space; objects allocated by the block add to that cost. The Hash holds the objects returned by the block.

These linear bounds describe the expected overhead of traversing and copying a Hash with n entries. Ruby documentation does not publish these as asymptotic guarantees.

References

^ Ruby Documentation, "Class Hash," Ruby 3.3.0. Free full text: docs.ruby-lang.org/en/3.3/Hash.html
^ Ruby Documentation, "Ruby 2.4.0 NEWS," Hash section, Feature #12512. Ruby 2.4.0. Free full text: docs.ruby-lang.org/en/2.4.0/NEWS.html