replace_string(3)     LPC Library Functions     replace_string(3)

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  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".

SEE ALSO
     sscanf(3), explode(3), strsrch(3)

AUTHOR
     Zak@TMI-2 wrote the range constraint additions.

MudOS                Last change: 5 Sep 1994                    1