From e17e08efef68e9865cfbd5c0155b3d9734339192 Mon Sep 17 00:00:00 2001
From: Xavier Noria <fxn@hashref.com>
Date: Wed, 28 Jul 2010 03:49:04 +0200
Subject: adds test coverage for edge-cases of Array.wrap, and better
 documentation for how it differs from Kernel#Array

---
 .../lib/active_support/core_ext/array/wrap.rb        | 13 +++++++++----
 activesupport/test/core_ext/array_ext_test.rb        | 20 ++++++++++++++++++++
 .../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}]
-- 
cgit v1.2.3