util/X86LINUX64/man/mann/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 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 .TH lindex n 8.4 Tcl "Tcl Built-In Commands"
  10 .\" The -*- nroff -*- definitions below are for supplemental macros used
  11 .\" in Tcl/Tk manual entries.
  12 .\"
  13 .\" .AP type name in/out ?indent?
  14 .\"     Start paragraph describing an argument to a library procedure.
  15 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  16 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  17 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  18 .\"     needed;  use .AS below instead)
  19 .\"
  20 .\" .AS ?type? ?name?
  21 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  22 .\"     name are examples of largest possible arguments that will be passed
  23 .\"     to .AP later.  If args are omitted, default tab stops are used.
  24 .\"
  25 .\" .BS
  26 .\"     Start box enclosure.  From here until next .BE, everything will be
  27 .\"     enclosed in one large box.
  28 .\"
  29 .\" .BE
  30 .\"     End of box enclosure.
  31 .\"
  32 .\" .CS
  33 .\"     Begin code excerpt.
  34 .\"
  35 .\" .CE
  36 .\"     End code excerpt.
  37 .\"
  38 .\" .VS ?version? ?br?
  39 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  40 .\"     of man pages.  The first argument is ignored and used for recording
  41 .\"     the version when the .VS was added, so that the sidebars can be
  42 .\"     found and removed when they reach a certain age.  If another argument
  43 .\"     is present, then a line break is forced before starting the sidebar.
  44 .\"
  45 .\" .VE
  46 .\"     End of vertical sidebar.
  47 .\"
  48 .\" .DS
  49 .\"     Begin an indented unfilled display.
  50 .\"
  51 .\" .DE
  52 .\"     End of indented unfilled display.
  53 .\"
  54 .\" .SO ?manpage?
  55 .\"     Start of list of standard options for a Tk widget. The manpage
  56 .\"     argument defines where to look up the standard options; if
  57 .\"     omitted, defaults to "options". The options follow on successive
  58 .\"     lines, in three columns separated by tabs.
  59 .\"
  60 .\" .SE
  61 .\"     End of list of standard options for a Tk widget.
  62 .\"
  63 .\" .OP cmdName dbName dbClass
  64 .\"     Start of description of a specific option.  cmdName gives the
  65 .\"     option's name as specified in the class command, dbName gives
  66 .\"     the option's name in the option database, and dbClass gives
  67 .\"     the option's class in the option database.
  68 .\"
  69 .\" .UL arg1 arg2
  70 .\"     Print arg1 underlined, then print arg2 normally.
  71 .\"
  72 .\" .QW arg1 ?arg2?
  73 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  74 .\"
  75 .\" .PQ arg1 ?arg2?
  76 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  77 .\"     (for trailing punctuation) and then a closing parenthesis.
  78 .\"
  79 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  80 .if t .wh -1.3i ^B
  81 .nr ^l \n(.l
  82 .ad b
  83 .\"     # Start an argument description
  84 .de AP
  85 .ie !"\\$4"" .TP \\$4
  86 .el \{\
  87 .   ie !"\\$2"" .TP \\n()Cu
  88 .   el          .TP 15
  89 .\}
  90 .ta \\n()Au \\n()Bu
  91 .ie !"\\$3"" \{\
  92 \&\\$1 \\fI\\$2\\fP (\\$3)
  93 .\".b
  94 .\}
  95 .el \{\
  96 .br
  97 .ie !"\\$2"" \{\
  98 \&\\$1  \\fI\\$2\\fP
  99 .\}
 100 .el \{\
 101 \&\\fI\\$1\\fP
 102 .\}
 103 .\}
 104 ..
 105 .\"     # define tabbing values for .AP
 106 .de AS
 107 .nr )A 10n
 108 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 109 .nr )B \\n()Au+15n
 110 .\"
 111 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 112 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 113 ..
 114 .AS Tcl_Interp Tcl_CreateInterp in/out
 115 .\"     # BS - start boxed text
 116 .\"     # ^y = starting y location
 117 .\"     # ^b = 1
 118 .de BS
 119 .br
 120 .mk ^y
 121 .nr ^b 1u
 122 .if n .nf
 123 .if n .ti 0
 124 .if n \l'\\n(.lu\(ul'
 125 .if n .fi
 126 ..
 127 .\"     # BE - end boxed text (draw box now)
 128 .de BE
 129 .nf
 130 .ti 0
 131 .mk ^t
 132 .ie n \l'\\n(^lu\(ul'
 133 .el \{\
 134 .\"     Draw four-sided box normally, but don't draw top of
 135 .\"     box if the box started on an earlier page.
 136 .ie !\\n(^b-1 \{\
 137 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 138 .\}
 139 .el \}\
 140 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 141 .\}
 142 .\}
 143 .fi
 144 .br
 145 .nr ^b 0
 146 ..
 147 .\"     # VS - start vertical sidebar
 148 .\"     # ^Y = starting y location
 149 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 150 .de VS
 151 .if !"\\$2"" .br
 152 .mk ^Y
 153 .ie n 'mc \s12\(br\s0
 154 .el .nr ^v 1u
 155 ..
 156 .\"     # VE - end of vertical sidebar
 157 .de VE
 158 .ie n 'mc
 159 .el \{\
 160 .ev 2
 161 .nf
 162 .ti 0
 163 .mk ^t
 164 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 165 .sp -1
 166 .fi
 167 .ev
 168 .\}
 169 .nr ^v 0
 170 ..
 171 .\"     # Special macro to handle page bottom:  finish off current
 172 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 173 .\"     # page bottom macro.
 174 .de ^B
 175 .ev 2
 176 'ti 0
 177 'nf
 178 .mk ^t
 179 .if \\n(^b \{\
 180 .\"     Draw three-sided box if this is the box's first page,
 181 .\"     draw two sides but no top otherwise.
 182 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 183 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 184 .\}
 185 .if \\n(^v \{\
 186 .nr ^x \\n(^tu+1v-\\n(^Yu
 187 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 188 .\}
 189 .bp
 190 'fi
 191 .ev
 192 .if \\n(^b \{\
 193 .mk ^y
 194 .nr ^b 2
 195 .\}
 196 .if \\n(^v \{\
 197 .mk ^Y
 198 .\}
 199 ..
 200 .\"     # DS - begin display
 201 .de DS
 202 .RS
 203 .nf
 204 .sp
 205 ..
 206 .\"     # DE - end display
 207 .de DE
 208 .fi
 209 .RE
 210 .sp
 211 ..
 212 .\"     # SO - start of list of standard options
 213 .de SO
 214 'ie '\\$1'' .ds So \\fBoptions\\fR
 215 'el .ds So \\fB\\$1\\fR
 216 .SH "STANDARD OPTIONS"
 217 .LP
 218 .nf
 219 .ta 5.5c 11c
 220 .ft B
 221 ..
 222 .\"     # SE - end of list of standard options
 223 .de SE
 224 .fi
 225 .ft R
 226 .LP
 227 See the \\*(So manual entry for details on the standard options.
 228 ..
 229 .\"     # OP - start of full description for a single option
 230 .de OP
 231 .LP
 232 .nf
 233 .ta 4c
 234 Command-Line Name:      \\fB\\$1\\fR
 235 Database Name:  \\fB\\$2\\fR
 236 Database Class: \\fB\\$3\\fR
 237 .fi
 238 .IP
 239 ..
 240 .\"     # CS - begin code excerpt
 241 .de CS
 242 .RS
 243 .nf
 244 .ta .25i .5i .75i 1i
 245 ..
 246 .\"     # CE - end code excerpt
 247 .de CE
 248 .fi
 249 .RE
 250 ..
 251 .\"     # UL - underline word
 252 .de UL
 253 \\$1\l'|0\(ul'\\$2
 254 ..
 255 .\"     # QW - apply quotation marks to word
 256 .de QW
 257 .ie '\\*(lq'"' ``\\$1''\\$2
 258 .\"" fix emacs highlighting
 259 .el \\*(lq\\$1\\*(rq\\$2
 260 ..
 261 .\"     # PQ - apply parens and quotation marks to word
 262 .de PQ
 263 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 264 .\"" fix emacs highlighting
 265 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 266 ..
 267 .\"     # QR - quoted range
 268 .de QR
 269 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 270 .\"" fix emacs highlighting
 271 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 272 ..
 273 .\"     # MT - "empty" string
 274 .de MT
 275 .QW ""
 276 ..
 277 .BS
 278 '\" Note:  do not modify the .SH NAME line immediately below!
 279 .SH NAME
 280 lindex \- Retrieve an element from a list
 281 .SH SYNOPSIS
 282 \fBlindex \fIlist ?index ...?\fR
 283 .BE
 284 .SH DESCRIPTION
 285 .PP
 286 The \fBlindex\fR command accepts a parameter, \fIlist\fR, which
 287 it treats as a Tcl list. It also accepts zero or more \fIindices\fR into
 288 the list.  The indices may be presented either consecutively on the
 289 command line, or grouped in a
 290 Tcl list and presented as a single argument.
 291 .PP
 292 If no indices are presented, the command takes the form:
 293 .PP
 294 .CS
 295 \fBlindex \fIlist\fR
 296 .CE
 297 .PP
 298 or
 299 .PP
 300 .CS
 301 \fBlindex \fIlist\fR {}
 302 .CE
 303 .PP
 304 In this case, the return value of \fBlindex\fR is simply the value of the
 305 \fIlist\fR parameter.
 306 .PP
 307 When presented with a single index, the \fBlindex\fR command
 308 treats \fIlist\fR as a Tcl list and returns the
 309 \fIindex\fR'th element from it (0 refers to the first element of the list).
 310 In extracting the element, \fBlindex\fR observes the same rules
 311 concerning braces and quotes and backslashes as the Tcl command
 312 interpreter; however, variable
 313 substitution and command substitution do not occur.
 314 If \fIindex\fR is negative or greater than or equal to the number
 315 of elements in \fIvalue\fR, then an empty
 316 string is returned.
 317 The interpretation of each simple \fIindex\fR value is the same as
 318 for the command \fBstring index\fR, supporting simple index
 319 arithmetic and indices relative to the end of the list.
 320 .PP
 321 If additional \fIindex\fR arguments are supplied, then each argument is
 322 used in turn to select an element from the previous indexing operation,
 323 allowing the script to select elements from sublists.  The command,
 324 .PP
 325 .CS
 326 \fBlindex\fR $a 1 2 3
 327 .CE
 328 .PP
 329 or
 330 .PP
 331 .CS
 332 \fBlindex\fR $a {1 2 3}
 333 .CE
 334 .PP
 335 is synonymous with
 336 .PP
 337 .CS
 338 \fBlindex\fR [\fBlindex\fR [\fBlindex\fR $a 1] 2] 3
 339 .CE
 340 .SH EXAMPLES
 341 .PP
 342 Lists can be indexed into from either end:
 343 .PP
 344 .CS
 345 \fBlindex\fR {a b c} 0
 346       \fI\(-> a\fR
 347 \fBlindex\fR {a b c} 2
 348       \fI\(-> c\fR
 349 \fBlindex\fR {a b c} end
 350       \fI\(-> c\fR
 351 \fBlindex\fR {a b c} end-1
 352       \fI\(-> b\fR
 353 .CE
 354 .PP
 355 Lists or sequences of indices allow selection into lists of lists:
 356 .PP
 357 .CS
 358 \fBlindex\fR {a b c}
 359       \fI\(-> a b c\fR
 360 \fBlindex\fR {a b c} {}
 361       \fI\(-> a b c\fR
 362 \fBlindex\fR {{a b c} {d e f} {g h i}} 2 1
 363       \fI\(-> h\fR
 364 \fBlindex\fR {{a b c} {d e f} {g h i}} {2 1}
 365       \fI\(-> h\fR
 366 \fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} 1 1 0
 367       \fI\(-> g\fR
 368 \fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} {1 1 0}
 369       \fI\(-> g\fR
 370 .CE
 371 .PP
 372 List indices may also perform limited computation, adding or subtracting fixed
 373 amounts from other indices:
 374 .PP
 375 .CS
 376 set idx 1
 377 \fBlindex\fR {a b c d e f} $idx+2
 378       \fI\(-> d\fR
 379 set idx 3
 380 \fBlindex\fR {a b c d e f} $idx+2
 381       \fI\(-> f\fR
 382 .CE
 383 .SH "SEE ALSO"
 384 list(n), lappend(n), linsert(n), llength(n), lsearch(n),
 385 lset(n), lsort(n), lrange(n), lreplace(n),
 386 string(n)
 387 .SH KEYWORDS
 388 element, index, list
 389 '\"Local Variables:
 390 '\"mode: nroff
 391 '\"End: