diff options
Diffstat (limited to 'tcl8.6/doc/dict.n')
| -rw-r--r-- | tcl8.6/doc/dict.n | 445 |
1 files changed, 0 insertions, 445 deletions
diff --git a/tcl8.6/doc/dict.n b/tcl8.6/doc/dict.n deleted file mode 100644 index fecad85..0000000 --- a/tcl8.6/doc/dict.n +++ /dev/null @@ -1,445 +0,0 @@ -'\" -'\" Copyright (c) 2003 Donal K. Fellows -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH dict n 8.5 Tcl "Tcl Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -dict \- Manipulate dictionaries -.SH SYNOPSIS -\fBdict \fIoption arg \fR?\fIarg ...\fR? -.BE -.SH DESCRIPTION -.PP -Performs one of several operations on dictionary values or variables -containing dictionary values (see the \fBDICTIONARY VALUES\fR section -below for a description), depending on \fIoption\fR. The legal -\fIoption\fRs (which may be abbreviated) are: -.TP -\fBdict append \fIdictionaryVariable key \fR?\fIstring ...\fR? -. -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. -.TP -\fBdict create \fR?\fIkey value ...\fR? -. -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.) -.TP -\fBdict exists \fIdictionaryValue key \fR?\fIkey ...\fR? -. -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 \fBdict -get\fR on that path will succeed. -.TP -\fBdict filter \fIdictionaryValue filterType arg \fR?\fIarg ...\fR? -. -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: -.RS -.TP -\fBdict filter \fIdictionaryValue \fBkey\fR ?\fIglobPattern ...\fR? -.VS 8.6 -The key rule only matches those key/value pairs whose keys match any -of the given patterns (in the style of \fBstring match\fR.) -.VE 8.6 -.TP -\fBdict filter \fIdictionaryValue \fBscript {\fIkeyVariable valueVariable\fB} \fIscript\fR -. -The script rule tests for matching by assigning the key to the -\fIkeyVariable\fR and the value to the \fIvalueVariable\fR, 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 \fBdict -filter\fR when a true value is returned.) Note that the first -argument after the rule selection word is a two-element list. If the -\fIscript\fR returns with a condition of \fBTCL_BREAK\fR, no further -key/value pairs are considered for inclusion in the resulting -dictionary, and a condition of \fBTCL_CONTINUE\fR is equivalent to a false -result. The key/value pairs are tested in the order in which the keys -were inserted into the dictionary. -.TP -\fBdict filter \fIdictionaryValue \fBvalue \fR?\fIglobPattern ...\fR? -.VS 8.6 -The value rule only matches those key/value pairs whose values match any -of the given patterns (in the style of \fBstring match\fR.) -.VE 8.6 -.RE -.TP -\fBdict for {\fIkeyVariable valueVariable\fB} \fIdictionaryValue body\fR -. -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 \fBforeach\fR.) -The result of the command is an empty string. If any evaluation of the -body generates a \fBTCL_BREAK\fR result, no further pairs from the -dictionary will be iterated over and the \fBdict for\fR command will -terminate successfully immediately. If any evaluation of the body -generates a \fBTCL_CONTINUE\fR result, this shall be treated exactly like a -normal \fBTCL_OK\fR result. The order of iteration is the order in -which the keys were inserted into the dictionary. -.TP -\fBdict get \fIdictionaryValue \fR?\fIkey ...\fR? -. -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 -\fBdict get $dictVal $key\fR was passed as the first argument to -\fBdict get\fR with the remaining arguments as second (and possibly -subsequent) arguments. This facilitates lookups in nested -dictionaries. For example, the following two commands are equivalent: -.RS -.PP -.CS -dict get $dict foo bar spong -dict get [dict get [dict get $dict foo] bar] spong -.CE -.PP -If no keys are provided, \fBdict get\fR will return a list containing pairs of -elements in a manner similar to \fBarray get\fR. That is, the first -element of each pair would be the key and the second element would be -the value for that key. -.PP -It is an error to attempt to retrieve a value for a key that is not -present in the dictionary. -.RE -.TP -\fBdict incr \fIdictionaryVariable key \fR?\fIincrement\fR? -. -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. -.TP -\fBdict info \fIdictionaryValue\fR -. -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 \fBTcl_HashStats\fR, similar to \fBarray statistics\fR. -.TP -\fBdict keys \fIdictionaryValue \fR?\fIglobPattern\fR? -. -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 -\fBstring match\fR) will be returned. The returned keys will be in the -order that they were inserted into the dictionary. -.TP -\fBdict lappend \fIdictionaryVariable key \fR?\fIvalue ...\fR? -. -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. -.TP -\fBdict map \fR{\fIkeyVariable valueVariable\fR} \fIdictionaryValue body\fR -. -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 \fBlmap\fR). In an iteration -where the evaluated script completes normally (\fBTCL_OK\fR, as opposed to an -\fBerror\fR, etc.) the result of the script is put into an accumulator -dictionary using the key that is the current contents of the \fIkeyVariable\fR -variable at that point. The result of the \fBdict map\fR command is the -accumulator dictionary after all keys have been iterated over. -.RS -.PP -If the evaluation of the body for any particular step generates a \fBbreak\fR, -no further pairs from the dictionary will be iterated over and the \fBdict -map\fR command will terminate successfully immediately. If the evaluation of -the body for a particular step generates a \fBcontinue\fR 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 \fBdict for\fR). -.RE -.TP -\fBdict merge \fR?\fIdictionaryValue ...\fR? -. -Return a dictionary that contains the contents of each of the -\fIdictionaryValue\fR 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. -.TP -\fBdict remove \fIdictionaryValue \fR?\fIkey ...\fR? -. -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. -.TP -\fBdict replace \fIdictionaryValue \fR?\fIkey value ...\fR? -. -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. -.TP -\fBdict set \fIdictionaryVariable key \fR?\fIkey ...\fR? \fIvalue\fR -. -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. -.TP -\fBdict size \fIdictionaryValue\fR -. -Return the number of key/value mappings in the given dictionary value. -.TP -\fBdict unset \fIdictionaryVariable key \fR?\fIkey ...\fR? -. -This operation (the companion to \fBdict set\fR) 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. -.TP -\fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR -. -Execute the Tcl script in \fIbody\fR with the value for each \fIkey\fR -(as found by reading the dictionary value in \fIdictionaryVariable\fR) -mapped to the variable \fIvarName\fR. There may be multiple -\fIkey\fR/\fIvarName\fR pairs. If a \fIkey\fR does not have a mapping, -that corresponds to an unset \fIvarName\fR. When \fIbody\fR -terminates, any changes made to the \fIvarName\fRs is reflected back -to the dictionary within \fIdictionaryVariable\fR (unless -\fIdictionaryVariable\fR itself becomes unreadable, when all updates -are silently discarded), even if the result of \fIbody\fR is an error -or some other kind of exceptional exit. The result of \fBdict -update\fR is (unless some kind of error occurs) the result of the -evaluation of \fIbody\fR. -.RS -.PP -Each \fIvarName\fR is mapped in the scope enclosing the \fBdict update\fR; -it is recommended that this command only be used in a local scope -(\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of -this, the variables set by \fBdict update\fR will continue to -exist after the command finishes (unless explicitly \fBunset\fR). -Note that the mapping of values to variables -does not use traces; changes to the \fIdictionaryVariable\fR's -contents only happen when \fIbody\fR terminates. -.RE -.TP -\fBdict values \fIdictionaryValue \fR?\fIglobPattern\fR? -. -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 \fBstring match\fR) will be returned. The returned values -will be in the order of that the keys associated with those values -were inserted into the dictionary. -.TP -\fBdict with \fIdictionaryVariable \fR?\fIkey ...\fR? \fIbody\fR -. -Execute the Tcl script in \fIbody\fR with the value for each key in -\fIdictionaryVariable\fR mapped (in a manner similarly to \fBdict -update\fR) to a variable with the same name. Where one or more -\fIkey\fRs are available, these indicate a chain of nested -dictionaries, with the innermost dictionary being the one opened out -for the execution of \fIbody\fR. As with \fBdict update\fR, making -\fIdictionaryVariable\fR unreadable will make the updates to the -dictionary be discarded, and this also happens if the contents of -\fIdictionaryVariable\fR are adjusted so that the chain of -dictionaries no longer exists. The result of \fBdict with\fR is -(unless some kind of error occurs) the result of the evaluation of -\fIbody\fR. -.RS -.PP -The variables are mapped in the scope enclosing the \fBdict with\fR; -it is recommended that this command only be used in a local scope -(\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of -this, the variables set by \fBdict with\fR will continue to -exist after the command finishes (unless explicitly \fBunset\fR). -Note that the mapping of values to variables does not use -traces; changes to the \fIdictionaryVariable\fR's contents only happen -when \fIbody\fR terminates. -.PP -If the \fIdictionaryVariable\fR contains a value that is not a dictionary at -the point when the \fIbody\fR 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 \fIdictionaryVariable\fR 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 -\fBEXAMPLES\fR below for an illustration of this. -.RE -.SH "DICTIONARY VALUES" -.PP -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, -.QW "apple banana" -and -.QW "apple carrot apple banana" -are equivalent dictionaries (with different string representations). -.PP -Operations that derive a new dictionary from an old one (e.g., updates -like \fBdict set\fR and \fBdict unset\fR) 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. -.SH EXAMPLES -.PP -Basic dictionary usage: -.PP -.CS -# Make a dictionary to map extensions to descriptions -set filetypes [\fBdict create\fR .txt "Text File" .tcl "Tcl File"] - -# Add/update the dictionary -\fBdict set\fR filetypes .tcl "Tcl Script" -\fBdict set\fR filetypes .tm "Tcl Module" -\fBdict set\fR filetypes .gif "GIF Image" -\fBdict set\fR filetypes .png "PNG Image" - -# Simple read from the dictionary -set ext ".tcl" -set desc [\fBdict get\fR $filetypes $ext] -puts "$ext is for a $desc" - -# Somewhat more complex, with existence test -foreach filename [glob *] { - set ext [file extension $filename] - if {[\fBdict exists\fR $filetypes $ext]} { - puts "$filename is a [\fBdict get\fR $filetypes $ext]" - } -} -.CE -.PP -Constructing and using nested dictionaries: -.PP -.CS -# Data for one employee -\fBdict set\fR employeeInfo 12345-A forenames "Joe" -\fBdict set\fR employeeInfo 12345-A surname "Schmoe" -\fBdict set\fR employeeInfo 12345-A street "147 Short Street" -\fBdict set\fR employeeInfo 12345-A city "Springfield" -\fBdict set\fR employeeInfo 12345-A phone "555-1234" -# Data for another employee -\fBdict set\fR employeeInfo 98372-J forenames "Anne" -\fBdict set\fR employeeInfo 98372-J surname "Other" -\fBdict set\fR employeeInfo 98372-J street "32995 Oakdale Way" -\fBdict set\fR employeeInfo 98372-J city "Springfield" -\fBdict set\fR 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 [\fBdict size\fR $employeeInfo] employees" -\fBdict for\fR {id info} $employeeInfo { - puts "Employee #[incr i]: $id" - \fBdict with\fR info { - puts " Name: $forenames $surname" - puts " Address: $street, $city" - puts " Telephone: $phone" - } -} -# Another way to iterate and pick out names... -foreach id [\fBdict keys\fR $employeeInfo] { - puts "Hello, [\fBdict get\fR $employeeInfo $id forenames]!" -} -.CE -.PP -A localizable version of \fBstring toupper\fR: -.PP -.CS -# Set up the basic C locale -set capital [\fBdict create\fR C [\fBdict create\fR]] -foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] { - \fBdict set\fR capital C $c [string toupper $c] -} - -# English locales can luckily share the "C" locale -\fBdict set\fR capital en [\fBdict get\fR $capital C] -\fBdict set\fR capital en_US [\fBdict get\fR $capital C] -\fBdict set\fR capital en_GB [\fBdict get\fR $capital C] - -# ... and so on for other supported languages ... - -# Now get the mapping for the current locale and use it. -set upperCaseMap [\fBdict get\fR $capital $env(LANG)] -set upperCase [string map $upperCaseMap $string] -.CE -.PP -Showing the detail of \fBdict with\fR: -.PP -.CS -proc sumDictionary {varName} { - upvar 1 $varName vbl - foreach key [\fBdict keys\fR $vbl] { - # Manufacture an entry in the subdictionary - \fBdict set\fR vbl $key total 0 - # Add the values and remove the old - \fBdict with\fR 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: \fIlast total was 15, for key b\fR - -puts "dictionary is now \\"$myDict\\"" -# prints: \fIdictionary is now "a {total 6} b {total 15}"\fR -.CE -.PP -When \fBdict with\fR is used with a key that clashes with the name of the -dictionary variable: -.PP -.CS -set foo {foo {a b} bar 2 baz 3} -\fBdict with\fR foo {} -puts $foo -# prints: \fIa b foo {a b} bar 2 baz 3\fR -.CE -.SH "SEE ALSO" -append(n), array(n), foreach(n), mapeach(n), incr(n), list(n), lappend(n), set(n) -.SH KEYWORDS -dictionary, create, update, lookup, iterate, filter, map -'\" Local Variables: -'\" mode: nroff -'\" End: |