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