dict - Manipulate dictionaries

Description

Performs one of several operations on dictionary values or variables containing dictionary values (see
the DICTIONARYVALUES section below for a description), depending on option. The legal options (which
may be abbreviated) are:

dictappenddictionaryVariablekey ?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. The updated
dictionary value is returned. If dictionaryVariable indicates an element that does not exist of 2
an array that has a default value set, the default value and will be used as the value of the 2
dictionary prior to the appending operation.

dictcreate ?keyvalue...?
Return 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.)

dictexistsdictionaryValuekey ?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
dictget on that path will succeed.

dictfilterdictionaryValuefilterTypearg ?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:

dictfilterdictionaryValuekey ?globPattern...?
The key rule only matches those key/value pairs whose keys match any of the given patterns
(in the style of stringmatch.)

dictfilterdictionaryValuescript{keyVariablevalueVariable}script
The script rule tests for matching by assigning the key to the keyVariable and the value to
the valueVariable, and then evaluating the given script which should result in a boolean
value (with the key/value pair only being included in the result of the dictfilter 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. The key/value pairs are tested in the
order in which the keys were inserted into the dictionary.

dictfilterdictionaryValuevalue ?globPattern...?
The value rule only matches those key/value pairs whose values match any of the given
patterns (in the style of stringmatch.)

dictfor{keyVariablevalueVariable}dictionaryValuebody
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 dictfor 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.

dictgetdictionaryValue ?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 dictget$dictVal$key was passed as the first argument to dictget 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, dictget will return a list containing pairs of elements in a manner
similar to arrayget. 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.

dictgetdefdictionaryValue ?key...? keydefaultdictgetwithdefaultdictionaryValue ?key...? keydefault
This behaves the same as dictget (with at least one key argument), returning the value that the 2
key path maps to in the dictionary dictionaryValue, except that instead of producing an error 2
because the key (or one of the keys on the key path) is absent, it returns the default argument 2
instead. 2

Note that there must always be at least one key provided, and that dictgetdef and dict 2
getwithdefault are aliases for each other. 2

dictincrdictionaryVariablekey ?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. The
updated dictionary value is returned. If dictionaryVariable indicates an element that does not 2
exist of an array that has a default value set, the default value and will be used as the value of 2
the dictionary prior to the incrementing operation.

dictinfodictionaryValue
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 arraystatistics.

dictkeysdictionaryValue ?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 stringmatch) will be returned. The returned keys will be
in the order that they were inserted into the dictionary.

dictlappenddictionaryVariablekey ?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. The updated dictionary value is returned. If dictionaryVariable 2
indicates an element that does not exist of an array that has a default value set, the default 2
value and will be used as the value of the dictionary prior to the list-appending operation.

dictmap {keyVariablevalueVariable} dictionaryValuebody
This command applies a transformation to each element of a dictionary, returning a new dictionary.
It takes three arguments: the first is 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 lmap). In an iteration where the evaluated script completes
normally (TCL_OK, as opposed to an error, etc.) the result of the script is put into an
accumulator dictionary using the key that is the current contents of the keyVariable variable at
that point. The result of the dictmap command is the accumulator dictionary after all keys have
been iterated over.

If the evaluation of the body for any particular step generates a break, no further pairs from the
dictionary will be iterated over and the dictmap command will terminate successfully immediately.
If the evaluation of the body for a particular step generates a continue result, the current
iteration is aborted and the accumulator dictionary is not modified. The order of iteration is the
natural order of the dictionary (typically the order in which the keys were added to the
dictionary; the order is the same as that used in dictfor).

dictmerge ?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.

dictremovedictionaryValue ?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.

dictreplacedictionaryValue ?keyvalue...?
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.

dictsetdictionaryVariablekey ?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. The
updated dictionary value is returned. If dictionaryVariable indicates an element that does not 2
exist of an array that has a default value set, the default value and will be used as the value of 2
the dictionary prior to the value insert/update operation.

dictsizedictionaryValue
Return the number of key/value mappings in the given dictionary value.

dictunsetdictionaryVariablekey ?key...?
This operation (the companion to dictset) 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. The updated dictionary value is
returned. If dictionaryVariable indicates an element that does not exist of an array that has a 2
default value set, the default value and will be used as the value of the dictionary prior to the 2
value remove operation.

dictupdatedictionaryVariablekeyvarName ?keyvarName...? 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
terminates, any changes made to the varNames is reflected back to the dictionary within
dictionaryVariable (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 dictupdate is (unless some kind of error occurs) the result of the evaluation
of body. If dictionaryVariable indicates an element that does not exist of an array that has a 2
default value set, the default value and will be used as the value of the dictionary prior to the 2
update operation.

Each varName is mapped in the scope enclosing the dictupdate; it is recommended that this command
only be used in a local scope (procedure, lambda term for apply, or method). Because of this, the
variables set by dictupdate will continue to exist after the command finishes (unless explicitly
unset).

Note that the mapping of values to variables does not use traces; changes to the
dictionaryVariable's contents only happen when body terminates.

dictvaluesdictionaryValue ?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 stringmatch) will be returned. The returned
values will be in the order of that the keys associated with those values were inserted into the
dictionary.

