splice

Splice an array

SPLICE

NAME

splice : Remove elements from an array and replace it with new elements.

SYNOPSIS

splice(array, start[, length[, replacements, ...]]);

DESCRIPTION

This function remove elements from an array and optionally replace it with new elements.

PARAMETERS

- array (array): A valid array

- start (int): The index of array at which the first element will be removed. 0 based. `1` will select the second item. Negative numbers will place the index counting from the end of the array (`-1` being the last entry).

- length (int - optional): The number of elements that will be removed starting at the `start` index. A value of 0 will remove no item; this is usefull in conjonction with 'replacements' when you want to add items in the middle of the array. IMPORTANT: Not putting any `length` defaults to remove ALL items starting at the `start` index.

- replacements (mixed - comma separeted list - optional): The `length` parameter becomes required when using replacements. You can add a list of comma separeted items to be replaced by the items that were removed.

RETURN

This function returns a new array.

EXAMPLES

Default behaviour

arr = [{"hello": "world"},{"hello": "sky"},{"hello": "earth"},{"hello": "sea"},{"hello": "hell"},{"hello": "paradise"}];
arr = arr.splice(1);
// Restult => [{"hello":"world"}]

// Alternate syntax
arr = [{"hello": "world"},{"hello": "sky"},{"hello": "earth"},{"hello": "sea"},{"hello": "hell"},{"hello": "paradise"}];
arr = splice(arr, 1);
// Restult => [{"hello":"world"}]

// Using negative number
arr = [{"hello": "world"},{"hello": "sky"},{"hello": "earth"},{"hello": "sea"},{"hello": "hell"},{"hello": "paradise"}];
arr = arr.splice(-2);
// Restult => [{"hello":"world"},{"hello":"sky"},{"hello":"earth"},{"hello":"sea"}]

Using parameter `length`

arr = [{"hello": "world"},{"hello": "sky"},{"hello": "earth"},{"hello": "sea"},{"hello": "hell"},{"hello": "paradise"}];
arr = arr.splice(1, 2);
// Result => [{"hello":"world"},{"hello":"sea"},{"hello":"hell"},{"hello":"paradise"}]

// Using negative number
arr = [{"hello": "world"},{"hello": "sky"},{"hello": "earth"},{"hello": "sea"},{"hello": "hell"},{"hello": "paradise"}];
arr = arr.splice(-2, 1);
// Result => [{"hello":"world"},{"hello":"sky"},{"hello":"earth"},{"hello":"sea"},{"hello":"paradise"}]

Using replacements

arr = [{"hello": "world"},{"hello": "sky"},{"hello": "earth"},{"hello": "sea"},{"hello": "hell"},{"hello": "paradise"}];
arr = arr.splice(1, 1, {"hello": "cosmos"});
// Restult => [{"hello":"world"},{"hello":"cosmos"},{"hello":"earth"},{"hello":"sea"},{"hello":"hell"},{"hello":"paradise"}]

// More than one replacement
arr = [{"hello": "world"},{"hello": "sky"},{"hello": "earth"},{"hello": "sea"},{"hello": "hell"},{"hello": "paradise"}];
arr = arr.splice(1, 2, {"hello": "cosmos"}, {"hello": "ground"});
// Restult => [{"hello":"world"},{"hello":"cosmos"},{"hello":"ground"},{"hello":"sea"},{"hello":"hell"},{"hello":"paradise"}]

// Remove more items than replacements
arr = [{"hello": "world"},{"hello": "sky"},{"hello": "earth"},{"hello": "sea"},{"hello": "hell"},{"hello": "paradise"}];
arr = arr.splice(1, 4, {"hello": "cosmos"}, {"hello": "ground"});
// Result => [{"hello":"world"},{"hello":"cosmos"},{"hello":"ground"},{"hello":"paradise"}]

// More replacements than `length`
arr = [{"hello": "world"},{"hello": "sky"},{"hello": "earth"},{"hello": "sea"},{"hello": "hell"},{"hello": "paradise"}];
arr = arr.splice(1, 1, {"hello": "cosmos"}, {"hello": "ground"});
// Result => [{"hello":"world"},{"hello":"cosmos"},{"hello":"ground"},{"hello":"earth"},{"hello":"sea"},{"hello":"hell"},{"hello":"paradise"}]

// Add item in the middle of the array (without removing any items)
arr = [{"hello": "world"},{"hello": "sky"},{"hello": "earth"},{"hello": "sea"},{"hello": "hell"},{"hello": "paradise"}]; 
arr = arr.splice(3, 0, {"hello": "My spliced item between earth and sea"});
// Result => [{"hello":"world"},{"hello":"sky"},{"hello":"earth"},{"hello":"My spliced item between earth and sea"},{"hello":"sea"},{"hello":"hell"},{"hello":"paradise"}]