
     rrrreeeeppppllllaaaacccceeee____ssssttttrrrriiiinnnngggg((((3333))))      MMMMuuuuddddOOOOSSSS ((((5555 SSSSeeeepppp 1111999999994444))))       rrrreeeeppppllllaaaacccceeee____ssssttttrrrriiiinnnngggg((((3333))))

     NNNNAAAAMMMMEEEE
          replace_string() - replace all instances of a string within
          a string

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          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;

     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
          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 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".

     SSSSEEEEEEEE AAAALLLLSSSSOOOO
          sscanf(3), explode(3), strsrch(3)

     AAAAUUUUTTTTHHHHOOOORRRR
          Zak@TMI-2 wrote the range constraint additions.

