Skip to content

Commit f78de68

Browse files
committed
explains Array.wrap directly, rather by comparison with Kernel#Array which is too obscure, leaves the comparison to document the differences, and adds a comparison with the related idiom that uses the splat operator
1 parent 96f8325 commit f78de68

File tree

2 files changed

+48
-4
lines changed

2 files changed

+48
-4
lines changed

activesupport/lib/active_support/core_ext/array/wrap.rb

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,17 @@
11
class Array
2-
# <tt>Array.wrap</tt> is like <tt>Kernel#Array</tt> except:
2+
# Wraps its argument in an array unless it is already an array (or array-like).
3+
#
4+
# Specifically:
5+
#
6+
# * If the argument is +nil+ an empty list is returned.
7+
# * Otherwise, if the argument responds to +to_ary+ it is invoked, and its result returned.
8+
# * Otherwise, returns an array with the argument as its single element.
9+
#
10+
# Array.wrap(nil) # => []
11+
# Array.wrap([1, 2, 3]) # => [1, 2, 3]
12+
# Array.wrap(0) # => [0]
13+
#
14+
# This method is similar in purpose to <tt>Kernel#Array</tt>, but there are some differences:
315
#
416
# * If the argument responds to +to_ary+ the method is invoked. <tt>Kernel#Array</tt>
517
# moves on to try +to_a+ if the returned value is +nil+, but <tt>Arraw.wrap</tt> returns
@@ -15,6 +27,15 @@ class Array
1527
#
1628
# Array("foo\nbar") # => ["foo\n", "bar"], in Ruby 1.8
1729
# Array.wrap("foo\nbar") # => ["foo\nbar"]
30+
#
31+
# There's also a related idiom that uses the splat operator:
32+
#
33+
# [*object]
34+
#
35+
# which returns <tt>[nil]</tt> for +nil+, and calls to <tt>Array(object)</tt> otherwise.
36+
#
37+
# Thus, in this case the behavior is different for +nil+, and the differences with
38+
# <tt>Kernel#Array</tt> explained above apply to the rest of +object+s.
1839
def self.wrap(object)
1940
if object.nil?
2041
[]

railties/guides/source/active_support_core_extensions.textile

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2214,14 +2214,27 @@ NOTE: Defined in +active_support/core_ext/array/conversions.rb+.
22142214

22152215
h4. Wrapping
22162216

2217-
The class method +Array.wrap+ behaves like the function +Array()+ except:
2217+
The method +Array.wrap+ wraps its argument in an array unless it is already an array (or array-like).
2218+
2219+
Specifically:
2220+
2221+
* If the argument is +nil+ an empty list is returned.
2222+
* Otherwise, if the argument responds to +to_ary+ it is invoked, and its result returned.
2223+
* Otherwise, returns an array with the argument as its single element.
2224+
2225+
<ruby>
2226+
Array.wrap(nil) # => []
2227+
Array.wrap([1, 2, 3]) # => [1, 2, 3]
2228+
Array.wrap(0) # => [0]
2229+
</ruby>
2230+
2231+
This method is similar in purpose to <tt>Kernel#Array</tt>, but there are some differences:
22182232

22192233
* If the argument responds to +to_ary+ the method is invoked. <tt>Kernel#Array</tt> moves on to try +to_a+ if the returned value is +nil+, but <tt>Arraw.wrap</tt> returns such a +nil+ right away.
22202234
* If the returned value from +to_ary+ is neither +nil+ nor an +Array+ object, <tt>Kernel#Array</tt> raises an exception, while <tt>Array.wrap</tt> does not, it just returns the value.
22212235
* It does not call +to_a+ on the argument, though special-cases +nil+ to return an empty array.
22222236

2223-
2224-
that it does not try to call +to_a+ on its argument. That changes the behavior for enumerables:
2237+
The last point is particularly worth comparing for some enumerables:
22252238

22262239
<ruby>
22272240
Array.wrap(:foo => :bar) # => [{:foo => :bar}]
@@ -2231,6 +2244,16 @@ Array.wrap("foo\nbar") # => ["foo\nbar"]
22312244
Array("foo\nbar") # => ["foo\n", "bar"], in Ruby 1.8
22322245
</ruby>
22332246

2247+
There's also a related idiom that uses the splat operator:
2248+
2249+
<ruby>
2250+
[*object]
2251+
</ruby>
2252+
2253+
which returns +[nil]+ for +nil+, and calls to <tt>Array(object)</tt> otherwise
2254+
2255+
Thus, in this case the behavior is different for +nil+, and the differences with <tt>Kernel#Array</tt> explained above apply to the rest of +object+s.
2256+
22342257
NOTE: Defined in +active_support/core_ext/array/wrap.rb+.
22352258

22362259
h4. Grouping

0 commit comments

Comments
 (0)