diff options
Diffstat (limited to 'doc/lindex.n')
| -rw-r--r-- | doc/lindex.n | 69 |
1 files changed, 61 insertions, 8 deletions
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 |