replace_string

       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 unmodified.  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
       compatibility.)   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 con-
              straints:
              - 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.