regsub(n)

_________________________________________________________________

NAME
       regsub - Perform substitutions based on regular expression
       pattern matching

SYNOPSIS
       regsub ?switches? exp string subSpec varName
_________________________________________________________________

DESCRIPTION
       This command matches the regular  expression  exp  against
       string, and it copies string to the variable whose name is
       given by varName.  If there is a match, then while copying
       string  to  varName the portion of string that matched exp
       is replaced with subSpec.  If subSpec contains a ``&''  or
       ``\0'',  then  it is replaced in the substitution with the
       portion of string that matched exp.  If subSpec contains a
       ``\n'',  where  n  is  a digit between 1 and 9, then it is
       replaced in the substitution with the  portion  of  string
       that  matched the n-th parenthesized subexpression of exp.
       Additional backslashes may be used in subSpec  to  prevent
       special  interpretation  of  ``&''  or ``\0'' or ``\n'' or
       backslash.  The use of backslashes  in  subSpec  tends  to
       interact  badly  with the Tcl parser's use of backslashes,
       so it's generally safest to enclose subSpec in  braces  if
       it includes backslashes.

       If  the initial arguments to regexp start with - then they
       are treated as switches.  The following switches are  cur-
       rently supported:

       -all      All  ranges  in  string that match exp are found
                 and substitution is performed for each of  these
                 ranges.   Without  this  switch  only  the first
                 matching range is  found  and  substituted.   If
                 -all   is   specified,  then  ``&''  and  ``\n''
                 sequences  are  handled  for  each  substitution
                 using  the  information  from  the corresponding
                 match.

       -nocase   Upper-case characters in  string  will  be  con-
                 verted  to  lower-case  before  matching against
                 exp;  however, substitutions specified  by  sub-
                 Spec   use  the  original  unconverted  form  of
                 string.

       --        Marks the end of switches.  The argument follow-
                 ing  this  one will be treated as exp even if it
                 starts with a -.

       The command returns a count  of  the  number  of  matching
       ranges that were found and replaced.  See the manual entry

       for regexp for details on the  interpretation  of  regular
       expressions.

KEYWORDS
       match, pattern, regular expression, substitute