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.  The command returns 1  if  there  is  a
       match  and  0  if  there isn't.  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  subexpres-
       sion  of  exp.  Additional backslashes may be used in sub-
       Spec 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 back-
       slashes,  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 -.

       See  the manual entry for regexp for details on the inter-
       pretation of regular expressions.
KEYWORDS
       match, pattern, regular expression, substitute