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 sub-
       Spec 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 parenthe-
       sized 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.

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