util/src/TclTk/tcl8.6.12/doc/lindex.n

   1 '\"
   2 '\" Copyright (c) 1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\" Copyright (c) 2001 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 .TH lindex n 8.4 Tcl "Tcl Built-In Commands"
  10 .so man.macros
  11 .BS
  12 '\" Note:  do not modify the .SH NAME line immediately below!
  13 .SH NAME
  14 lindex \- Retrieve an element from a list
  15 .SH SYNOPSIS
  16 \fBlindex \fIlist ?index ...?\fR
  17 .BE
  18 .SH DESCRIPTION
  19 .PP
  20 The \fBlindex\fR command accepts a parameter, \fIlist\fR, which
  21 it treats as a Tcl list. It also accepts zero or more \fIindices\fR into
  22 the list.  The indices may be presented either consecutively on the
  23 command line, or grouped in a
  24 Tcl list and presented as a single argument.
  25 .PP
  26 If no indices are presented, the command takes the form:
  27 .PP
  28 .CS
  29 \fBlindex \fIlist\fR
  30 .CE
  31 .PP
  32 or
  33 .PP
  34 .CS
  35 \fBlindex \fIlist\fR {}
  36 .CE
  37 .PP
  38 In this case, the return value of \fBlindex\fR is simply the value of the
  39 \fIlist\fR parameter.
  40 .PP
  41 When presented with a single index, the \fBlindex\fR command
  42 treats \fIlist\fR as a Tcl list and returns the
  43 \fIindex\fR'th element from it (0 refers to the first element of the list).
  44 In extracting the element, \fBlindex\fR observes the same rules
  45 concerning braces and quotes and backslashes as the Tcl command
  46 interpreter; however, variable
  47 substitution and command substitution do not occur.
  48 If \fIindex\fR is negative or greater than or equal to the number
  49 of elements in \fIvalue\fR, then an empty
  50 string is returned.
  51 The interpretation of each simple \fIindex\fR value is the same as
  52 for the command \fBstring index\fR, supporting simple index
  53 arithmetic and indices relative to the end of the list.
  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 .PP
  59 .CS
  60 \fBlindex\fR $a 1 2 3
  61 .CE
  62 .PP
  63 or
  64 .PP
  65 .CS
  66 \fBlindex\fR $a {1 2 3}
  67 .CE
  68 .PP
  69 is synonymous with
  70 .PP
  71 .CS
  72 \fBlindex\fR [\fBlindex\fR [\fBlindex\fR $a 1] 2] 3
  73 .CE
  74 .SH EXAMPLES
  75 .PP
  76 Lists can be indexed into from either end:
  77 .PP
  78 .CS
  79 \fBlindex\fR {a b c} 0
  80       \fI\(-> a\fR
  81 \fBlindex\fR {a b c} 2
  82       \fI\(-> c\fR
  83 \fBlindex\fR {a b c} end
  84       \fI\(-> c\fR
  85 \fBlindex\fR {a b c} end-1
  86       \fI\(-> b\fR
  87 .CE
  88 .PP
  89 Lists or sequences of indices allow selection into lists of lists:
  90 .PP
  91 .CS
  92 \fBlindex\fR {a b c}
  93       \fI\(-> a b c\fR
  94 \fBlindex\fR {a b c} {}
  95       \fI\(-> a b c\fR
  96 \fBlindex\fR {{a b c} {d e f} {g h i}} 2 1
  97       \fI\(-> h\fR
  98 \fBlindex\fR {{a b c} {d e f} {g h i}} {2 1}
  99       \fI\(-> h\fR
 100 \fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} 1 1 0
 101       \fI\(-> g\fR
 102 \fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} {1 1 0}
 103       \fI\(-> g\fR
 104 .CE
 105 .PP
 106 List indices may also perform limited computation, adding or subtracting fixed
 107 amounts from other indices:
 108 .PP
 109 .CS
 110 set idx 1
 111 \fBlindex\fR {a b c d e f} $idx+2
 112       \fI\(-> d\fR
 113 set idx 3
 114 \fBlindex\fR {a b c d e f} $idx+2
 115       \fI\(-> f\fR
 116 .CE
 117 .SH "SEE ALSO"
 118 list(n), lappend(n), linsert(n), llength(n), lsearch(n),
 119 lset(n), lsort(n), lrange(n), lreplace(n),
 120 string(n)
 121 .SH KEYWORDS
 122 element, index, list
 123 '\"Local Variables:
 124 '\"mode: nroff
 125 '\"End: