In Ruby, how does uniq with a block decide which elements are duplicates, and which element does it keep for each key?

## What uniq with a block does `uniq` removes duplicates and returns a **new Array**. Without a block, elements are compared directly. With a block, Ruby compares the **block values** instead and returns the original elements: ```ruby %w[Ash ash Birch].uniq { |s| s.downcase } # => ["Ash", "Birch"] ``` "Ash" and "ash" produce the same key, `"ash"`, so the second is dropped. ## How the key is used In CRuby, `Enumerable#uniq` (`enum.c`) and `Array#uniq` (`array.c`) both work through a hidden Hash: 1. The block runs **once per element**. 2. The returned value is used as a Hash key; the element is stored as the value **only if the key is not already present** (`rb_hash_add_new_element`). 3. The result is the Hash's values, in insertion order. Three consequences follow: - **Duplicates are defined by Hash-key equality** of the block values: two elements collide exactly when their keys would land on the same Hash entry (the `eql?` and `hash` pair). - **The first occurrence is kept.** The `Array#uniq` rdoc says so directly: "the first occurrence always being retained". - **Order is preserved.** Survivors appear in the order they were first seen. ## Choosing which element survives Because the first occurrence wins, you control the survivor by ordering the input first. Hotel search often merges offers from several booking sources, and the page should show one offer per hotel, the cheapest: ```ruby Offer = Data.define(:hotel_id, :source, :price) cheapest = offers.sort_by { |o| o.price }.uniq { |o| o.hotel_id } ``` The variants: | Goal | Idiom | |---|---| | cheapest offer per hotel | `sort_by { \|o\| o.price }.uniq { \|o\| o.hotel_id }` | | most recent offer per hotel | `sort_by { \|o\| -o.fetched_at.to_i }.uniq { \|o\| o.hotel_id }` | | last occurrence in input order | `reverse.uniq { \|o\| o.hotel_id }.reverse` | | first occurrence in input order | `uniq { \|o\| o.hotel_id }` | When the sort key can tie, which tied element comes first is not guaranteed (Ruby's sorts are not stable), so add a tiebreaker to the sort key if the choice must be reproducible. ## Composite and derived keys The block can return any object that works as a Hash key: - an **array** for a composite identity: `uniq { |o| [o.hotel_id, o.room_type] }`; - a **normalised string** for case-insensitive or whitespace-insensitive matching: `uniq { |h| h.name.strip.downcase }`; - a **rounded number** to collapse near-identical prices: `uniq { |o| o.price.round }`. ## uniq on other Enumerables `Enumerable#uniq` is available on any Enumerable, not only Arrays, and always returns an Array. On a Hash it iterates `[key, value]` pairs: ```ruby {a: 1, b: 1, c: 2}.uniq { |k, v| v } # => [[:a, 1], [:c, 2]] ``` The result is an Array of pairs, not a Hash; call `to_h` on it if you need a Hash back. ## Cost `uniq` is a single pass with a Hash, so it is roughly linear in the number of elements, plus the cost of the block. Combined with a `sort_by` it becomes O(n log n), dominated by the sort. For a pipeline that only needs the minimum per group, that is usually acceptable and much clearer than a hand-written loop. ## Key points - The block produces a key; duplicates share a key. - The first element per key is kept, in original order. - Sort before `uniq` to decide which element survives. - `uniq` never mutates the receiver and always returns an Array.