diff options
Diffstat (limited to 'doc/dict.n')
| -rw-r--r-- | doc/dict.n | 53 |
1 files changed, 41 insertions, 12 deletions
@@ -4,8 +4,8 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.so man.macros .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 @@ -25,11 +25,12 @@ below for a description), depending on \fIoption\fR. The legal 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. +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? . -Create a new dictionary that contains each of the key/value mappings +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 @@ -53,10 +54,10 @@ 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 {\fIkeyVar valueVar\fB} \fIscript\fR +\fBdict filter \fIdictionaryValue \fBscript {\fIkeyVariable valueVariable\fB} \fIscript\fR . The script rule tests for matching by assigning the key to the -\fIkeyVar\fR and the value to the \fIvalueVar\fR, and then evaluating +\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 @@ -74,7 +75,7 @@ of the given patterns (in the style of \fBstring match\fR.) .VE 8.6 .RE .TP -\fBdict for {\fIkeyVar valueVar\fB} \fIdictionaryValue body\fR +\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 @@ -121,7 +122,8 @@ 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. +for an existing key if that value is not an integer. The updated +dictionary value is returned. .TP \fBdict info \fIdictionaryValue\fR . @@ -145,7 +147,33 @@ 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. +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? . @@ -177,7 +205,7 @@ 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. +of nested dictionaries. The updated dictionary value is returned. .TP \fBdict size \fIdictionaryValue\fR . @@ -191,7 +219,8 @@ 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. +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 . @@ -408,9 +437,9 @@ puts $foo # prints: \fIa b foo {a b} bar 2 baz 3\fR .CE .SH "SEE ALSO" -append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n) +append(n), array(n), foreach(n), mapeach(n), incr(n), list(n), lappend(n), set(n) .SH KEYWORDS -dictionary, create, update, lookup, iterate, filter +dictionary, create, update, lookup, iterate, filter, map '\" Local Variables: '\" mode: nroff '\" End: |