Hash#assoc

Updated May 30, 2026· Hash Methods

rubyhashhash-methodssearch

Hash#assoc searches a hash by key and returns the matching key-value pair as a two-element array [key, value]. It is the counterpart to Hash#rassoc, which searches by value.

The method is handy when you want the key and the value together instead of just the value. That makes it useful for inspection, lookups that need to keep the original key around, and situations where the hash entry itself matters more than the value alone.

Basic Usage

person = { name: "Alice", age: 30, city: "NYC" }

person.assoc(:name)
# => [:name, "Alice"]

person.assoc(:age)
# => [:age, 30]

person.assoc(:missing)
# => nil

When a key matches, you get both the key and its value in an array. When no key matches, assoc returns nil.

That result shape is easy to branch on because there are only two outcomes: a pair or nothing. It keeps the caller and avoids a separate key lookup to recover it later.

Signature

assoc(key)

Returns the first key-value pair where the key matches the given argument. The search proceeds in insertion order and stops on the first match. Unlike [], this method returns the full [key, value] pair instead of just the value.

The method does not try to be clever beyond that first match. If you need a custom search rule or a value-based lookup, a different hash method will usually be clearer.

String Keys

config = { "host" => "localhost", "port" => 3000 }

config.assoc("host")
# => ["host", "localhost"]

config.assoc("port")
# => ["port", 3000]

Works with symbols, strings, numbers, or any object that supports == comparison.

This flexibility makes assoc convenient for hashes that mix different key types. The comparison still follows Ruby’s normal equality rules, so the lookup behaves the same way the rest of the language does.

counts = { 1 => "one", 2 => "two" }

counts.assoc(2)
# => [2, "two"]

Comparing with other hash methods

Method	Searches by	Returns
`assoc`	key	`[key, value]` or `nil`
`rassoc`	value	`[key, value]` or `nil`
`[]`	key	value or `nil`
`fetch`	key (with default)	value or default
`key`	value	key or `nil`

The key difference between assoc and []: the bracket method returns only the value, while assoc returns both key and value together. This comes in handy when you need the key back after a lookup.

It is often the cleaner choice when the data is being inspected or displayed rather than modified. Returning the pair directly avoids a second call just to recover the key you already matched.

Behavior with defaults

h = Hash.new("unknown")

h[:missing] = "found"
h.assoc(:missing)
# => [:missing, "found"]

h.assoc(:nonexistent)
# => nil

Unlike [], the assoc method is not affected by the receiver’s default value or default_proc. It always returns nil for keys that do not exist.

That behavior is deliberate and predictable, which makes assoc safer for checking which entries are actually stored. A default value would blur the line between stored data and fallback behavior, and this method avoids that confusion.

Limitations

Only returns the first match. If the collection has duplicate keys, only the first one in insertion order is returned:

scores = { alice: 95, bob: 87, alice: 100 }

scores.assoc(:alice)
# => [:alice, 95]
# The second :alice entry is not reached

The first match rule keeps the method deterministic. Even if the input is unusual, the caller always knows that the earliest matching pair wins.

Linear search. The collection is scanned from the beginning, making this O(n) regardless of hash size.

No block form. Unlike select or find, there is no variant that accepts a block for custom matching logic.

That limitation is usually fine because assoc is meant to be simple and direct. If the matching rule needs to grow, moving to a more general search method is usually the clearer path.