summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorhobbs <hobbs>2001-11-14 23:15:33 (GMT)
committerhobbs <hobbs>2001-11-14 23:15:33 (GMT)
commitc4f80ca2b57a0c80444e363fcb0aff8d3ff410dd (patch)
tree6eae5fde2936d7274d72057a8ce6673677633e54
parentae9e4081d57d307c56ac7581dcb3b66f9bb0c4d4 (diff)
downloadtcl-c4f80ca2b57a0c80444e363fcb0aff8d3ff410dd.zip
tcl-c4f80ca2b57a0c80444e363fcb0aff8d3ff410dd.tar.gz
tcl-c4f80ca2b57a0c80444e363fcb0aff8d3ff410dd.tar.bz2
added lset.n lset docs with xref and updated lindex of TIPs#22,33,45 by Kenny
-rw-r--r--doc/lappend.n9
-rw-r--r--doc/lindex.n69
-rw-r--r--doc/linsert.n9
-rw-r--r--doc/list.n9
-rw-r--r--doc/llength.n8
-rw-r--r--doc/lrange.n8
-rw-r--r--doc/lreplace.n9
-rw-r--r--doc/lsearch.n9
-rwxr-xr-xdoc/lset.n107
-rw-r--r--doc/lsort.n9
10 files changed, 219 insertions, 27 deletions
diff --git a/doc/lappend.n b/doc/lappend.n
index d9a3375..c95fdcf 100644
--- a/doc/lappend.n
+++ b/doc/lappend.n
@@ -1,11 +1,12 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: lappend.n,v 1.4 2000/09/07 14:27:48 poenitz Exp $
+'\" RCS: @(#) $Id: lappend.n,v 1.5 2001/11/14 23:15:33 hobbs Exp $
'\"
.so man.macros
.TH lappend n "" Tcl "Tcl Built-In Commands"
@@ -32,7 +33,11 @@ more efficient than ``\fBset a [concat $a [list $b]]\fR'' when
\fB$a\fR is long.
.SH "SEE ALSO"
-list(n), lindex(n), linsert(n), llength(n), lsort(n), lrange(n)
+list(n), lindex(n), linsert(n), llength(n),
+.VS 8.4
+lset(n)
+.VE
+lsort(n), lrange(n)
.SH KEYWORDS
append, element, list, variable
diff --git a/doc/lindex.n b/doc/lindex.n
index 904952e..81e8bd0 100644
--- a/doc/lindex.n
+++ b/doc/lindex.n
@@ -1,27 +1,47 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 2001 by Kevin B. Kenny. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: lindex.n,v 1.6 2000/09/07 14:27:49 poenitz Exp $
+'\" RCS: @(#) $Id: lindex.n,v 1.7 2001/11/14 23:15:33 hobbs Exp $
'\"
.so man.macros
-.TH lindex n 8.2 Tcl "Tcl Built-In Commands"
+.TH lindex n 8.4 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
lindex \- Retrieve an element from a list
.SH SYNOPSIS
-\fBlindex \fIlist index\fR
+\fBlindex \fIlist ?index...?\fR
.BE
-
.SH DESCRIPTION
.PP
-This command treats \fIlist\fR as a Tcl list and returns the
+.VS 8.4
+The \fBlindex\fP command accepts a parameter, \fIlist\fP, which
+it treats as a Tcl list. It also accepts zero or more \fIindices\fP into
+the list. The indices may be presented either consecutively on the
+command line, or grouped in a
+Tcl list and presented as a single argument.
+.PP
+If no indices are presented, the command takes the form:
+.CS
+lindex list
+.CE
+or
+.CS
+lindex list {}
+.CE
+In this case, the return value of \fBlindex\fR is simply the value of the
+\fIlist\fR parameter.
+.PP
+When presented with a single index, the \fBlindex\fR command
+treats \fIlist\fR as a Tcl list and returns the
+.VE
\fIindex\fR'th element from it (0 refers to the first element of the list).
-In extracting the element, \fIlindex\fR observes the same rules
+In extracting the element, \fBlindex\fR observes the same rules
concerning braces and quotes and backslashes as the Tcl command
interpreter; however, variable
substitution and command substitution do not occur.
@@ -31,9 +51,42 @@ string is returned.
If \fIindex\fR has the value \fBend\fR, it refers to the last element
in the list, and \fBend\-\fIinteger\fR refers to the last element in
the list minus the specified integer offset.
-
+.PP
+.VS 8.4
+If additional \fIindex\fR arguments are supplied, then each argument is
+used in turn to select an element from the previous indexing operation,
+allowing the script to select elements from sublists. The command,
+.CS
+lindex $a 1 2 3
+.CE
+or
+.CS
+lindex $a {1 2 3}
+.CE
+is synonymous with
+.CS
+lindex [lindex [lindex $a 1] 2] 3
+.CE
+.SH EXAMPLES
+.CS
+lindex {a b c} => a b c
+lindex {a b c} {} => a b c
+lindex {a b c} 0 => a
+lindex {a b c} 2 => c
+lindex {a b c} end => c
+lindex {a b c} end-1 => b
+lindex {{a b c} {d e f} {g h i}} 2 1 => h
+lindex {{a b c} {d e f} {g h i}} {2 1} => h
+lindex {{{a b} {c d}} {{e f} {g h}}} 1 1 0 => g
+lindex {{{a b} {c d}} {{e f} {g h}}} {1 1 0} => g
+.CE
+.VE
.SH "SEE ALSO"
-list(n), lappend(n), linsert(n), llength(n), lsearch(n), lsort(n),
+list(n), lappend(n), linsert(n), llength(n), lsearch(n),
+.VS 8.4
+lset(n),
+.VE
+lsort(n),
lrange(n), lreplace(n)
.SH KEYWORDS
diff --git a/doc/linsert.n b/doc/linsert.n
index f306441..98fd374 100644
--- a/doc/linsert.n
+++ b/doc/linsert.n
@@ -1,11 +1,12 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: linsert.n,v 1.5 2000/09/07 14:27:49 poenitz Exp $
+'\" RCS: @(#) $Id: linsert.n,v 1.6 2001/11/14 23:15:33 hobbs Exp $
'\"
.so man.macros
.TH linsert n 8.2 Tcl "Tcl Built-In Commands"
@@ -29,8 +30,12 @@ elements in the list, then the new elements are appended to the list.
\fBend\-\fIinteger\fR refers to the last element in the list minus the
specified integer offset.
+
.SH "SEE ALSO"
-list(n), lappend(n), llength(n)
+.VS 8.4
+list(n), lappend(n), lindex(n), llength(n), lsearch(n),
+lset(n), lsort(n), lrange(n), lreplace(n)
+.VE
.SH KEYWORDS
element, insert, list
diff --git a/doc/list.n b/doc/list.n
index 824a473..32305ad 100644
--- a/doc/list.n
+++ b/doc/list.n
@@ -1,11 +1,12 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: list.n,v 1.4 2000/09/07 14:27:49 poenitz Exp $
+'\" RCS: @(#) $Id: list.n,v 1.5 2001/11/14 23:15:33 hobbs Exp $
'\"
.so man.macros
.TH list n "" Tcl "Tcl Built-In Commands"
@@ -42,7 +43,11 @@ while \fBconcat\fR with the same arguments will return
.CE
.SH "SEE ALSO"
-lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), lsort(n),
+lappend(n), lindex(n), linsert(n), llength(n), lsearch(n),
+.VS 8.4
+lset(n),
+.VE
+lsort(n),
lrange(n), lreplace(n)
.SH KEYWORDS
diff --git a/doc/llength.n b/doc/llength.n
index 163af67..591dc23 100644
--- a/doc/llength.n
+++ b/doc/llength.n
@@ -1,11 +1,12 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: llength.n,v 1.4 2000/09/07 14:27:49 poenitz Exp $
+'\" RCS: @(#) $Id: llength.n,v 1.5 2001/11/14 23:15:33 hobbs Exp $
'\"
.so man.macros
.TH llength n "" Tcl "Tcl Built-In Commands"
@@ -23,7 +24,10 @@ Treats \fIlist\fR as a list and returns a decimal string giving
the number of elements in it.
.SH "SEE ALSO"
-list(n), lindex(n), lrange(n)
+.VS 8.4
+list(n), lappend(n), lindex(n), linsert(n), lsearch(n),
+lset(n), lsort(n), lrange(n), lreplace(n)
+.VE
.SH KEYWORDS
element, list, length
diff --git a/doc/lrange.n b/doc/lrange.n
index e937cf4..73a3419 100644
--- a/doc/lrange.n
+++ b/doc/lrange.n
@@ -1,11 +1,12 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: lrange.n,v 1.4 2000/09/07 14:27:49 poenitz Exp $
+'\" RCS: @(#) $Id: lrange.n,v 1.5 2001/11/14 23:15:33 hobbs Exp $
'\"
.so man.macros
.TH lrange n 7.4 Tcl "Tcl Built-In Commands"
@@ -36,7 +37,10 @@ for simple fields that aren't enclosed in braces); it does, however,
produce exactly the same results as ``\fBlist [lindex \fIlist first\fB]\fR''
.SH "SEE ALSO"
-lappend(n), lindex(n), linsert(n), list(n), llength(n), lreplace(n)
+.VS 8.4
+list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n),
+lset(n), lreplace(n), lsort(n)
+.VE
.SH KEYWORDS
element, list, range, sublist
diff --git a/doc/lreplace.n b/doc/lreplace.n
index ad84672..92dcad7 100644
--- a/doc/lreplace.n
+++ b/doc/lreplace.n
@@ -1,11 +1,12 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: lreplace.n,v 1.6 2000/09/07 14:27:49 poenitz Exp $
+'\" RCS: @(#) $Id: lreplace.n,v 1.7 2001/11/14 23:15:33 hobbs Exp $
'\"
.so man.macros
.TH lreplace n 7.4 Tcl "Tcl Built-In Commands"
@@ -44,8 +45,10 @@ between \fIfirst\fR and \fIlast\fR are simply deleted. If \fIlist\fR
is empty, any \fIelement\fR arguments are added to the end of the list.
.SH "SEE ALSO"
-lappend(n), lindex(n), linsert(n), list(n), llength(n), lrange(n),
-lsearch(n), lsort(n)
+.VS 8.4
+list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n),
+lset(n), lrange(n), lsort(n)
+.VE
.SH KEYWORDS
element, list, replace
diff --git a/doc/lsearch.n b/doc/lsearch.n
index 4898b4e..16b3ce2 100644
--- a/doc/lsearch.n
+++ b/doc/lsearch.n
@@ -1,11 +1,12 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: lsearch.n,v 1.7 2001/09/10 22:51:40 hobbs Exp $
+'\" RCS: @(#) $Id: lsearch.n,v 1.8 2001/11/14 23:15:33 hobbs Exp $
'\"
.so man.macros
.TH lsearch n 8.4 Tcl "Tcl Built-In Commands"
@@ -79,8 +80,10 @@ last takes precendence. If more than one of \fB\-increasing\fR and
\fB\-decreasing\fR is specified, the option specified last takes precedence.
.SH "SEE ALSO"
-lappend(n), lindex(n), linsert(n), list(n), llength(n), lrange(n),
-lreplace(n), lsort(n)
+.VS 8.4
+list(n), lappend(n), lindex(n), linsert(n), llength(n),
+lset(n), lsort(n), lrange(n), lreplace(n)
+.VE
.SH KEYWORDS
list, match, pattern, regular expression, search, string
diff --git a/doc/lset.n b/doc/lset.n
new file mode 100755
index 0000000..38517a1
--- /dev/null
+++ b/doc/lset.n
@@ -0,0 +1,107 @@
+.\" Copyright (c) 2001 by Kevin B. Kenny. All rights reserved.
+.\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" RCS: @(#) $Id: lset.n,v 1.1 2001/11/14 23:15:33 hobbs Exp $
+'\"
+.so man.macros
+.TH lset n 8.4 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+lset \- Change an element in a list
+.SH SYNOPSIS
+\fBlset \fIlist ?index...? newValue\fR
+.BE
+.SH DESCRIPTION
+.PP
+The \fBlset\fP command accepts a parameter, \fIlist\fP, which
+it interprets as the name of a variable containing a Tcl list.
+It also accepts zero or more \fIindices\fP into
+the list. The indices may be presented either consecutively on the
+command line, or grouped in a
+Tcl list and presented as a single argument.
+Finally, it acccepts a new value for an element of \fIlist\fP.
+.PP
+If no indices are presented, the command takes the form:
+.CS
+lset list newValue
+.CE
+or
+.CS
+lset list {} newValue
+.CE
+In this case, \fInewValue\fP replaces the old value of the variable \fIlist\fP.
+.PP
+When presented with a single index, the \fBlset\fR command
+treats the content of the \fIlist\fR variable as a Tcl list.
+It addresses the \fIindex\fR'th element in it
+(0 refers to the first element of the list).
+When interpreting the list, \fBlset\fR observes the same rules
+concerning braces and quotes and backslashes as the Tcl command
+interpreter; however, variable
+substitution and command substitution do not occur.
+The command constructs a new list in which the designated element is
+replaced with \fInewValue\fP. This new list is stored in the
+variable \fIlist\fP, and is also the return value from the \fBlset\fP
+command.
+.PP
+If \fIindex\fR is negative or greater than or equal to the number
+of elements in \fI$list\fR, then an error occurs.
+.PP
+If \fIindex\fR has the value \fBend\fR, it refers to the last element
+in the list, and \fBend\-\fIinteger\fR refers to the last element in
+the list minus the specified integer offset.
+.PP
+If additional \fIindex\fR arguments are supplied, then each argument is
+used in turn to address an element within a sublist designated
+by the previous indexing operation,
+allowing the script to alter elements in sublists. The command,
+.CS
+lset a 1 2 newValue
+.CE
+or
+.CS
+lset a {1 2} newValue
+.CE
+replaces element 2 of sublist 1 with \fInewValue\fP.
+.PP
+The integer appearing in each \fIindex\fR argument must be greater
+than or equal to zero. The integer appearing in each \fIindex\fR
+argument must be strictly less than the length of the corresponding
+list. In other words, the \fBlset\fR command cannot change the size
+of a list. If an index is outside the permitted range, an error is reported.
+.SH EXAMPLES
+In each of these examples, the initial value of \fIx\fP is:
+.CS
+{a b c} {d e f} {g h i}
+.CE
+The indicated return value also becomes the new value of \fIx\fP.
+.CS
+lset x {j k l} => j k l
+lset x {} {j k l} => j k l
+lset x 0 j => j {d e f} {g h i}
+lset x 2 j => {a b c} {d e f} j
+lset x end j => {a b c} {d e f} j
+lset x end-1 j => {a b c} j {d e f}
+lset x 2 1 j => {a b c} {d e f} {g j i}
+lset x {2 1} j => {a b c} {d e f} {g j i}
+lset x {2 3} j
+.CE
+In the following examples, the initial value of \fIx\fP is:
+.CS
+{{a b} {c d}} {{e f} {g h}}
+.CE
+The indicated return value also becomes the new value of \fIx\fP.
+.CS
+lset x 1 1 0 j => {{a b} {c d}} {{e f} {j h}}
+lset x {1 1 0} j => {{a b} {c d}} {{e f} {j h}}
+.CE
+.SH "SEE ALSO"
+list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n),
+lsort(n), lrange(n), lreplace(n)
+
+.SH KEYWORDS
+element, index, list, replace, set
+.VE
diff --git a/doc/lsort.n b/doc/lsort.n
index 67f7f09..1278100 100644
--- a/doc/lsort.n
+++ b/doc/lsort.n
@@ -2,11 +2,12 @@
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" Copyright (c) 1999 Scriptics Corporation
+.\" Copyright (c) 2001 Kevin B. Kenny. All rights reserved.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: lsort.n,v 1.10 2001/09/28 15:32:17 dkf Exp $
+'\" RCS: @(#) $Id: lsort.n,v 1.11 2001/11/14 23:15:33 hobbs Exp $
'\"
.so man.macros
.TH lsort n 8.3 Tcl "Tcl Built-In Commands"
@@ -184,8 +185,10 @@ More complex sorting using a comparison function:
.CE
.SH "SEE ALSO"
-lappend(n), lindex(n), linsert(n), list(n), llength(n), lrange(n),
-lreplace(n), lsearch(n)
+.VS 8.4
+list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n),
+lset(n), lrange(n), lreplace(n)
+.VE
.SH KEYWORDS
element, list, order, sort