update comments and increase speed of merging JSONArray objects

Author: John J. Aylward

src/main/java/org/json/JSONArray.java

@@ -194,15 +194,16 @@ public JSONArray(Iterable<?> iter) {
     /**
      * Construct a JSONArray from another JSONArray. This is a shallow copy.
      *
-     * @param collection
-     *            A Collection.
+     * @param array
+     *            A array.
      */
     public JSONArray(JSONArray array) {
         if (array == null) {
             this.myArrayList = new ArrayList<Object>();
         } else {
-            this.myArrayList = new ArrayList<Object>(array.length());
-            this.addAll(array.myArrayList);
+            // shallow copy directly the internal array lists as any wrapping
+            // should have been done already in the original JSONArray
+            this.myArrayList = new ArrayList<Object>(array.myArrayList);
         }
     }
 
@@ -1213,7 +1214,7 @@ public JSONArray putAll(Collection<?> collection) {
      * Put an Iterable's elements in to the JSONArray.
      *
      * @param iter
-     *            A Collection.
+     *            An Iterable.
      * @return this. 
      */
     public JSONArray putAll(Iterable<?> iter) {
@@ -1229,7 +1230,9 @@ public JSONArray putAll(Iterable<?> iter) {
      * @return this. 
      */
     public JSONArray putAll(JSONArray array) {
-        this.addAll(array.myArrayList);
+        // directly copy the elements from the source array to this one
+        // as all wrapping should have been done already in the source.
+        this.myArrayList.addAll(array.myArrayList);
         return this;
     }
 
@@ -1606,8 +1609,9 @@ private void addAll(Iterable<?> iter) {
      * Add an array's elements to the JSONArray.
      *
      * @param array
-     *            Array. If the parameter passed is null, or not an array, an
-     *            exception will be thrown.
+     *            Array. If the parameter passed is null, or not an array,
+     *            JSONArray, Collection, or Iterable, an exception will be
+     *            thrown.
      *
      * @throws JSONException
      *            If not an array or if an array value is non-finite number.
@@ -1622,7 +1626,10 @@ private void addAll(Object array) throws JSONException {
                 this.put(JSONObject.wrap(Array.get(array, i)));
             }
         } else if (array instanceof JSONArray) {
-            this.addAll(((JSONArray)array).myArrayList);
+            // use the built in array list `addAll` as all object
+            // wrapping should have been completed in the original
+            // JSONArray
+            this.myArrayList.addAll(((JSONArray)array).myArrayList);
         } else if (array instanceof Collection) {
             this.addAll((Collection<?>)array);
         } else if (array instanceof Iterable) {