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

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


1mDESCRIPTION0m
       This command matches the regular expression 4mexp24m against 4mstring24m, and  it
       copies 4mstring24m to the variable whose name is given by 4mvarName24m.  (Regular
       expression matching is described in the 1mre_syntax 22mreference page.)   If
       there  is  a match, then while copying 4mstring24m to 4mvarName24m 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 substi-
       tution with the portion of 4mstring24m that matched the  4mn24m-th  parenthesized
       subexpression of 4mexp24m.  Additional backslashes may be used in 4msubSpec24m to
       prevent special interpretation of ``&'' or ``\0'' or  ``\4mn24m''  or  back-
       slash.   The use of backslashes in 4msubSpec24m 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 1mregexp 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 META-
                      SYNTAX, below).

       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 METASYNTAX, below).

       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  METASYNTAX,
                      below).

       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 METASYNTAX, below).

       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.

       The command returns a count of the number of matching ranges that  were
       found and replaced.  See the manual entry for 1mregexp 22mfor details on the
       interpretation of regular expressions.


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


1mKEYWORDS0m
