diff --git a/docs/underscore.array.builders.js.md b/docs/underscore.array.builders.js.md index d5850b7..0788d36 100644 --- a/docs/underscore.array.builders.js.md +++ b/docs/underscore.array.builders.js.md @@ -1,4 +1,4 @@ -### array.builders +### array.builders > Functions to build arrays. View Annotated Source @@ -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); //=> [[],[]] diff --git a/test/array.builders.js b/test/array.builders.js index a143b0f..07d406b 100644 --- a/test/array.builders.js +++ b/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'); + }); }); diff --git a/underscore.array.builders.js b/underscore.array.builders.js index 426657f..2be04f9 100644 --- a/underscore.array.builders.js +++ b/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; } });