dictwithdictionaryVariable ?key...? body
Execute the Tcl script in body with the value for each key in dictionaryVariable mapped (in a
manner similarly to dictupdate) 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 dictupdate, 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 dictwith is (unless some kind of error occurs) the result of the evaluation of
body. If dictionaryVariable indicates an element that does not exist of an array that has a 2
default value set, the default value and will be used as the value of the dictionary prior to the 2
updating operation.

The variables are mapped in the scope enclosing the dictwith; it is recommended that this command
only be used in a local scope (procedure, lambda term for apply, or method). Because of this, the
variables set by dictwith will continue to exist after the command finishes (unless explicitly
unset).

Note that the mapping of values to variables does not use traces; changes to the
dictionaryVariable's contents only happen when body terminates.

If the dictionaryVariable contains a value that is not a dictionary at the point when the body
terminates (which can easily happen if the name is the same as any of the keys in dictionary) then
an error occurs at that point. This command is thus not recommended for use when the keys in the
dictionary are expected to clash with the dictionaryVariable name itself. Where the contained key
does map to a dictionary, the net effect is to combine that inner dictionary into the outer
dictionary; see the EXAMPLES below for an illustration of this.

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 dictionary
       based on it (either returning it or writing it back into the variable that the  starting  dictionary  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).

       Operations that derive a new dictionary from an old one (e.g., updates like  dictset  and  dictunset)
       preserve the order of keys in the dictionary. The exceptions to this are for any new keys they add, which
       are appended to the sequence, and any keys that are removed, which are excised from the order.

Examples

       Basic dictionary usage:

              # Make a dictionary to map extensions to descriptions
              set filetypes [dictcreate .txt "Text File" .tcl "Tcl File"]

              # Add/update the dictionary
              dictset filetypes .tcl "Tcl Script"
              dictset filetypes .tm  "Tcl Module"
              dictset filetypes .gif "GIF Image"
              dictset filetypes .png "PNG Image"

              # Simple read from the dictionary
              set ext ".tcl"
              set desc [dictget $filetypes $ext]
              puts "$ext is for a $desc"

              # Somewhat more complex, with existence test
              foreach filename [glob *] {
                  set ext [file extension $filename]
                  if {[dictexists $filetypes $ext]} {
                      puts "$filename is a [dictget $filetypes $ext]"
                  }
              }

       Constructing and using nested dictionaries:

              # Data for one employee
              dictset employeeInfo 12345-A forenames "Joe"
              dictset employeeInfo 12345-A surname   "Schmoe"
              dictset employeeInfo 12345-A street "147 Short Street"
              dictset employeeInfo 12345-A city   "Springfield"
              dictset employeeInfo 12345-A phone  "555-1234"
              # Data for another employee
              dictset employeeInfo 98372-J forenames "Anne"
              dictset employeeInfo 98372-J surname   "Other"
              dictset employeeInfo 98372-J street "32995 Oakdale Way"
              dictset employeeInfo 98372-J city   "Springfield"
              dictset 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 [dictsize $employeeInfo] employees"
              dictfor {id info} $employeeInfo {
                  puts "Employee #[incr i]: $id"
                  dictwith info {
                      puts "   Name: $forenames $surname"
                      puts "   Address: $street, $city"
                      puts "   Telephone: $phone"
                  }
              }
              # Another way to iterate and pick out names...
              foreach id [dictkeys $employeeInfo] {
                  puts "Hello, [dictget $employeeInfo $id forenames]!"
              }

       A localizable version of stringtoupper:

              # Set up the basic C locale
              set capital [dictcreate C [dictcreate]]
              foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] {
                  dictset capital C $c [string toupper $c]
              }

              # English locales can luckily share the "C" locale
              dictset capital en [dictget $capital C]
              dictset capital en_US [dictget $capital C]
              dictset capital en_GB [dictget $capital C]

              # ... and so on for other supported languages ...

              # Now get the mapping for the current locale and use it.
              set upperCaseMap [dictget $capital $env(LANG)]
              set upperCase [string map $upperCaseMap $string]

       Showing the detail of dictwith:

              proc sumDictionary {varName} {
                  upvar 1 $varName vbl
                  foreach key [dictkeys $vbl] {
                      # Manufacture an entry in the subdictionary
                      dictset vbl $key total 0
                      # Add the values and remove the old
                      dictwith vbl $key {
                          set total [expr {$x + $y + $z}]
                          unset x y z
                      }
                  }
                  puts "last total was $total, for key $key"
              }

              set myDict {
                  a {x 1 y 2 z 3}
                  b {x 6 y 5 z 4}
              }

              sumDictionary myDict
              #    prints: lasttotalwas15,forkeyb

              puts "dictionary is now \"$myDict\""
              #    prints: dictionaryisnow"a{total6}b{total15}"

       When dictwith is used with a key that clashes with the name of the dictionary variable:

              set foo {foo {a b} bar 2 baz 3}
              dictwith foo {}
              puts $foo
              #    prints: abfoo{ab}bar2baz3

Keywords

       dictionary, create, update, lookup, iterate, filter, map

Tcl                                                    8.5                                            dict(3tcl)

Name

       dict - Manipulate dictionaries

Synopsis

dictoptionarg ?arg...?
________________________________________________________________________________________________________________