通讯编程

开发平台：
Visual C++

array.n：源码内容
							'"
'" Copyright (c) 1993-1994 The Regents of the University of California.
'" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'"
'" See the file "license.terms" for information on usage and redistribution
'" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'" 
'" RCS: @(#) $Id: array.n,v 1.8.18.3 2004/10/27 14:23:41 dkf Exp $
'" 
.so man.macros
.TH array n 8.3 Tcl "Tcl Built-In Commands"
.BS
'" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
array - Manipulate array variables
.SH SYNOPSIS
fBarray fIoption arrayNamefR ?fIarg arg ...fR?
.BE
.SH DESCRIPTION
.PP
This command performs one of several operations on the
variable given by fIarrayNamefR.
Unless otherwise specified for individual commands below,
fIarrayNamefR must be the name of an existing array variable.
The fIoptionfR argument determines what action is carried
out by the command.
The legal fIoptionsfR (which may be abbreviated) are:
.TP
fBarray anymore fIarrayName searchIdfR
Returns 1 if there are any more elements left to be processed
in an array search, 0 if all elements have already been
returned.
fISearchIdfR indicates which search on fIarrayNamefR to
check, and must have been the return value from a previous
invocation of fBarray startsearchfR.
This option is particularly useful if an array has an element
with an empty name, since the return value from
fBarray nextelementfR won't indicate whether the search
has been completed.
.TP
fBarray donesearch fIarrayName searchIdfR
This command terminates an array search and destroys all the
state associated with that search.  fISearchIdfR indicates
which search on fIarrayNamefR to destroy, and must have
been the return value from a previous invocation of
fBarray startsearchfR.  Returns an empty string.
.TP
fBarray exists fIarrayNamefR
Returns 1 if fIarrayNamefR is an array variable, 0 if there
is no variable by that name or if it is a scalar variable.
.TP
fBarray get fIarrayNamefR ?fIpatternfR?
Returns a list containing pairs of elements.  The first
element in each pair is the name of an element in fIarrayNamefR
and the second element of each pair is the value of the
array element.  The order of the pairs is undefined.
If fIpatternfR is not specified, then all of the elements of the
array are included in the result.
If fIpatternfR is specified, then only those elements whose names
match fIpatternfR (using the matching rules of
fBstring matchfR) are included.
If fIarrayNamefR isn't the name of an array variable, or if
the array contains no elements, then an empty list is returned.
.TP
fBarray names fIarrayNamefR ?fImodefR? ?fIpatternfR?
Returns a list containing the names of all of the elements in
the array that match fIpatternfR.  fIModefR may be one of
fB-exactfR, fB-globfR, or fB-regexpfR.  If specified, fImodefR
designates which matching rules to use to match fIpatternfR against
the names of the elements in the array.  If not specified, fImodefR
defaults to fB-globfR.  See the documentation for fBstring matchfR
for information on glob style matching, and the documentation for
fBregexpfR for information on regexp matching.
If fIpatternfR is omitted then the command returns all of
the element names in the array.  If there are no (matching) elements
in the array, or if fIarrayNamefR isn't the name of an array
variable, then an empty string is returned.
.TP
fBarray nextelement fIarrayName searchIdfR
Returns the name of the next element in fIarrayNamefR, or
an empty string if all elements of fIarrayNamefR have
already been returned in this search.  The fIsearchIdfR
argument identifies the search, and must have
been the return value of an fBarray startsearchfR command.
Warning:  if elements are added to or deleted from the array,
then all searches are automatically terminated just as if
fBarray donesearchfR had been invoked; this will cause
fBarray nextelementfR operations to fail for those searches.
.TP
fBarray set fIarrayName listfR
Sets the values of one or more elements in fIarrayNamefR.
fIlistfR must have a form like that returned by fBarray getfR,
consisting of an even number of elements.
Each odd-numbered element in fIlistfR is treated as an element
name within fIarrayNamefR, and the following element in fIlistfR
is used as a new value for that array element.
If the variable fIarrayNamefR does not already exist
and fIlistfR is empty,
fIarrayNamefR is created with an empty array value.
.TP
fBarray size fIarrayNamefR
Returns a decimal string giving the number of elements in the
array.
If fIarrayNamefR isn't the name of an array then 0 is returned.
.TP
fBarray startsearch fIarrayNamefR
This command initializes an element-by-element search through the
array given by fIarrayNamefR, such that invocations of the
fBarray nextelementfR command will return the names of the
individual elements in the array.
When the search has been completed, the fBarray donesearchfR
command should be invoked.
The return value is a
search identifier that must be used in fBarray nextelementfR
and fBarray donesearchfR commands; it allows multiple
searches to be underway simultaneously for the same array.
It is currently more efficient and easier to use either the fBarray
getfR or fBarray namesfR, together with fBforeachfR, to iterate
over all but very large arrays.  See the examples below for how to do
this.
.VS 8.4
.TP
fBarray statistics fIarrayNamefR
Returns statistics about the distribution of data within the hashtable
that represents the array.  This information includes the number of
entries in the table, the number of buckets, and the utilization of
the buckets.
.VE 8.4
.VS 8.3
.TP
fBarray unset fIarrayNamefR ?fIpatternfR?
Unsets all of the elements in the array that match fIpatternfR (using the
matching rules of fBstring matchfR).  If fIarrayNamefR isn't the name
of an array variable or there are no matching elements in the array, no
error will be raised.  If fIpatternfR is omitted and fIarrayNamefR is
an array variable, then the command unsets the entire array.
The command always returns an empty string.
.VE 8.3
.SH EXAMPLES
.CS
fBarray setfR colorcount {
    red   1
    green 5
    blue  4
    white 9
}
foreach {color count} [fBarray getfR colorcount] {
   puts "Color: $color Count: $count" 
}
 => Color: blue Count: 4
    Color: white Count: 9
    Color: green Count: 5
    Color: red Count: 1
foreach color [fBarray namesfR colorcount] {
   puts "Color: $color Count: $colorcount($color)" 
}
 => Color: blue Count: 4
    Color: white Count: 9
    Color: green Count: 5
    Color: red Count: 1
foreach color [lsort [array names colorcount]] {
    puts "Color: $color Count: $colorcount($color)" 
}
 => Color: blue Count: 4
    Color: green Count: 5
    Color: red Count: 1
    Color: white Count: 9
fBarray statisticsfR colorcount
 => 4 entries in table, 4 buckets
    number of buckets with 0 entries: 1
    number of buckets with 1 entries: 2
    number of buckets with 2 entries: 1
    number of buckets with 3 entries: 0
    number of buckets with 4 entries: 0
    number of buckets with 5 entries: 0
    number of buckets with 6 entries: 0
    number of buckets with 7 entries: 0
    number of buckets with 8 entries: 0
    number of buckets with 9 entries: 0
    number of buckets with 10 or more entries: 0
    average search distance for entry: 1.2
.CE
.SH "SEE ALSO"
list(n), string(n), variable(n), trace(n), foreach(n)
.SH KEYWORDS
array, element names, search

						