1mNAME0m
       regsub  -  Perform  substitutions  based  on regular expression pattern
       matching

1mSYNOPSIS0m
       1mregsub 22m?4mswitches24m? 4mexp24m 4mstring24m 4msubSpec24m ?4mvarName24m?


1mDESCRIPTION0m
       This command matches the regular expression  4mexp24m  against  4mstring24m,  and
       either  copies 4mstring24m to the variable whose name is given by 4mvarName24m or
       returns 4mstring24m if 4mvarName24m is not present.  (Regular expression matching
       is  described  in  the 1mre_syntax 22mreference page.)  If there is a match,
       then while copying 4mstring24m to 4mvarName24m (or to the result of this  command
       if  4mvarName24m  is  not present) the portion of 4mstring24m that matched 4mexp24m is
       replaced with 4msubSpec24m.  If 4msubSpec24m contains a ``&'' or ``\0'', then  it
       is replaced in the substitution with the portion of 4mstring24m that matched
       4mexp24m.  If 4msubSpec24m contains a ``\4mn24m'', where 4mn24m is a digit between 1 and 9,
       then it is replaced in the substitution with the portion of 4mstring24m that
       matched the 4mn24m-th parenthesized subexpression of 4mexp24m.  Additional  back-
       slashes  may  be  used  in 4msubSpec24m to prevent special interpretation of
       ``&'' or ``\0'' or ``\4mn24m'' or backslash.  The use of backslashes in 4msub-0m
       4mSpec24m  tends to interact badly with the Tcl parser's use of backslashes,
       so it's generally safest to enclose 4msubSpec24m in braces  if  it  includes
       backslashes.

       If  the  initial arguments to 1mregsub 22mstart with 1m- 22mthen they are treated
       as switches.  The following switches are currently supported:

       1m-all      22mAll ranges in 4mstring24m that match 4mexp24m are found  and  substitu-
                 tion  is  performed  for  each of these ranges.  Without this
                 switch only the first matching range  is  found  and  substi-
                 tuted.  If 1m-all 22mis specified, then ``&'' and ``\4mn24m'' sequences
                 are handled for each substitution using the information  from
                 the corresponding match.

       1m-expanded      22mEnables  use  of  the expanded regular expression syntax
                      where whitespace and comments are ignored.  This is  the
                      same  as  specifying  the  1m(?x) 22membedded option (see the
                      1mre_syntax 22mmanual page).

       1m-line          22mEnables newline-sensitive matching.  By default, newline
                      is a completely ordinary character with no special mean-
                      ing.  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  1m-linestop 22mand 1m-lineanchor22m, or the 1m(?n)0m
                      embedded option (see the 1mre_syntax 22mmanual page).

       1m-linestop      22mChanges the behavior of `[^' bracket expressions and `.'
                      so  that  they  stop  at  newlines.  This is the same as
                      specifying the 1m(?p) 22membedded option (see  the  1mre_syntax0m
                      manual page).

       1m-lineanchor    22mChanges the behavior of `^' and `$' (the ``anchors'') so
                      they match the beginning and end of a line respectively.
                      This  is the same as specifying the 1m(?w) 22membedded option
                      (see the 1mre_syntax 22mmanual page).

       1m-nocase   22mUpper-case characters in 4mstring24m will be converted  to  lower-
                 case  before  matching  against  4mexp24m;  however, substitutions
                 specified by 4msubSpec24m use the  original  unconverted  form  of
                 4mstring24m.

       1m-start 4m22mindex0m
                 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 4mindex24m.  4mindex24m will  be
                 constrained to the bounds of the input string.

       1m--        22mMarks  the  end of switches.  The argument following this one
                 will be treated as 4mexp24m even if it starts with a 1m-22m.

       If 4mvarName24m 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  1mregexp  22mfor
       details on the interpretation of regular expressions.

1mEXAMPLES0m
       Replace  (in the string in variable 4mstring24m) every instance of 1mfoo 22mwhich
       is a word by itself with 1mbar22m:
              1mregsub 22m-all {\<foo\>} $string bar string

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

       Convert  all  non-ASCII  and  Tcl-significant characters into \u escape
       sequences by using 1mregsub 22mand 1msubst 22min 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 [1mregsub 22m-all $RE $string $substitution]]


1mSEE ALSO0m
       regexp(n), re_syntax(n), subst(n)


1mKEYWORDS0m
