|
ActiveTcl User Guide |
 |
Table of Contents
_________________________________________________________________
dict - Manipulate dictionaries.
dict option arg ?arg ...?
_________________________________________________________________
Performs one of several operations on dictionary values or
variables containing dictionary values, depending on option.
The legal options (which may be abbreviated) are:
dict append dictionaryVariable key
?string ...? This appends the given string (or
strings) to the value that the given key maps to in the dictionary
value contained in the given variable, writing the resulting
dictionary value back to that variable. Non-existent keys are
treated as if they map to an empty string.
dict create ?key value
...?
Create a new dictionary that contains each of the key/value
mappings listed as arguments (keys and values alternating, with
each key being followed by its associated value.)
dict exists dictionaryValue key
?key ...? This returns a boolean value indicating
whether the given key (or path of keys through a set of nested
dictionaries) exists in the given dictionary value. This returns a
true value exactly when dict get on that path will
succeed.
dict filter dictionaryValue
filterType arg ?arg ...? This takes a
dictionary value and returns a new dictionary that contains just
those key/value pairs that match the specified filter type (which
may be abbreviated.) Supported filter types are:
dict filter dictionaryValue key
globPattern The key rule only matches those key/value pairs
whose keys match the given pattern (in the style of string
match.)
dict filter dictionaryValue script
{keyVar value_Var}
script The script rule tests for matching by assigning the
key to the keyVar and the value to the valueVar, and
then evaluating the given script which should return a boolean
value (with the key/value pair only being included in the result of
the dict filter when a true value is returned.) Note
that the first argument after the rule selection word is a
two-element list. If the script returns with a condition of
TCL_BREAK, no further key/value pairs are considered for inclusion
in the resulting dictionary, and a condition of TCL_CONTINUE is
equivalent to a false result.
dict filter dictionaryValue value
globPattern The value rule only matches those key/value
pairs whose values match the given pattern (in the style of
string match.)
dict for {keyVar
valueVar} dictionaryValue body This
command takes three arguments, the first a two-element list of
variable names (for the key and value respectively of each mapping
in the dictionary), the second the dictionary value to iterate
across, and the third a script to be evaluated for each mapping
with the key and value variables set appropriately (in the manner
of foreach.) The result of the command is an empty string.
If any evaluation of the body generates a TCL_BREAK result, no
further pairs from the dictionary will be iterated over and the
dict for command will terminate successfully
immediately. If any evaluation of the body generates a TCL_CONTINUE
result, this shall be treated exactly like a normal TCL_OK result.
The order of iteration is undefined.
dict get dictionaryValue ?key
...?
Given a dictionary value (first argument) and a key (second
argument), this will retrieve the value for that key. Where several
keys are supplied, the behaviour of the command shall be as if the
result of dict get $dictVal $key was
passed as the first argument to dict get with the
remaining arguments as second (and possibly subsequent) arguments.
This facilitates lookups in nested dictionaries. For example, the
following two commands are equivalent: dict get $dict foo bar spong
dict get [dict get [dict get $dict foo] bar] spong If no keys are
provided, dict would return a list containing pairs of elements in
a manner similar to array get. That is, the first
element of each pair would be the key and the second element would
be the value for that key.
It is an error to attempt to retrieve a value for a key that is
not present in the dictionary.
dict incr dictionaryVariable key
?increment? This adds the given increment value (an integer
that defaults to 1 if not specified) to the value that the given
key maps to in the dictionary value contained in the given
variable, writing the resulting dictionary value back to that
variable. Non-existent keys are treated as if they map to 0. It is
an error to increment a value for an existing key if that value is
not an integer.
dict info dictionaryValue
This returns information (intended for display to people) about
the given dictionary though the format of this data is dependent on
the implementation of the dictionary. For dictionaries that are
implemented by hash tables, it is expected that this will return
the string produced by Tcl_HashStats, similar to
array info.
dict keys dictionaryValue
?globPattern?
Return a list of all keys in the given dictionary value. If a
pattern is supplied, only those keys that match it (according to
the rules of string match) will be returned. The
returned keys will be in an arbitrary implementation-specific
order, though where no pattern is supplied the i'th key returned by
dict keys will be the key for the i'th value returned
by dict values applied to the same dictionary
value.
dict lappend dictionaryVariable key
?value ...? This appends the given items to the list
value that the given key maps to in the dictionary value contained
in the given variable, writing the resulting dictionary value back
to that variable. Non-existent keys are treated as if they map to
an empty list, and it is legal for there to be no items to append
to the list. It is an error for the value that the key maps to to
not be representable as a list.
dict merge ?dictionaryValue ...?
Return a dictionary that contains the contents of each of the
dictionaryValue arguments. Where two (or more) dictionaries
contain a mapping for the same key, the resulting dictionary maps
that key to the value according to the last dictionary on the
command line containing a mapping for that key.
dict remove dictionaryValue ?key
...?
Return a new dictionary that is a copy of an old one passed in as
first argument except without mappings for each of the keys listed.
It is legal for there to be no keys to remove, and it also legal
for any of the keys to be removed to not be present in the input
dictionary in the first place.
dict replace dictionaryValue ?key
value ...? Return a new dictionary that is a copy of
an old one passed in as first argument except with some values
different or some extra key/value pairs added. It is legal for this
command to be called with no key/value pairs, but illegal for this
command to be called with a key but no value.
dict set dictionaryVariable key
?key ...? value This operation takes the name
of a variable containing a dictionary value and places an updated
dictionary value in that variable containing a mapping from the
given key to the given value. In a manner analogous to lset,
where multiple keys are present, they do indexing into nested
dictionaries.
dict size dictionaryValue
Return the number of key/value mappings in the given dictionary
value.
dict unset dictionaryVariable key
?key ...? This operation (the companion to
dict set) takes the name of a variable containing a
dictionary value and places an updated dictionary value in that
variable that does not contain a mapping for the given key. Where
multiple keys are present, this describes a path through nested
dictionaries to the mapping to remove. At least one key must be
specified, but the last key on the key-path need not exist. All
other components on the path must exist.
dict values dictionaryValue
?globPattern? Return a list of all values in the given
dictionary value. If a pattern is supplied, only those values that
match it (according to the rules of string match)
will be returned. The returned values will be in an arbitrary
implementation-specific order, though where no pattern is supplied
the i'th key returned by dict keys will be the key
for the i'th value returned by dict values applied to
the same dictionary value.
append(n) , array(n) , foreach(n) , incr(n) , list(n) , lappend(n) , set(n)
dictionary, create, update, lookup, iterate, filter
Table of Contents
|
