From f78de6864998369002a5b1906dad151b6c787c24 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sun, 1 Aug 2010 03:19:30 +0200 Subject: 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 --- .../source/active_support_core_extensions.textile | 29 +++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) (limited to 'railties/guides/source/active_support_core_extensions.textile') diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index fcf4ae29ba..136fcde82a 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -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. + + +Array.wrap(nil) # => [] +Array.wrap([1, 2, 3]) # => [1, 2, 3] +Array.wrap(0) # => [0] + + +This method is similar in purpose to Kernel#Array, but there are some differences: * If the argument responds to +to_ary+ the method is invoked. Kernel#Array moves on to try +to_a+ if the returned value is +nil+, but Arraw.wrap returns such a +nil+ right away. * If the returned value from +to_ary+ is neither +nil+ nor an +Array+ object, Kernel#Array raises an exception, while Array.wrap 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: 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 +There's also a related idiom that uses the splat operator: + + +[*object] + + +which returns +[nil]+ for +nil+, and calls to Array(object) otherwise + +Thus, in this case the behavior is different for +nil+, and the differences with Kernel#Array explained above apply to the rest of +object+s. + NOTE: Defined in +active_support/core_ext/array/wrap.rb+. h4. Grouping -- cgit v1.2.3