summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/regsub.n25
1 files changed, 17 insertions, 8 deletions
diff --git a/doc/regsub.n b/doc/regsub.n
index 9fe54ab..6fa4bd0 100644
--- a/doc/regsub.n
+++ b/doc/regsub.n
@@ -6,7 +6,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: regsub.n,v 1.7 2001/11/28 13:15:31 dkf Exp $
+'\" RCS: @(#) $Id: regsub.n,v 1.8 2002/02/22 14:52:45 dkf Exp $
'\"
.so man.macros
.TH regsub n 8.3 Tcl "Tcl Built-In Commands"
@@ -15,18 +15,26 @@
.SH NAME
regsub \- Perform substitutions based on regular expression pattern matching
.SH SYNOPSIS
-\fBregsub \fR?\fIswitches\fR? \fIexp string subSpec varName\fR
+.VS 8.4
+\fBregsub \fR?\fIswitches\fR? \fIexp string subSpec \fR?\fIvarName\fR?
+.VE 8.4
.BE
.SH DESCRIPTION
.PP
This command matches the regular expression \fIexp\fR against
\fIstring\fR,
-and it copies \fIstring\fR to the variable whose name is
-given by \fIvarName\fR.
+.VS 8.4
+and either copies \fIstring\fR to the variable whose name is
+given by \fIvarName\fR or returns \fIstring\fR if \fIvarName\fR is not
+present.
+.VE 8.4
(Regular expression matching is described in the \fBre_syntax\fR
reference page.)
If there is a match, then while copying \fIstring\fR to \fIvarName\fR
+.VS 8.4
+(or to the result of this command if \fIvarName\fR is not present)
+.VE 8.4
the portion of \fIstring\fR that
matched \fIexp\fR is replaced with \fIsubSpec\fR.
If \fIsubSpec\fR contains a ``&'' or ``\e0'', then it is replaced
@@ -87,7 +95,6 @@ manual page).
Upper-case characters in \fIstring\fR will be converted to lower-case
before matching against \fIexp\fR; however, substitutions specified
by \fIsubSpec\fR use the original unconverted form of \fIstring\fR.
-.VS 8.3
.TP 10
\fB\-start\fR \fIindex\fR
Specifies a character index offset into the string to start
@@ -95,14 +102,16 @@ 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 \fIindex\fR.
\fIindex\fR will be constrained to the bounds of the input string.
-.VE 8.3
.TP 10
\fB\-\|\-\fR
Marks the end of switches. The argument following this one will
be treated as \fIexp\fR even if it starts with a \fB\-\fR.
.PP
-The command returns a count of the number of matching ranges that
-were found and replaced.
+.VS 8.4
+If \fIvarName\fR 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.
+.VE 8.4
See the manual entry for \fBregexp\fR for details on the interpretation
of regular expressions.