substr_replace

Replace text within a portion of a string

&reftitle.description; ``string``array```substr_replace` ``array``string```string` ``array``string```replace` ``array``int```offset` ``array``int``null```length`&null;

`substr_replace` replaces a copy of `string` delimited by the `offset` and (optionally) `length` parameters with the string given in `replace`.

&reftitle.parameters;

`string`

- The input string.

  An `array` of `string`s can be provided, in which case the replacements will occur on each string in turn. In this case, the `replace`, `offset` and `length` parameters may be provided either as scalar values to be applied to each input string in turn, or as `array`s, in which case the corresponding array element will be used for each input string.

`replace`

- The replacement string.

`offset`

- If `offset` is non-negative, the replacing will begin at the `offset`'th offset into `string`.

  If `offset` is negative, the replacing will begin at the `offset`'th character from the end of `string`.

`length`

- If given and is positive, it represents the length of the portion of `string` which is to be replaced. If it is negative, it represents the number of characters from the end of `string` at which to stop replacing. If it is not given, then it will default to strlen( `string` ); i.e. end the replacing at the end of `string`. Of course, if `length` is zero then this function will have the effect of inserting `replace` into `string` at the given `offset` offset.

&reftitle.returnvalues;

The result string is returned. If `string` is an array then array is returned.

&reftitle.changelog;

&Version; | &Description;
8.0.0 | `length` is nullable now.

&reftitle.examples;

### Simple `substr_replace` examples

    <?php
    $var = 'ABCDEFGH:/MNRPQR/';
    echo "Original: $var<hr />\n";

    /* These two examples replace all of $var with 'bob'. */
    echo substr_replace($var, 'bob', 0) . "<br />\n";
    echo substr_replace($var, 'bob', 0, strlen($var)) . "<br />\n";

    /* Insert 'bob' right at the beginning of $var. */
    echo substr_replace($var, 'bob', 0, 0) . "<br />\n";

    /* These next two replace 'MNRPQR' in $var with 'bob'. */
    echo substr_replace($var, 'bob', 10, -1) . "<br />\n";
    echo substr_replace($var, 'bob', -7, -1) . "<br />\n";

    /* Delete 'MNRPQR' from $var. */
    echo substr_replace($var, '', 10, -1) . "<br />\n";
    ?>

### Using `substr_replace` to replace multiple strings at once

    <?php
    $input = array('A: XXX', 'B: XXX', 'C: XXX');

    // A simple case: replace XXX in each string with YYY.
    echo implode('; ', substr_replace($input, 'YYY', 3, 3))."\n";

    // A more complicated case where each replacement is different.
    $replace = array('AAA', 'BBB', 'CCC');
    echo implode('; ', substr_replace($input, $replace, 3, 3))."\n";

    // Replace a different number of characters each time.
    $length = array(1, 2, 3);
    echo implode('; ', substr_replace($input, $replace, 3, $length))."\n";
    ?>

&example.outputs;

    A: YYY; B: YYY; C: YYY
    A: AAA; B: BBB; C: CCC
    A: AAAXX; B: BBBX; C: CCC

&reftitle.notes; ¬e.bin-safe;
&reftitle.seealso;

- `str_replace`
- `substr`
- String access and modification by character