raw/mann/array.n

   1 '\"
   2 '\" Copyright (c) 1993-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\"
   9 '\" The definitions below are for supplemental macros used in Tcl/Tk
  10 '\" manual entries.
  11 '\"
  12 '\" .AP type name in/out ?indent?
  13 '\"     Start paragraph describing an argument to a library procedure.
  14 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  15 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  16 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  17 '\"     needed;  use .AS below instead)
  18 '\"
  19 '\" .AS ?type? ?name?
  20 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  21 '\"     name are examples of largest possible arguments that will be passed
  22 '\"     to .AP later.  If args are omitted, default tab stops are used.
  23 '\"
  24 '\" .BS
  25 '\"     Start box enclosure.  From here until next .BE, everything will be
  26 '\"     enclosed in one large box.
  27 '\"
  28 '\" .BE
  29 '\"     End of box enclosure.
  30 '\"
  31 '\" .CS
  32 '\"     Begin code excerpt.
  33 '\"
  34 '\" .CE
  35 '\"     End code excerpt.
  36 '\"
  37 '\" .VS ?version? ?br?
  38 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  39 '\"     of man pages.  The first argument is ignored and used for recording
  40 '\"     the version when the .VS was added, so that the sidebars can be
  41 '\"     found and removed when they reach a certain age.  If another argument
  42 '\"     is present, then a line break is forced before starting the sidebar.
  43 '\"
  44 '\" .VE
  45 '\"     End of vertical sidebar.
  46 '\"
  47 '\" .DS
  48 '\"     Begin an indented unfilled display.
  49 '\"
  50 '\" .DE
  51 '\"     End of indented unfilled display.
  52 '\"
  53 '\" .SO
  54 '\"     Start of list of standard options for a Tk widget.  The
  55 '\"     options follow on successive lines, in four columns separated
  56 '\"     by tabs.
  57 '\"
  58 '\" .SE
  59 '\"     End of list of standard options for a Tk widget.
  60 '\"
  61 '\" .OP cmdName dbName dbClass
  62 '\"     Start of description of a specific option.  cmdName gives the
  63 '\"     option's name as specified in the class command, dbName gives
  64 '\"     the option's name in the option database, and dbClass gives
  65 '\"     the option's class in the option database.
  66 '\"
  67 '\" .UL arg1 arg2
  68 '\"     Print arg1 underlined, then print arg2 normally.
  69 '\"
  70 '\"
  71 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  72 .if t .wh -1.3i ^B
  73 .nr ^l \n(.l
  74 .ad b
  75 '\"     # Start an argument description
  76 .de AP
  77 .ie !"\\$4"" .TP \\$4
  78 .el \{\
  79 .   ie !"\\$2"" .TP \\n()Cu
  80 .   el          .TP 15
  81 .\}
  82 .ta \\n()Au \\n()Bu
  83 .ie !"\\$3"" \{\
  84 \&\\$1  \\fI\\$2\\fP    (\\$3)
  85 .\".b
  86 .\}
  87 .el \{\
  88 .br
  89 .ie !"\\$2"" \{\
  90 \&\\$1  \\fI\\$2\\fP
  91 .\}
  92 .el \{\
  93 \&\\fI\\$1\\fP
  94 .\}
  95 .\}
  96 ..
  97 '\"     # define tabbing values for .AP
  98 .de AS
  99 .nr )A 10n
 100 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 101 .nr )B \\n()Au+15n
 102 .\"
 103 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 104 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 105 ..
 106 .AS Tcl_Interp Tcl_CreateInterp in/out
 107 '\"     # BS - start boxed text
 108 '\"     # ^y = starting y location
 109 '\"     # ^b = 1
 110 .de BS
 111 .br
 112 .mk ^y
 113 .nr ^b 1u
 114 .if n .nf
 115 .if n .ti 0
 116 .if n \l'\\n(.lu\(ul'
 117 .if n .fi
 118 ..
 119 '\"     # BE - end boxed text (draw box now)
 120 .de BE
 121 .nf
 122 .ti 0
 123 .mk ^t
 124 .ie n \l'\\n(^lu\(ul'
 125 .el \{\
 126 .\"     Draw four-sided box normally, but don't draw top of
 127 .\"     box if the box started on an earlier page.
 128 .ie !\\n(^b-1 \{\
 129 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 130 .\}
 131 .el \}\
 132 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 133 .\}
 134 .\}
 135 .fi
 136 .br
 137 .nr ^b 0
 138 ..
 139 '\"     # VS - start vertical sidebar
 140 '\"     # ^Y = starting y location
 141 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 142 .de VS
 143 .if !"\\$2"" .br
 144 .mk ^Y
 145 .ie n 'mc \s12\(br\s0
 146 .el .nr ^v 1u
 147 ..
 148 '\"     # VE - end of vertical sidebar
 149 .de VE
 150 .ie n 'mc
 151 .el \{\
 152 .ev 2
 153 .nf
 154 .ti 0
 155 .mk ^t
 156 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 157 .sp -1
 158 .fi
 159 .ev
 160 .\}
 161 .nr ^v 0
 162 ..
 163 '\"     # Special macro to handle page bottom:  finish off current
 164 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 165 '\"     # page bottom macro.
 166 .de ^B
 167 .ev 2
 168 'ti 0
 169 'nf
 170 .mk ^t
 171 .if \\n(^b \{\
 172 .\"     Draw three-sided box if this is the box's first page,
 173 .\"     draw two sides but no top otherwise.
 174 .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
 175 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 176 .\}
 177 .if \\n(^v \{\
 178 .nr ^x \\n(^tu+1v-\\n(^Yu
 179 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 180 .\}
 181 .bp
 182 'fi
 183 .ev
 184 .if \\n(^b \{\
 185 .mk ^y
 186 .nr ^b 2
 187 .\}
 188 .if \\n(^v \{\
 189 .mk ^Y
 190 .\}
 191 ..
 192 '\"     # DS - begin display
 193 .de DS
 194 .RS
 195 .nf
 196 .sp
 197 ..
 198 '\"     # DE - end display
 199 .de DE
 200 .fi
 201 .RE
 202 .sp
 203 ..
 204 '\"     # SO - start of list of standard options
 205 .de SO
 206 .SH "STANDARD OPTIONS"
 207 .LP
 208 .nf
 209 .ta 5.5c 11c
 210 .ft B
 211 ..
 212 '\"     # SE - end of list of standard options
 213 .de SE
 214 .fi
 215 .ft R
 216 .LP
 217 See the \\fBoptions\\fR manual entry for details on the standard options.
 218 ..
 219 '\"     # OP - start of full description for a single option
 220 .de OP
 221 .LP
 222 .nf
 223 .ta 4c
 224 Command-Line Name:      \\fB\\$1\\fR
 225 Database Name:  \\fB\\$2\\fR
 226 Database Class: \\fB\\$3\\fR
 227 .fi
 228 .IP
 229 ..
 230 '\"     # CS - begin code excerpt
 231 .de CS
 232 .RS
 233 .nf
 234 .ta .25i .5i .75i 1i
 235 ..
 236 '\"     # CE - end code excerpt
 237 .de CE
 238 .fi
 239 .RE
 240 ..
 241 .de UL
 242 \\$1\l'|0\(ul'\\$2
 243 ..
 244 .TH array n 8.3 Tcl "Tcl Built-In Commands"
 245 .BS
 246 '\" Note:  do not modify the .SH NAME line immediately below!
 247 .SH NAME
 248 array \- Manipulate array variables
 249 .SH SYNOPSIS
 250 \fBarray \fIoption arrayName\fR ?\fIarg arg ...\fR?
 251 .BE
 252
 253 .SH DESCRIPTION
 254 .PP
 255 This command performs one of several operations on the
 256 variable given by \fIarrayName\fR.
 257 Unless otherwise specified for individual commands below,
 258 \fIarrayName\fR must be the name of an existing array variable.
 259 The \fIoption\fR argument determines what action is carried
 260 out by the command.
 261 The legal \fIoptions\fR (which may be abbreviated) are:
 262 .TP
 263 \fBarray anymore \fIarrayName searchId\fR
 264 Returns 1 if there are any more elements left to be processed
 265 in an array search, 0 if all elements have already been
 266 returned.
 267 \fISearchId\fR indicates which search on \fIarrayName\fR to
 268 check, and must have been the return value from a previous
 269 invocation of \fBarray startsearch\fR.
 270 This option is particularly useful if an array has an element
 271 with an empty name, since the return value from
 272 \fBarray nextelement\fR won't indicate whether the search
 273 has been completed.
 274 .TP
 275 \fBarray donesearch \fIarrayName searchId\fR
 276 This command terminates an array search and destroys all the
 277 state associated with that search.  \fISearchId\fR indicates
 278 which search on \fIarrayName\fR to destroy, and must have
 279 been the return value from a previous invocation of
 280 \fBarray startsearch\fR.  Returns an empty string.
 281 .TP
 282 \fBarray exists \fIarrayName\fR
 283 Returns 1 if \fIarrayName\fR is an array variable, 0 if there
 284 is no variable by that name or if it is a scalar variable.
 285 .TP
 286 \fBarray get \fIarrayName\fR ?\fIpattern\fR?
 287 Returns a list containing pairs of elements.  The first
 288 element in each pair is the name of an element in \fIarrayName\fR
 289 and the second element of each pair is the value of the
 290 array element.  The order of the pairs is undefined.
 291 If \fIpattern\fR is not specified, then all of the elements of the
 292 array are included in the result.
 293 If \fIpattern\fR is specified, then only those elements whose names
 294 match \fIpattern\fR (using the matching rules of
 295 \fBstring match\fR) are included.
 296 If \fIarrayName\fR isn't the name of an array variable, or if
 297 the array contains no elements, then an empty list is returned.
 298 .TP
 299 \fBarray names \fIarrayName\fR ?\fIpattern\fR?
 300 Returns a list containing the names of all of the elements in
 301 the array that match \fIpattern\fR (using the matching
 302 rules of \fBstring match\fR).
 303 If \fIpattern\fR is omitted then the command returns all of
 304 the element names in the array.
 305 If there are no (matching) elements in the array, or if \fIarrayName\fR
 306 isn't the name of an array variable, then an empty string is
 307 returned.
 308 .TP
 309 \fBarray nextelement \fIarrayName searchId\fR
 310 Returns the name of the next element in \fIarrayName\fR, or
 311 an empty string if all elements of \fIarrayName\fR have
 312 already been returned in this search.  The \fIsearchId\fR
 313 argument identifies the search, and must have
 314 been the return value of an \fBarray startsearch\fR command.
 315 Warning:  if elements are added to or deleted from the array,
 316 then all searches are automatically terminated just as if
 317 \fBarray donesearch\fR had been invoked; this will cause
 318 \fBarray nextelement\fR operations to fail for those searches.
 319 .TP
 320 \fBarray set \fIarrayName list\fR
 321 Sets the values of one or more elements in \fIarrayName\fR.
 322 \fIlist\fR must have a form like that returned by \fBarray get\fR,
 323 consisting of an even number of elements.
 324 Each odd-numbered element in \fIlist\fR is treated as an element
 325 name within \fIarrayName\fR, and the following element in \fIlist\fR
 326 is used as a new value for that array element.
 327 If the variable \fIarrayName\fR does not already exist
 328 and \fIlist\fR is empty,
 329 \fIarrayName\fR is created with an empty array value.
 330 .TP
 331 \fBarray size \fIarrayName\fR
 332 Returns a decimal string giving the number of elements in the
 333 array.
 334 If \fIarrayName\fR isn't the name of an array then 0 is returned.
 335 .TP
 336 \fBarray startsearch \fIarrayName\fR
 337 This command initializes an element-by-element search through the
 338 array given by \fIarrayName\fR, such that invocations of the
 339 \fBarray nextelement\fR command will return the names of the
 340 individual elements in the array.
 341 When the search has been completed, the \fBarray donesearch\fR
 342 command should be invoked.
 343 The return value is a
 344 search identifier that must be used in \fBarray nextelement\fR
 345 and \fBarray donesearch\fR commands; it allows multiple
 346 searches to be underway simultaneously for the same array.
 347 .VS 8.3
 348 .TP
 349 \fBarray unset \fIarrayName\fR ?\fIpattern\fR?
 350 Unsets all of the elements in the array that match \fIpattern\fR (using the
 351 matching rules of \fBstring match\fR).  If \fIarrayName\fR isn't the name
 352 of an array variable or there are no matching elements in the array, then
 353 an empty string is returned.  If \fIpattern\fR is omitted and is it an
 354 array variable, then the command unsets the entire array.
 355 .VE 8.3
 356
 357 .SH KEYWORDS
 358 array, element names, search