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 either copies string │
       to the variable whose name is given by  varName  or  returns  string  if  varName  is  not │
       present.   (Regular expression matching is described in the re_syntax reference page.)  If
       there is a match, then while copying string to varName (or to the result of  this  command │
       if  varName  is  not  present)  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 regsub 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.

       -expanded      Enables use of the expanded regular expression syntax where whitespace  and
                      comments  are  ignored.   This  is the same as specifying the (?x) embedded
                      option (see the re_syntax manual page).

       -line          Enables newline-sensitive matching.  By default, newline  is  a  completely
                      ordinary  character  with no special meaning.  With this flag, `[^' bracket
                      expressions and `.' never match newline, `^' matches an empty string  after
                      any  newline  in  addition to its normal function, and `$' matches an empty
                      string before any newline in addition to its normal function.  This flag is
                      equivalent  to  specifying  both  -linestop  and  -lineanchor,  or the (?n)
                      embedded option (see the re_syntax manual page).

       -linestop      Changes the behavior of `[^' bracket expressions and `.' so that they  stop
                      at  newlines.  This is the same as specifying the (?p) embedded option (see
                      the re_syntax manual page).

       -lineanchor    Changes the behavior of `^' and `$' (the ``anchors'')  so  they  match  the
                      beginning  and  end of a line respectively.  This is the same as specifying
                      the (?w) embedded option (see the re_syntax manual page).

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

       If varName is supplied, the command returns a count of the number of matching ranges  that │
       were  found  and  replaced,  otherwise  the string after replacement is returned.  See the
       manual entry for regexp for details on the interpretation of regular expressions.

EXAMPLES

       Replace (in the string in variable string) every instance of foo which is a word by itself
       with bar:
              regsub -all {\<foo\>} $string bar string

       Insert  double-quotes  around  the  first  instance of the word interesting, however it is
       capitalised.
              regsub -nocase {\<interesting\>} $string {"&"} string

       Convert all non-ASCII and Tcl-significant characters into \u  escape  sequences  by  using
       regsub and subst in combination:
              # This RE is just a character class for everything "bad"
              set RE {[][{}\$\s\u0100-\uffff]}

              # We will substitute with a fragment of Tcl script in brackets
              set substitution {[format \\\\u%04x [scan "\\&" %c]]}

              # Now we apply the substitution to get a subst-string that
              # will perform the computational parts of the conversion.
              set quoted [subst [regsub -all $RE $string $substitution]]

SEE ALSO

       regexp(3tcl), re_syntax(3tcl), subst(3tcl)

KEYWORDS

       match, pattern, regular expression, substitute