Added inject, which inserts the items of one array into another at a …

…given offset

Readme.md

@@ -4,7 +4,7 @@ More-underscore is an add-on to [Underscore][1]. Please enjoy, and feel free to
 
 ## Documentation
 
-###extendClass
+### extendClass
 
     _.extendClass( dst, src )
 
@@ -22,7 +22,7 @@ Extends a constructor with the prototype of another. When using this, it's requi
     // Extend prototype
     _.extendClass( Bar, Foo );
 
-###objectify
+### objectify
 
     _.objectify( arr, [...] )
 
@@ -40,4 +40,14 @@ Gets a value within a multi-level collection. A path is a list of object keys an
     _.traverse( { 'a': ['b', 'c', { 'd': 'test' }] }, ['a', 2, 'd'] );
     => 'test'
 
+### inject
+
+    _.inject( arr, offset, items )
+
+Inserts items of one array into another at a given offset.
+
+    var arr = [0, 1, 2, 3];
+    _.traverse( arr, 2, ['a', 'b', 'c'] );
+    => [0, 1, 'a', 'b', 'c', 2, 3]
+
 [1]: http://github.com/documentcloud/underscore/

more-underscore.js

@@ -88,5 +88,36 @@ _.mixin( {
 			}
 		}
 		return value;
+	},
+	/**
+	 * Inserts items of one array into another at a given offset.
+	 *
+	 * This is the equivalent of calling arr.splice( offset, 0, d1, d2, d3, ... ) except that the
+	 * "d1, d2, d3, ..." arguments are specified as an array rather than separate parameters.
+	 *
+	 * @example
+	 *     var arr = [1, 2, 3];
+	 *     _.inject( arr, 1, [4, 5, 6] );
+	 *     // arr is now [1, 4, 5, 6, 2, 3];
+	 *
+	 * @static
+	 * @method
+	 * @param {Array} arr Array to remove from and insert into. Will be modified
+	 * @param {Number} offset Offset in arr to splice at. May be negative; see the 'index'
+	 * parameter for Array.prototype.splice()
+	 * @param {Array} items Array of items to insert at the offset
+	 */
+	'inject': function( arr, offset, items ) {
+		// Splicing needs to be done in in batches, because of maximum argument length limits tend
+		// to vary between JavaScript engines - 1024 seems to be a safe batch size on all of them
+		var index = 0,
+			batchSize = 1024;
+		// Splice in batches of 1024 items at a time
+		while ( index < items.length ) {
+			arr.splice.apply(
+				arr, [index + offset, 0].concat( items.slice( index, index + batchSize ) )
+			);
+			index += batchSize;
+		}
 	}
 } );

tests/more-underscore.test.js

@@ -11,15 +11,18 @@ test( 'extendClass', function() {
 		this.e = true;
 	}
 	ParentClass.prototype.b = b;
-	function ChildClass() { }
+	function ChildClass() {
+		ParentClass.call( this );
+	}
 	ChildClass.prototype.c = c;
 	ChildClass.prototype.d = d;
 	_.extendClass( ChildClass, ParentClass );
-	strictEqual( ChildClass.prototype.a, a, 'Child prototype has methods from parent constructor' );
+	var child = new ChildClass();
+	strictEqual( child.a, a, 'Child inherits methods from parent through constructor' );
 	strictEqual( ChildClass.prototype.b, b, 'Child prototype has methods from parent prototype' );
 	strictEqual( ChildClass.prototype.c, c, 'Child prototype has methods from child prototype' );
 	strictEqual( ChildClass.prototype.d, d, 'Child prototype overrides parent methods' );
-	strictEqual( ChildClass.prototype.e, undefined, 'Parent properties are ignored' );
+	strictEqual( ChildClass.prototype.e, undefined, 'Parent properties are not inherited' );
 	strictEqual( ParentClass.prototype.c, undefined, 'Parent prototype is not modified' );
 } );
 
@@ -50,3 +53,10 @@ test( 'traverse', function() {
 	equal( _.traverse( tree, [] ), tree, 'Empty path returns top-level object' );
 	equal( _.traverse( tree ), tree, 'Undefined path returns top-level object' );
 } );
+
+test( 'inject', function() {
+	var actual = [1, 2, 3, 4, 5, 6, 7, 8, 9],
+		expected = [1, 2, 3, 'a', 'b', 'c', 'd', 'e', 4, 5, 6, 7, 8, 9];
+	_.inject( actual, 3, ['a', 'b', 'c', 'd', 'e'] );
+	deepEqual( actual, expected, 'Inserts items in the middle' );
+} );