|
|
This manual page is for Mac OS X version 10.6.3If you are running a different version of Mac OS X, view the documentation locally:
Reading manual pagesManual pages are intended as a quick reference for people who already understand a technology.
|
dict(n) Tcl Built-In Commands dict(n)
____________________________________________________________________________________________________________
NAME
dict - Manipulate dictionaries
SYNOPSIS
dict option arg ?arg ...?
____________________________________________________________________________________________________________
DESCRIPTION
Performs one of several operations on dictionary values or variables containing dictionary values
(see the DICTIONARY VALUES section below for a description), 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 dic-tionary dictionary
tionary 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 valueVar} 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 condi-tion condition
tion of TCL_CONTINUE is equivalent to a false result. The key/value pairs are tested in
the order in which the keys were inserted into the dictionary.
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 the order in which the
keys were inserted into the dictionary.
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 the order that they were inserted into the dictionary.
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 with-out without
out 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. When multiple keys are present, this operation creates or updates a chain of 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 dictio-nary dictionary
nary 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 update dictionaryVariable key varName ?key varName ...? body
Execute the Tcl script in body with the value for each key (as found by reading the dictionary
value in dictionaryVariable) mapped to the variable varName. There may be multiple key/varName
pairs. If a key does not have a mapping, that corresponds to an unset varName. When body ter-minates, terminates,
minates, any changes made to the varNames is reflected back to the dictionary within dictio-naryVariable dictionaryVariable
naryVariable (unless dictionaryVariable itself becomes unreadable, when all updates are
silently discarded), even if the result of body is an error or some other kind of exceptional
exit. The result of dict update is (unless some kind of error occurs) the result of the evalu-ation evaluation
ation of body. Note that the mapping of values to variables does not use traces; changes to
the dictionaryVariable's contents only happen when body terminates.
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 the order of that the keys associated with those values were
inserted into the dictionary.
dict with dictionaryVariable ?key ...? body
Execute the Tcl script in body with the value for each key in dictionaryVariable mapped (in a
manner similarly to dict update) to a variable with the same name. Where one or more keys are
available, these indicate a chain of nested dictionaries, with the innermost dictionary being
the one opened out for the execution of body. As with dict update, making dictionaryVariable
unreadable will make the updates to the dictionary be discarded, and this also happens if the
contents of dictionaryVariable are adjusted so that the chain of dictionaries no longer
exists. The result of dict with is (unless some kind of error occurs) the result of the evalu-ation evaluation
ation of body. Note that the mapping of values to variables does not use traces; changes to
the dictionaryVariable's contents only happen when body terminates.
DICTIONARY VALUES
Dictionaries are values that contain an efficient, order-preserving mapping from arbitrary keys to
arbitrary values. Each key in the dictionary maps to a single value. They have a textual format
that is exactly that of any list with an even number of elements, with each mapping in the dictionary
being represented as two items in the list. When a command takes a dictionary and produces a new dic-tionary dictionary
tionary based on it (either returning it or writing it back into the variable that the starting dic-tionary dictionary
tionary was read from) the new dictionary will have the same order of keys, modulo any deleted keys
and with new keys added on to the end. When a string is interpreted as a dictionary and it would
otherwise have duplicate keys, only the last value for a particular key is used; the others are
ignored, meaning that, "apple banana" and "apple carrot apple banana" are equivalent dictionaries
(with different string representations).
EXAMPLES
Constructing and using nested dictionaries:
# Data for one employee
dict set employeeInfo 12345-A forenames "Joe"
dict set employeeInfo 12345-A surname "Schmoe"
dict set employeeInfo 12345-A street "147 Short Street"
dict set employeeInfo 12345-A city "Springfield"
dict set employeeInfo 12345-A phone "555-1234"
# Data for another employee
dict set employeeInfo 98372-J forenames "Anne"
dict set employeeInfo 98372-J surname "Other"
dict set employeeInfo 98372-J street "32995 Oakdale Way"
dict set employeeInfo 98372-J city "Springfield"
dict set employeeInfo 98372-J phone "555-8765"
# The above data probably ought to come from a database...
# Print out some employee info
set i 0
puts "There are [dict size $employeeInfo] employees"
dict for {id info} $employeeInfo {
puts "Employee #[incr i]: $id"
dict with info {
puts " Name: $forenames $surname"
puts " Address: $street, $city"
puts " Telephone: $phone"
}
}
# Another way to iterate and pick out names...
foreach id [dict keys $employeeInfo] {
puts "Hello, [dict get $employeeInfo $id forenames]!"
}
A localizable version of string toupper:
# Set up the basic C locale
set capital [dict create C [dict create]]
foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] {
dict set capital C $c [string toupper $c]
}
# English locales can luckily share the "C" locale
dict set capital en [dict get $capital C]
dict set capital en_US [dict get $capital C]
dict set capital en_GB [dict get $capital C]
# ... and so on for other supported languages ...
# Now get the mapping for the current locale and use it.
set upperCaseMap [dict get $capital $env(LANG)]
set upperCase [string map $upperCaseMap $string]
SEE ALSO
append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n)
KEYWORDS
dictionary, create, update, lookup, iterate, filter
Tcl 8.5 dict(n)
|
The way to report a problem with this manual page depends on the type of problem: