Description

Removes the elements designated by offset and
length from the input array,
and replaces them with the elements of the
replacement array, if supplied.

Note that numeric keys in input are not preserved.

Note:
If replacement is not an array, it will be
typecast
to one (i.e. (array) $replacement). This may result in unexpected
behavior when using an object or NULLreplacement.

Parameters

input

The input array.

offset

If offset is positive then the start of removed
portion is at that offset from the beginning of the
input array. If offset
is negative then it starts that far from the end of the
input array.

length

If length is omitted, removes everything
from offset to the end of the array. If
length is specified and is positive, then
that many elements will be removed. If
length is specified and is negative then
the end of the removed portion will be that many elements from
the end of the array. If length is
specified and is zero, no elements will be removed.
Tip: to remove everything from
offset to the end of the array when
replacement is also specified, use
count($input) for
length.

replacement

If replacement array is specified, then the
removed elements are replaced with elements from this array.

If offset and length
are such that nothing is removed, then the elements from the
replacement array are inserted in the place
specified by the offset. Note that keys in
replacement array are not preserved.

If replacement is just one element it is
not necessary to put array()
around it, unless the element is an array itself, an object or NULL.

Splicing with NULL as replacement may result in unexpected behavior too. Typecasting NULL into an array results in an empty array (as "(array)NULL" equals "array()"). That means, instead of creating an element with value NULL just no new element ist created (just as if there was no replacement specified).

If you want the splicing to create a new element with value NULL you have to use "array(NULL)" instead of NULL.

You should expect this if you read the explanation carefully, but just as objects are considered as a special case for replacement, NULL should be too.

The explanation of replacement better should read: "If replacement is just one element it is not necessary to put array() around it, unless the element is an array itself, an object or NULL."

And the note better should be: "If replacement is not an array, it will be typecast to one (i.e. (array) $parameter). This may result in unexpected behavior when using an object or NULL replacement."

Remember that you are telling the array to insert the element into the KEY position. Thus the elements start with key 0 and so on 0=>1, 1=>2, 2=>3, 3=>blue, 4=>4, 5=>5. And walla, you've inserted. I can't say if this is of any value for named keys, or multidimensional arrays. However it does work for single dimensional arrays.

$returned should be an empty array as nothing was returned. This would have substance if you were doing a replace instead.

array_splice dynamically updates the total number of entries into the array. So for instance I had a case where I needed to insert a value into every 4th entry of the array from the back. The problem was when it added the first, because the total number was dynamically updated, it would only add after the 3rd then the 2nd and so one. The solution I found is to track the number of inserts which were done and account for them dynamically.

Appending arrays
If you have an array $a2 whose values you would like to append to an array $a1 then four methods you could use are listed below in order of increasing time. The last two methods took significantly more time than the first two. The most surprising lesson is that using the & incurs a time hit.

After reading KoKos' post above, I thought that the code I posted right before his should do what he wanted. However, my original post neglected to note the little "Tip" in the documentation above, about a single element replacement.

Note the position of $t[0] in the second call to var_dump().
And of course, array_splice() left it intact, changing $t[2] instead.
This is because it operates the _offset_, not the _index_. :)
I think that "equivalence note" should be considered buggy. ;)))

In PHP 4.3.10, at least, it seems that elements that are inserted as part of the replacement array are inserted BY REFERENCE (that is, as though with the =& rather than = assignment operation). So if your replacement array contains elements that references to variables that you can also access via other variable name, then this will be true of the elements in the final array too.

In particular, this means that it is safe to use array_splice() on arrays of objects, as you won't be creating copies of the objects (as it is so easy to do in PHP 4).

A comment on array_merge mentioned that array_splice is faster than array_merge for inserting values. This may be the case, but if your goal is instead to reindex a numeric array, array_values() is the function of choice. Performing the following functions in a 100,000-iteration loop gave me the following times: ($b is a 3-element array)

The failure to check for the insert case like you pointed out is not a bug, however. I didn't add code to handle that because the key of such an added index is more or less undefined in an unordered associative array. Put another way, if your array is associative and not auto-indexed, you most likely care enough about your keys to want to set them explicitly.

Sometimes you may want to insert one array into another and just work on with the resulting array. array_splice() doesn't support this, as the resulting array isn't the returned value but the first argument, which is changed by reference.

Therefore you may use the following function, which inserts array $ins in array $src at position $pos. $rep can be used if $ins shouldn't be just inserted, but should replace some existing elements (the number of elements to be replaced is given in $rep).

It preserves numeric keys. Note that the function does not use a reference to the original array but returns a new array (I see absolutely no reason how the performance would be increased by using a reference when modifying an array through PHP script code).

Maybe it will help someone else: I was trying to strip off the last part of an array using this section, more or less as follows:

<?php array_splice($array, $offset); ?>

Now it could occur in my code that <?php $offset === 0 ?>, in which case the array is returned as-is and not, as you might expect, an empty array because everything is stripped off. Obviously it is not really useful anyway to "strip off everything", but I was reminded of that the hard way and this may spare someone some time, hopefully.

[ Editor's Note: If you're not concerned with the indexes being contiguously numbered (such as for an associative array) then unset($ar[$ind]); will accomplish the same as the code below without requiring splice/splice/merge. If contiguous numbering IS a concern (such as for indexed arrays), you can still save time by using: unset($ar[$ind]); $ar = array_values($ar); ]

I need <?php array_Splice()?> function, that use array keys instead of order (offset and length) because of associated arrays, and this is result:

<?php/** * first variation * * $input is input array * $start is index of slice begin * $end is index of slice end, if this is null, $replacement will be inserted (in the same way as original array_Slice()) *indexes of $replacement are preserved in both examples */function array_KSplice1(&$input, $start, $end=null, $replacement=null){$keys=array_Keys($input);$values=array_Values($input); if($replacement!==null) {$replacement=(array)$replacement;$rKeys=array_Keys($replacement);$rValues=array_Values($replacement); }

/** * second variation * * $input is input array * $start is index of slice begin * $length is length of slice, what will be replaced, if is zero, $replacement will be inserted (in the same way as original array_Slice()) */function array_KSplice2(&$input, $start, $length=0, $replacement=null){$keys=array_Keys($input);$values=array_Values($input); if($replacement!==null) {$replacement=(array)$replacement;$rKeys=array_Keys($replacement);$rValues=array_Values($replacement); }

$arr[0] = "test"; // should be $a$arr[3] = "test2"; // should be $b$arr[1] = "this be d?"; // should be $d$arr[2] = "or this be d?"; // should be $dvar_dump($arr);var_dump($a);var_dump($b);var_dump($d);?>

In this case, the array has a number of items added to it equal to the number of attributes in the new Node object and the values thereof I.e, if your Node object has 2 attributes with values "foo" and "bar", count($tree->childNodes) will now return 4, with the items "foo" and "bar" added to it. I'm not sure if this qualifies as a bug, or is just a byproduct of how PHP handles objects.

Note that this function makes no allowances for when $offset equals the first or last index in the array. That's because array_unshift and array_push work just fine in those cases. It's only array_splice that can trip you up. Obviously, this is kinda tailor-made for arrays with numeric keys when you don't really care what said keys are, but i'm sure you could adapt it for associative arrays if you needed it.