mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
22fd617aa5
Adds a full discussion of #dig, along with links from Array, Hash, Struct, and OpenStruct. CSV::Table and CSV::Row are over in ruby/csv. I'll get to them soon. The art to the thing is to figure out how much (or how little) to say at each #dig.
82 lines
2.6 KiB
Text
82 lines
2.6 KiB
Text
= Dig Methods
|
|
|
|
Ruby's +dig+ methods are useful for accessing nested data structures.
|
|
|
|
Consider this data:
|
|
item = {
|
|
id: "0001",
|
|
type: "donut",
|
|
name: "Cake",
|
|
ppu: 0.55,
|
|
batters: {
|
|
batter: [
|
|
{id: "1001", type: "Regular"},
|
|
{id: "1002", type: "Chocolate"},
|
|
{id: "1003", type: "Blueberry"},
|
|
{id: "1004", type: "Devil's Food"}
|
|
]
|
|
},
|
|
topping: [
|
|
{id: "5001", type: "None"},
|
|
{id: "5002", type: "Glazed"},
|
|
{id: "5005", type: "Sugar"},
|
|
{id: "5007", type: "Powdered Sugar"},
|
|
{id: "5006", type: "Chocolate with Sprinkles"},
|
|
{id: "5003", type: "Chocolate"},
|
|
{id: "5004", type: "Maple"}
|
|
]
|
|
}
|
|
|
|
Without a +dig+ method, you can write:
|
|
item[:batters][:batter][1][:type] # => "Chocolate"
|
|
|
|
With a +dig+ method, you can write:
|
|
item.dig(:batters, :batter, 1, :type) # => "Chocolate"
|
|
|
|
Without a +dig+ method, you can write, erroneously
|
|
(raises <tt>NoMethodError (undefined method `[]' for nil:NilClass)</tt>):
|
|
item[:batters][:BATTER][1][:type]
|
|
|
|
With a +dig+ method, you can write (still erroneously, but avoiding the exception):
|
|
item.dig(:batters, :BATTER, 1, :type) # => nil
|
|
|
|
== Why Is +dig+ Better?
|
|
|
|
- It has fewer syntactical elements (to get wrong).
|
|
- It reads better.
|
|
- It does not raise an exception if an item is not found.
|
|
|
|
== How Does +dig+ Work?
|
|
|
|
The call sequence is:
|
|
obj.dig(*identifiers)
|
|
|
|
The +identifiers+ define a "path" into the nested data structures:
|
|
- For each identifier in +identifiers+, calls method \#dig on a receiver
|
|
with that identifier.
|
|
- The first receiver is +self+.
|
|
- Each successive receiver is the value returned by the previous call to +dig+.
|
|
- The value finally returned is the value returned by the last call to +dig+.
|
|
|
|
A +dig+ method raises an exception if any receiver does not respond to \#dig:
|
|
h = { foo: 1 }
|
|
# Raises TypeError (Integer does not have #dig method):
|
|
h.dig(:foo, :bar)
|
|
|
|
== What Else?
|
|
|
|
The structure above has \Hash objects and \Array objects,
|
|
both of which have instance method +dig+.
|
|
|
|
Altogether there are six built-in Ruby classes that have method +dig+,
|
|
three in the core classes and three in the standard library.
|
|
|
|
In the core:
|
|
- Array#dig: the first argument is an \Integer index.
|
|
- Hash#dig: the first argument is a key.
|
|
- Struct#dig: the first argument is a key.
|
|
|
|
In the standard library:
|
|
- OpenStruct#dig: the first argument is a \String name.
|
|
- CSV::Table#dig: the first argument is an \Integer index or a \String header.
|
|
- CSV::Row#dig: the first argument is an \Integer index or a \String header.
|