Permalink
Browse files

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
  • Loading branch information...
1 parent 96f8325 commit f78de6864998369002a5b1906dad151b6c787c24 @fxn fxn committed Aug 1, 2010
@@ -1,5 +1,17 @@
class Array
- # <tt>Array.wrap</tt> is like <tt>Kernel#Array</tt> except:
+ # Wraps its argument in an array unless it is already an array (or array-like).
+ #
+ # Specifically:
+ #
+ # * If the argument is +nil+ an empty list is returned.
+ # * Otherwise, if the argument responds to +to_ary+ it is invoked, and its result returned.
+ # * Otherwise, returns an array with the argument as its single element.
+ #
+ # Array.wrap(nil) # => []
+ # Array.wrap([1, 2, 3]) # => [1, 2, 3]
+ # Array.wrap(0) # => [0]
+ #
+ # This method is similar in purpose to <tt>Kernel#Array</tt>, but there are some differences:
#
# * 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
@@ -15,6 +27,15 @@ class Array
#
# Array("foo\nbar") # => ["foo\n", "bar"], in Ruby 1.8
# Array.wrap("foo\nbar") # => ["foo\nbar"]
+ #
+ # There's also a related idiom that uses the splat operator:
+ #
+ # [*object]
+ #
+ # which returns <tt>[nil]</tt> for +nil+, and calls to <tt>Array(object)</tt> otherwise.
+ #
+ # 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.
def self.wrap(object)
if object.nil?
[]
@@ -2214,14 +2214,27 @@ NOTE: Defined in +active_support/core_ext/array/conversions.rb+.
h4. Wrapping
-The class method +Array.wrap+ behaves like the function +Array()+ except:
+The method +Array.wrap+ wraps its argument in an array unless it is already an array (or array-like).
+
+Specifically:
+
+* If the argument is +nil+ an empty list is returned.
+* Otherwise, if the argument responds to +to_ary+ it is invoked, and its result returned.
+* Otherwise, returns an array with the argument as its single element.
+
+<ruby>
+Array.wrap(nil) # => []
+Array.wrap([1, 2, 3]) # => [1, 2, 3]
+Array.wrap(0) # => [0]
+</ruby>
+
+This method is similar in purpose to <tt>Kernel#Array</tt>, but there are some differences:
* 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.
* 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.
* It does not call +to_a+ on the argument, though special-cases +nil+ to return an empty array.
-
- that it does not try to call +to_a+ on its argument. That changes the behavior for enumerables:
+The last point is particularly worth comparing for some enumerables:
<ruby>
Array.wrap(:foo => :bar) # => [{:foo => :bar}]
@@ -2231,6 +2244,16 @@ Array.wrap("foo\nbar") # => ["foo\nbar"]
Array("foo\nbar") # => ["foo\n", "bar"], in Ruby 1.8
</ruby>
+There's also a related idiom that uses the splat operator:
+
+<ruby>
+[*object]
+</ruby>
+
+which returns +[nil]+ for +nil+, and calls to <tt>Array(object)</tt> otherwise
+
+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.
+
NOTE: Defined in +active_support/core_ext/array/wrap.rb+.
h4. Grouping

0 comments on commit f78de68

Please sign in to comment.