diff options
| -rw-r--r-- | doc/lappend.n | 9 | ||||
| -rw-r--r-- | doc/lindex.n | 69 | ||||
| -rw-r--r-- | doc/linsert.n | 9 | ||||
| -rw-r--r-- | doc/list.n | 9 | ||||
| -rw-r--r-- | doc/llength.n | 8 | ||||
| -rw-r--r-- | doc/lrange.n | 8 | ||||
| -rw-r--r-- | doc/lreplace.n | 9 | ||||
| -rw-r--r-- | doc/lsearch.n | 9 | ||||
| -rwxr-xr-x | doc/lset.n | 107 | ||||
| -rw-r--r-- | doc/lsort.n | 9 |
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 @@ -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 |