fluffos/docs/efun/strings/replace_string.md

---
title: strings / replace_string
---
# replace_string

### NAME

    replace_string() - replace all instances of a string within a string

### SYNOPSIS

    string replace_string( str, pattern, replace );
    string replace_string( str, pattern, replace, max );
    string replace_string( str, pattern, replace, first, last );

    string str, pattern replace;
    int max, first, last;

### DESCRIPTION

    replace_string()  returns  str  with  all instances of pattern replaced
    with replace.  If pattern has zero length then str is returned  unmodi‐
    fied.   If  the resultant string would exceed the maximum string length
    then replace_string() returns an undefinedp(), non-stringp() value.

    replace_string() can be used to remove  characters  from  a  string  by
    specifying a pattern and a zero-length replace parameter.  For example,
    replace_string("  1  2  3   ",   "   ",   "")   would   return   "123".
    replace_string() executes faster this way then explode()/implode().

    The  4th and 5th arguments are optional (to retain backward compatibil‐
    ity.)  The extra arguments have the following effect:

    4 args
        The 4th argument specifies the maximum number  of  replacements  to
        make  (the  count starts at 1). A value of 0 implies 'replace all',
        and thus, acts as replace_string() with 3  arguments  would.  E.g.,
        replace_string("xyxx", "x", "z", 2) would return "zyzx".

    5 args
        The  4th  and 5th arguments specify the range of matches to replace
        between, with the following constraints:
        - first < 1 : change all from the start.
        - last == 0, or last > max_matches : change all to end
        - first > last : return the unmodified array.
        E.g., replace_string("xyxxy", "x", "z", 2, 3) returns "xyzzy".

### SEE ALSO

    sscanf(3), explode(3), strsrch(3)

### AUTHOR

    Zak@TMI-2 wrote the range constraint additions.