diff options
| -rw-r--r-- | activesupport/lib/active_support/core_ext/array/wrap.rb | 13 | ||||
| -rw-r--r-- | activesupport/test/core_ext/array_ext_test.rb | 20 | ||||
| -rw-r--r-- | railties/guides/source/active_support_core_extensions.textile | 9 |
3 files changed, 37 insertions, 5 deletions
diff --git a/activesupport/lib/active_support/core_ext/array/wrap.rb b/activesupport/lib/active_support/core_ext/array/wrap.rb index e211bdeeca..09a1c2e5a1 100644 --- a/activesupport/lib/active_support/core_ext/array/wrap.rb +++ b/activesupport/lib/active_support/core_ext/array/wrap.rb @@ -1,9 +1,14 @@ class Array - # Wraps the object in an Array unless it's an Array. Converts the - # object to an Array using #to_ary if it implements that. + # <tt>Array.wrap</tt> is like <tt>Kernel#Array</tt> except: # - # It differs with Array() in that it does not call +to_a+ on - # the argument: + # * 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. + # + # The last point is particularly worth comparing for some enumerables: # # Array(:foo => :bar) # => [[:foo, :bar]] # Array.wrap(:foo => :bar) # => [{:foo => :bar}] diff --git a/activesupport/test/core_ext/array_ext_test.rb b/activesupport/test/core_ext/array_ext_test.rb index 54376deee5..009a254c64 100644 --- a/activesupport/test/core_ext/array_ext_test.rb +++ b/activesupport/test/core_ext/array_ext_test.rb @@ -398,6 +398,18 @@ class ArrayWrapperTests < Test::Unit::TestCase def method_missing(*a) @target.send(*a) end end + class DoubtfulToAry + def to_ary + :not_an_array + end + end + + class NilToAry + def to_ary + nil + end + end + def test_array ary = %w(foo bar) assert_same ary, Array.wrap(ary) @@ -438,4 +450,12 @@ class ArrayWrapperTests < Test::Unit::TestCase o = Struct.new(:foo).new(123) assert_equal [o], Array.wrap(o) end + + def test_wrap_returns_nil_if_to_ary_returns_nil + assert_nil Array.wrap(NilToAry.new) + end + + def test_wrap_does_not_complain_if_to_ary_does_not_return_an_array + assert_equal DoubtfulToAry.new.to_ary, Array.wrap(DoubtfulToAry.new) + end end diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index d14a531abe..fc59df9fe4 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -2229,7 +2229,14 @@ NOTE: Defined in +active_support/core_ext/array/conversions.rb+. h4. Wrapping -The class method +Array.wrap+ behaves like the function +Array()+ except that it does not try to call +to_a+ on its argument. That changes the behavior for enumerables: +The class method +Array.wrap+ behaves like the function +Array()+ except: + +* 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: <ruby> Array.wrap(:foo => :bar) # => [{:foo => :bar}] |