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.   (Regular  expression   matching   is
       described in the re_syntax reference page.)  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
       currently 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
                 converted  to lower-case before matching against
                 exp;   however,   substitutions   specified   by
                 subSpec  use  the  original  unconverted form of
                 string.

       -start index
                 Specifies a  character  index  offset  into  the
                 string  to start matching the regular expression
                 at.  When using this switch, `^' will not  match
                 the  beginning  of  the  line, and \A will still
                 match the start of  the  string  at  index.   If
                 -indices  is  specified,  the  indices  will  be
                 indexed starting from the absolute beginning  of
                 the  input string.  index will be constrained to
                 the bounds of the input string.

       --        Marks  the  end  of  switches.    The   argument
                 following  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
