splice

  • function
can.List.prototype.splice  

Insert and remove elements from a List.

list.splice(index[, howMany[, ...newElements]])

Parameters

  1. index {Number}

    where to start removing or inserting elements

  2. howMany {Number}Optional

    the number of elements to remove If howMany is not provided, splice will remove all elements from index to the end of the List.

  3. newElements {*}

    elements to insert into the List

Returns

{Array}

the elements removed by splice

splice lets you remove elements from and insert elements into a List.

This example demonstrates how to do surgery on a list of numbers:

 var list = new can.List([0, 1, 2, 3]);

 // starting at index 2, remove one element and insert 'Alice' and 'Bob':
 list.splice(2, 1, 'Alice', 'Bob');
 list.attr(); // [0, 1, 'Alice', 'Bob', 3]

Events

splice causes the List it's called on to emit change events, add events, remove events, and length events. If there are any elements to remove, a change event, a remove event, and a length event will be fired. If there are any elements to insert, a separate change event, an add event, and a separate length event will be fired.

This slightly-modified version of the above example should help make it clear how splice causes events to be emitted:

 var list = new can.List(['a', 'b', 'c', 'd']);
 list.bind('change', function(ev, attr, how, newVals, oldVals) {
     console.log('change: ' + attr + ', ' + how + ', ' + newVals + ', ' + oldVals);
 });
 list.bind('add', function(ev, newVals, where) {
     console.log('add: ' + newVals + ', ' + where);
 });
 list.bind('remove', function(ev, oldVals, where) {
     console.log('remove: ' + oldVals + ', ' + where);
 });
 list.bind('length', function(ev, length) {
     console.log('length: ' + length + ', ' + this.attr());
 });

 // starting at index 2, remove one element and insert 'Alice' and 'Bob':
 list.splice(2, 1, 'Alice', 'Bob'); // change: 2, 'remove', undefined, ['c']
                                    // remove: ['c'], 2
                                    // length: 5, ['a', 'b', 'Alice', 'Bob', 'd']
                                    // change: 2, 'add', ['Alice', 'Bob'], ['c']
                                    // add: ['Alice', 'Bob'], 2
                                    // length: 5, ['a', 'b', 'Alice', 'Bob', 'd']

More information about binding to these events can be found under [can.List.attr attr].