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
       “&”, “\0”, “\n” and backslashes.  The use of backslashes in subSpec tends to interact badly with the  Tcl
       parser's  use  of  backslashes,  so  it  is  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.
              The  index  value  is  interpreted in the same manner as the index argument to string index.  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 {\mfoo\M} $string bar string

       or (using the “basic regular expression” syntax):

              regsub -all {(?b)\<foo\>} $string bar string

       Insert double-quotes around the first instance of the word interesting, however it is capitalized.

              regsub -nocase {\yinteresting\y} $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 almost everything "bad"
              set RE {[][{};#\\\$ \r\t\u0080-\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. Note
              # that newline is handled specially through string map since
              # backslash-newline is a special sequence.
              set quoted [subst [string map {\n {\\u000a}} \
                      [regsub -all $RE $string $substitution]]]

SEE ALSO

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

KEYWORDS

       match, pattern, quoting, regular expression, substitution

Tcl                                                    8.3                                          regsub(3tcl)