# $EPIC: sar,v 1.3 2005/03/08 05:53:31 jnelson Exp $
Synopsis:
   $sar([i][g][r]/<search>/<replace>/<text>)

Technical:
   The arguments are composed of:
   1) zero or more of the options 'i', 'g', and 'r',
   2) a delimiter which can be any character other than 'i', 'g', or 'r',
      and is customarily a forward-slash,
   3) some text ("<search>") that may not contain the delimiter to be removed,
   4) a delimiter; the same as (2),
   5) some text ("<replace>") that may not contain the delimiter to be inserted
      in place of #3,
   6) a delimiter; the same as (2), and
   7) a string of text ("<text>") that MAY contain the delimiter to be
      transformed.

   In its simple form, the string <text> is returned with the first instance
   of the string <search> replaced with the string <replace>.  The search of
   <search> is case insensitive.

   The options modify this behavior:
      i    The search for <search> should be case sensitive.
      g    All instances of <search> should be replaced with <replace>.
           You must be careful that the contents of <replace> do not match
           <search> because this would cause it to be infinitely replaced.
      r    The <text> argument is a variable that should be substituted.
           The result of the substitution(s) are assigned back to this
           variable.

Practical:
   This is the general purpose search-and-replace function.  It allows you
   to look for any arbitrary text substring in any text string, and replace
   it with another arbitrary substring.  Any of the strings may consist of
   variables to expand at runtime.

Returns:
   resultant string

Examples:
   @ foo = [foobarblah]
   $sar(/oo/ee/booyamon)              returns "beeyamon"
   $sar(/oo/ee/foofoo)                returns "feefoo"
   $sar(g/oo/ee/foofoo)               returns "feefee"
   $sar(r/oo/ee/foo)                  returns and sets $foo to "feebarblah"

See Also:
   tr(6); msar(6)