In Ruby, what do Hash#transform_keys and transform_values return, and what happens when two old keys map to the same new key?

## What each method returns `Hash#transform_keys` and `Hash#transform_values` build a **new hash** from an existing one, changing one side of every entry: - **`transform_keys { |key| ... }`** replaces each key with the block's return value and keeps the value. - **`transform_values { |value| ... }`** replaces each value and keeps the key. Its block receives **only the value**. - Both keep the receiver's **entry order**. - Both leave the receiver unchanged. Without a block they return an `Enumerator`. A detail worth knowing: the new hash does **not** inherit the receiver's default value or default proc. `Hash.new(0).merge(a: 1).transform_values { |v| v * 2 }[:missing]` returns `nil`, not `0`. ## Three ways to name the new keys | Call | Keys listed in the mapping | Other keys | |---|---|---| | `transform_keys { \|k\| ... }` | n/a | block's return value | | `transform_keys(stars: :rating)` | renamed per the mapping | kept unchanged | | `transform_keys(stars: :rating) { \|k\| ... }` | renamed per the mapping, block not called | block's return value | Entries in the mapping that match no key are ignored. The mapping form is the concise way to rename a few fields from an external payload without touching the rest. ## Collisions overwrite silently If two old keys produce the same new key, the one processed **later** wins, because building the result is a series of assignments into the new hash: ```ruby {"Plot" => 2, "plot" => 5}.transform_keys(&:downcase) # => {"plot" => 5} ``` No exception or warning is raised. When keys come from users or external systems, normalising case, whitespace or type can merge entries. Guard against it: 1. Compare sizes: `result.size == source.size` detects a collision. 2. Merge deliberately instead, for example by building the result with `each_with_object` and summing counts for colliding words. ## The bang versions `transform_keys!` and `transform_values!` modify the receiver and return `self`, including when nothing changed; they do not follow the self-or-nil convention of some `Array` bang methods. `transform_keys!` also accepts the mapping hash and the block. Because it rewrites keys in place, it has the same collision behaviour: a duplicate new key overwrites. ## Only the top level changes Both methods are **shallow**. `transform_keys(&:to_sym)` on a parsed review such as `{"title" => "Dune", "author" => {"name" => "Ann"}}` symbolises `title` and `author`, but the nested hash under `author` keeps its string key `"name"`. Converting a whole tree needs a recursive helper that calls `transform_keys` on every nested hash and walks arrays, or conversion at parse time by the parser that produced the data. Likewise, `transform_values` passes nested hashes to its block as whole values; the block decides whether to descend. ## Changing keys and values together - Chain them: `h.transform_keys(&:to_sym).transform_values(&:to_i)`, which allocates one intermediate hash. - Use `to_h` with a block that returns a pair: `h.to_h { |k, v| [k.to_sym, v.to_i] }`, which builds one hash. ## Example: normalising review word counts A word-frequency table built from raw review text may contain `"Plot"` and `"plot"` as separate keys. `transform_keys(&:downcase)` would keep only one count. Summing into a fresh hash keeps both: ```ruby normalised = raw.each_with_object(Hash.new(0)) { |(w, n), acc| acc[w.downcase] += n } ``` Then `normalised.transform_values { |n| (n * 100.0 / total).round(1) }` turns counts into percentages while keeping the keys and their order.