Add _.insert to array.builders

docs/underscore.array.builders.js.md

@@ -1,4 +1,4 @@
-### array.builders 
+### array.builders
 
 > Functions to build arrays. <a href="docs/underscore.array.builders.js.html" class="btn btn-primary btn-xs">View Annotated Source</a>
 
@@ -152,6 +152,20 @@ _.cycle(5, [1,2,3]);
 
 --------------------------------------------------------------------------------
 
+#### insert
+
+Given an array (or array-like object), an index and a value, insert the value at this index in the array. The value that was previously at this index shifts one position up, together with any values that may come after it. `_.insert` modifies the array in place and also returns it. Useful shorthand for `Array.prototype.splice.call(array, index, 0, value)`.
+
+```javascript
+var array = [1, 2, 3];
+var result = _.insert(array, 1, 4);
+//=> [1, 4, 2, 3]
+result === array;
+//=> true
+```
+
+--------------------------------------------------------------------------------
+
 #### interpose
 
 The `_.interpose` function takes an array and an element and returns a new array with the given element inserted betwixt every element in the original array:
@@ -198,7 +212,7 @@ That is, the array only contains every number from `5` down to `1` because when
 The `_.keepIndexed` function takes an array and a function and returns a new array filled with the *non-null* return results of the given function on the elements or keys in the given array:
 
 ```javascript
-_.keepIndexed([1,2,3], function(k) { 
+_.keepIndexed([1,2,3], function(k) {
   return i === 1 || i === 2;
 });
 
@@ -208,8 +222,8 @@ _.keepIndexed([1,2,3], function(k) {
 If you return either `null` or `undefined` then the result is dropped from the resulting array:
 
 ```javascript
-_.keepIndexed(['a','b','c'], function(k, v) { 
-  if (k === 1) return v; 
+_.keepIndexed(['a','b','c'], function(k, v) {
+  if (k === 1) return v;
 });
 
 //=> ['b']
@@ -291,7 +305,7 @@ _.splitAt([1,2,3,4,5], 20000);
 //=> [[1,2,3,4,5],[]]
 
 _.splitAt([1,2,3,4,5], -1000);
-//=> [[],[1,2,3,4,5]]    
+//=> [[],[1,2,3,4,5]]
 
 _.splitAt([], 0);
 //=> [[],[]]

test/array.builders.js

@@ -208,4 +208,13 @@ $(document).ready(function() {
     assert.deepEqual(_.combinations(["a",["b"]],[[1]]),[["a",[1]],[["b"],[1]]],'initial arrays can contain array elements which are then preserved');
   });
 
+  QUnit.test('insert', function(assert){
+    var throwingFn = function() { _.insert({}, 0, 1); };
+    assert.throws(throwingFn, TypeError, 'throws a TypeError when passing an object literal');
+
+    assert.deepEqual(_.insert([], 0, 1), [1],'inserts item in empty array');
+    assert.deepEqual(_.insert([2], 0, 1), [1,2],'inserst item at the corret index');
+    assert.deepEqual(_.insert([1,2], 2, 3), [1,2,3],'inserts item at the end of array if exceeding index');
+    assert.deepEqual(_.insert([1,3], -1, 2), [1,2,3],'inserst item at the correct index if negative index');
+  });
 });

underscore.array.builders.js

@@ -14,9 +14,10 @@
 
   // Helpers
   // -------
-  
+
   // Create quick reference variables for speed access to core prototypes.
   var slice   = Array.prototype.slice;
+  var splice  = Array.prototype.splice;
 
   var existy = function(x) { return x != null; };
 
@@ -25,7 +26,7 @@
 
   _.mixin({
     // Concatenates one or more arrays given as arguments.  If given objects and
-    // scalars as arguments `cat` will plop them down in place in the result 
+    // scalars as arguments `cat` will plop them down in place in the result
     // array.  If given an `arguments` object, `cat` will treat it like an array
     // and concatenate it likewise.
     cat: function() {
@@ -88,7 +89,7 @@
       if (sz === 0) return array;
       if (sz === 1) return array;
 
-      return slice.call(_.mapcat(array, function(elem) { 
+      return slice.call(_.mapcat(array, function(elem) {
         return _.cons(elem, [inter]);
       }), 0, -1);
     },
@@ -166,7 +167,7 @@
       return ret;
     },
 
-    // Runs its given function on the index of the elements rather than 
+    // Runs its given function on the index of the elements rather than
     // the elements themselves, keeping all of the truthy values in the end.
     keepIndexed: function(array, pred) {
       return _.filter(_.map(_.range(_.size(array)), function(i) {
@@ -196,6 +197,14 @@
           }));
         },[]);
       },_.map(arguments[0],function(i){return [i];}));
+    },
+
+    // Inserts an item in an array at the specific index mutating the original
+    // array and returning it.
+    insert: function(array, index, item){
+      if (!_.isNumber(array.length)) throw new TypeError('Expected an array-like object as the first argument');
+      splice.call(array, index, 0, item);
+      return array;
     }
 
   });