<HTML><HEAD><TITLE>Tcl Built-In Commands - regsub manual page</TITLE></HEAD><BODY> <DL> <DD><A HREF="regsub.htm#M2" NAME="L968">NAME</A> <DL><DD>regsub - Perform substitutions based on regular expression pattern matching</DL> <DD><A HREF="regsub.htm#M3" NAME="L969">SYNOPSIS</A> <DL> <DD><B>regsub </B>?<I>switches</I>? <I>exp string subSpec varName</I> </DL> <DD><A HREF="regsub.htm#M4" NAME="L970">DESCRIPTION</A> <DL> <DD><A HREF="regsub.htm#M5" NAME="L971"><B>-all</B></A> <DD><A HREF="regsub.htm#M6" NAME="L972"><B>-expanded</B></A> <DD><A HREF="regsub.htm#M7" NAME="L973"><B>-line</B></A> <DD><A HREF="regsub.htm#M8" NAME="L974"><B>-linestop</B></A> <DD><A HREF="regsub.htm#M9" NAME="L975"><B>-lineanchor</B></A> <DD><A HREF="regsub.htm#M10" NAME="L976"><B>-nocase</B></A> <DD><A HREF="regsub.htm#M11" NAME="L977"><B>-start</B> <I>index</I></A> <DD><A HREF="regsub.htm#M12" NAME="L978"><B>- -</B></A> </DL> <DD><A HREF="regsub.htm#M13" NAME="L979">SEE ALSO</A> <DD><A HREF="regsub.htm#M14" NAME="L980">KEYWORDS</A> </DL><HR> <H3><A NAME="M2">NAME</A></H3> regsub - Perform substitutions based on regular expression pattern matching <H3><A NAME="M3">SYNOPSIS</A></H3> <B>regsub </B>?<I>switches</I>? <I>exp string subSpec varName</I><BR> <H3><A NAME="M4">DESCRIPTION</A></H3> This command matches the regular expression <I>exp</I> against <I>string</I>, and it copies <I>string</I> to the variable whose name is given by <I>varName</I>. (Regular expression matching is described in the <B><A HREF="../TkCmd/re_syntax.htm">re_syntax</A></B> reference page.) If there is a match, then while copying <I>string</I> to <I>varName</I> the portion of <I>string</I> that matched <I>exp</I> is replaced with <I>subSpec</I>. If <I>subSpec</I> contains a ``&'' or ``\0'', then it is replaced in the substitution with the portion of <I>string</I> that matched <I>exp</I>. If <I>subSpec</I> contains a ``\<I>n</I>'', where <I>n</I> is a digit between 1 and 9, then it is replaced in the substitution with the portion of <I>string</I> that matched the <I>n</I>-th parenthesized subexpression of <I>exp</I>. Additional backslashes may be used in <I>subSpec</I> to prevent special interpretation of ``&'' or ``\0'' or ``\<I>n</I>'' or backslash. The use of backslashes in <I>subSpec</I> tends to interact badly with the Tcl parser's use of backslashes, so it's generally safest to enclose <I>subSpec</I> in braces if it includes backslashes. <P> If the initial arguments to <B><A HREF="../TkCmd/regexp.htm">regexp</A></B> start with <B>-</B> then they are treated as switches. The following switches are currently supported: <P> <DL> <P><DT><A NAME="M5"><B>-all</B></A><DD> All ranges in <I>string</I> that match <I>exp</I> are found and substitution is performed for each of these ranges. Without this switch only the first matching range is found and substituted. If <B>-all</B> is specified, then ``&'' and ``\<I>n</I>'' sequences are handled for each substitution using the information from the corresponding match. <P><DT><A NAME="M6"><B>-expanded</B></A><DD> Enables use of the expanded regular expression syntax where whitespace and comments are ignored. This is the same as specifying the <B>(?x)</B> embedded option (see METASYNTAX, below). <P><DT><A NAME="M7"><B>-line</B></A><DD> 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 <B>-linestop</B> and <B>-lineanchor</B>, or the <B>(?n)</B> embedded option (see METASYNTAX, below). <P><DT><A NAME="M8"><B>-linestop</B></A><DD> Changes the behavior of `[^' bracket expressions and `.' so that they stop at newlines. This is the same as specifying the <B>(?p)</B> embedded option (see METASYNTAX, below). <P><DT><A NAME="M9"><B>-lineanchor</B></A><DD> 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 <B>(?w)</B> embedded option (see METASYNTAX, below). <P><DT><A NAME="M10"><B>-nocase</B></A><DD> Upper-case characters in <I>string</I> will be converted to lower-case before matching against <I>exp</I>; however, substitutions specified by <I>subSpec</I> use the original unconverted form of <I>string</I>. <P><DT><A NAME="M11"><B>-start</B> <I>index</I></A><DD> 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 <I>index</I>. <I>index</I> will be constrained to the bounds of the input string. <P><DT><A NAME="M12"><B>- -</B></A><DD> Marks the end of switches. The argument following this one will be treated as <I>exp</I> even if it starts with a <B>-</B>. <P></DL> <P> The command returns a count of the number of matching ranges that were found and replaced. See the manual entry for <B><A HREF="../TkCmd/regexp.htm">regexp</A></B> for details on the interpretation of regular expressions. <H3><A NAME="M13">SEE ALSO</A></H3> <B><A HREF="../TkCmd/regexp.htm">regexp</A></B>, <B><A HREF="../TkCmd/re_syntax.htm">re_syntax</A></B> <H3><A NAME="M14">KEYWORDS</A></H3> <A href="../Keywords/M.htm#match">match</A>, <A href="../Keywords/P.htm#pattern">pattern</A>, <A href="../Keywords/R.htm#regular expression">regular expression</A>, <A href="../Keywords/S.htm#substitute">substitute</A> <HR><PRE> <A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California. <A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc. <A HREF="../copyright.htm">Copyright</A> © 2000 Scriptics Corporation. <A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE> </BODY></HTML>