1 | '\" |
---|
2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved. |
---|
5 | '\" |
---|
6 | '\" See the file "license.terms" for information on usage and redistribution |
---|
7 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
8 | '\" |
---|
9 | '\" RCS: @(#) $Id: lindex.n,v 1.17 2008/03/26 09:59:22 dkf Exp $ |
---|
10 | '\" |
---|
11 | .so man.macros |
---|
12 | .TH lindex n 8.4 Tcl "Tcl Built-In Commands" |
---|
13 | .BS |
---|
14 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
15 | .SH NAME |
---|
16 | lindex \- Retrieve an element from a list |
---|
17 | .SH SYNOPSIS |
---|
18 | \fBlindex \fIlist ?index...?\fR |
---|
19 | .BE |
---|
20 | .SH DESCRIPTION |
---|
21 | .PP |
---|
22 | The \fBlindex\fR command accepts a parameter, \fIlist\fR, which |
---|
23 | it treats as a Tcl list. It also accepts zero or more \fIindices\fR into |
---|
24 | the list. The indices may be presented either consecutively on the |
---|
25 | command line, or grouped in a |
---|
26 | Tcl list and presented as a single argument. |
---|
27 | .PP |
---|
28 | If no indices are presented, the command takes the form: |
---|
29 | .CS |
---|
30 | lindex list |
---|
31 | .CE |
---|
32 | or |
---|
33 | .CS |
---|
34 | lindex list {} |
---|
35 | .CE |
---|
36 | In this case, the return value of \fBlindex\fR is simply the value of the |
---|
37 | \fIlist\fR parameter. |
---|
38 | .PP |
---|
39 | When presented with a single index, the \fBlindex\fR command |
---|
40 | treats \fIlist\fR as a Tcl list and returns the |
---|
41 | \fIindex\fR'th element from it (0 refers to the first element of the list). |
---|
42 | In extracting the element, \fBlindex\fR observes the same rules |
---|
43 | concerning braces and quotes and backslashes as the Tcl command |
---|
44 | interpreter; however, variable |
---|
45 | substitution and command substitution do not occur. |
---|
46 | If \fIindex\fR is negative or greater than or equal to the number |
---|
47 | of elements in \fIvalue\fR, then an empty |
---|
48 | string is returned. |
---|
49 | .VS 8.5 |
---|
50 | The interpretation of each simple \fIindex\fR value is the same as |
---|
51 | for the command \fBstring index\fR, supporting simple index |
---|
52 | arithmetic and indices relative to the end of the list. |
---|
53 | .VE 8.5 |
---|
54 | .PP |
---|
55 | If additional \fIindex\fR arguments are supplied, then each argument is |
---|
56 | used in turn to select an element from the previous indexing operation, |
---|
57 | allowing the script to select elements from sublists. The command, |
---|
58 | .CS |
---|
59 | lindex $a 1 2 3 |
---|
60 | .CE |
---|
61 | or |
---|
62 | .CS |
---|
63 | lindex $a {1 2 3} |
---|
64 | .CE |
---|
65 | is synonymous with |
---|
66 | .CS |
---|
67 | lindex [lindex [lindex $a 1] 2] 3 |
---|
68 | .CE |
---|
69 | .SH EXAMPLES |
---|
70 | .CS |
---|
71 | \fBlindex\fR {a b c} |
---|
72 | \fI\(-> a b c\fR |
---|
73 | \fBlindex\fR {a b c} {} |
---|
74 | \fI\(-> a b c\fR |
---|
75 | \fBlindex\fR {a b c} 0 |
---|
76 | \fI\(-> a\fR |
---|
77 | \fBlindex\fR {a b c} 2 |
---|
78 | \fI\(-> c\fR |
---|
79 | \fBlindex\fR {a b c} end |
---|
80 | \fI\(-> c\fR |
---|
81 | \fBlindex\fR {a b c} end-1 |
---|
82 | \fI\(-> b\fR |
---|
83 | \fBlindex\fR {{a b c} {d e f} {g h i}} 2 1 |
---|
84 | \fI\(-> h\fR |
---|
85 | \fBlindex\fR {{a b c} {d e f} {g h i}} {2 1} |
---|
86 | \fI\(-> h\fR |
---|
87 | \fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} 1 1 0 |
---|
88 | \fI\(-> g\fR |
---|
89 | \fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} {1 1 0} |
---|
90 | \fI\(-> g\fR |
---|
91 | .CE |
---|
92 | .SH "SEE ALSO" |
---|
93 | list(n), lappend(n), linsert(n), llength(n), lsearch(n), |
---|
94 | lset(n), lsort(n), lrange(n), lreplace(n), |
---|
95 | .VS 8.5 |
---|
96 | string(n) |
---|
97 | .VE |
---|
98 | |
---|
99 | .SH KEYWORDS |
---|
100 | element, index, list |
---|