tcl7.6 User Commands - regsub






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.  Addi-
     tional 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 match-
               ing  range  is  found and substituted.  If -all is
               specified, then ``&''  and  ``\n''  sequences  are
               handled  for  each substitution using the informa-
               tion from the corresponding match.

     -nocase    Upper-case characters in string will be converted
               to  lower-case  before matching against exp;  how-
               ever, substitutions specified by subSpec  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  expres-
     sions.



KEYWORDS

     match, pattern, regular expression, substitute