finalizing new Array.create. Clone ability and handling inherited

Former-commit-id: 8fff8fb81d6c703a3bb3591075196be1be7801d4 [formerly d8fd44342b01dd3effaa61a47e9e420d74ee3ffd]
Former-commit-id: fd143ba4c7bb60c660b009b3fb77cb7d8dca3e6d

CAUTION.md

@@ -50,7 +50,7 @@ v2.0.0+
   - `Array#randomize` was renamed to `Array#shuffle`.
 
 - Level: Major
-  - `Array.create` functionality has changed. See the docs for more details or use ES6 method `Array.from` instead. Sugar provides this as a polyfill in the default bundle.
+  - `Array.create` now only accepts one argument. See the docs for more details or use ES6 method `Array.from` instead. Sugar provides this as a polyfill in the default bundle.
 
 - Level: Major
   - `Object.watch` was removed. This method was the only part of Sugar that was not 100% compatible in all environments, and was an overly simplistic solution to a difficult problem that others have done better (see discussions around Object.observe and polling). As a quick and dirty solution, this will be made available as a [plugin](https://github.com/andrewplummer/sugar-plugins). Also includes `Object.unwatch`.

CHANGELOG.md

@@ -48,7 +48,7 @@ v2.0.0
 - Renamed `Array#randomize` to `Array#shuffle`
 - Added `Array#sample` ability to remove sampled elements and performance optimization.
 - Added `String#replaceAll` and `String#removeAll`.
-- Added polyfill for `Array.from` and removed `Array.create`.
+- Added polyfill for `Array.from` and modified `Array.create` to return a reference by default.
 - Changed behavior of `Function#after` to more closely match that of Underscore/Lodash.
 - Changed behavior of `Number#times` to return an array of return values.
 - Changed `Object.fromQueryString` to return a plain object.
@@ -77,7 +77,6 @@ v2.0.0
 - Removed `Array#include` (now is identical to `Array#add`).
 - Added `Object.invert`.
 - Moved `String#titleize` to String module from Inflections.
-- Added `Array.create`.
 - Modified `Object.has` to allow deep keys. Previous behavior is now moved to `Object.hasOwn`.
 - Removed `Object.extended` and all trace of Hashes in favor of Sugar chainables.
 

lib/array.js

@@ -80,10 +80,6 @@ function isArrayOrInherited(obj) {
   return obj && obj.constructor && isArray(obj.constructor.prototype);
 }
 
-function arrayCreateOrClone(obj) {
-  return isArray(obj) ? arrayClone(obj) : arrayCreateFromArrayLike(obj);
-}
-
 function arrayCreateFromArrayLike(obj) {
   if (isObjectType(obj) || isString(obj)) {
     return Array.from(obj);
@@ -379,14 +375,14 @@ defineStatic(sugarArray, {
 
   /***
    *
-   * @method Array.create(<obj>, [map], [context])
+   * @method Array.create(<obj>, [clone] = false)
    * @returns Array
    * @short Creates an array from an unknown <obj>.
-   * @extra This method is similar to native `Array.from` except that if <obj>
-   *        is already an array it will perform a quick clone operation, which
-   *        can be a bit faster. Additionally, it will not fail on `undefined`,
-   *        `null`, or numbers, producing an empty array in the case of
-   *        `undefined` and wrapping <obj> otherwise.
+   * @extra This method is similar to native `Array.from` but is faster when
+   *        <obj> is already an array, even when [clone] is true, in which case
+   *        the array will be shallow cloned. Additionally, it will not fail on
+   *        `undefined`, `null`, or numbers, producing an empty array in the
+   *        case of `undefined` and wrapping <obj> otherwise.
    * @example
    *
    *   Array.create()          -> []
@@ -396,8 +392,13 @@ defineStatic(sugarArray, {
    *   Array.create(undefined) -> []
    *
    ***/
-  'create': function(obj) {
-    return arrayCreateOrClone(obj);
+  'create': function(obj, clone) {
+    if (!isArrayOrInherited(obj)) {
+      obj = arrayCreateFromArrayLike(obj);
+    } else if (clone) {
+      obj = arrayClone(obj);
+    }
+    return obj;
   },
 
   /***

lib/extras/upgrade.js

@@ -131,8 +131,9 @@
     {
       type: 'Array',
       sName: 'create',
-      message: 'Array.create was removed. Use native Array.from instead. Sugar provides this as a polyfill in the default bundle.',
-      docs: 'Array/from'
+      check: moreThanOneArgument,
+      message: 'Array.create now only accepts a single argument. See the docs for more details.',
+      docs: 'Array/create'
     },
     {
       type: 'Array',

test/tests/array.js

@@ -22,10 +22,15 @@ namespace('Array', function () {
   method('create', function() {
     var arrayLike = { 0: 1, 1: 2, 2: 3, length: 3 }
     var args = (function() { return arguments; })('a','b','c');
+    var Soup = function() {}; Soup.prototype = [1,2,3]; var inst = new Soup();
+
+    var arr = [1,2,3];
+    equal(run(Array, 'create', [arr]) === arr, true, 'should return a reference by default');
 
     var arr = [1,2,3];
-    equal(arr === run(Array, 'create', [arr]), false, 'Should clone a passed array');
+    equal(run(Array, 'create', [arr, true]) === arr, false, 'should clone the array with argument');
 
+    equal(run(Array, 'create', [inst]) === inst, true, 'should return reference to inherited');
     test(Array, [], 'no argument produces empty array');
     test(Array, [undefined], [], 'undefined is the same as no argument');
     test(Array, [8], [8], 'non-object argument wraps in array');