diff options
Diffstat (limited to 'doc/dict.n')
| -rw-r--r-- | doc/dict.n | 55 |
1 files changed, 51 insertions, 4 deletions
@@ -27,6 +27,11 @@ 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. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the appending operation. +.VE TIP508 .TP \fBdict create \fR?\fIkey value ...\fR? . @@ -49,10 +54,8 @@ 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 . @@ -69,10 +72,8 @@ 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 @@ -115,6 +116,22 @@ It is an error to attempt to retrieve a value for a key that is not present in the dictionary. .RE .TP +\fBdict getdef \fIdictionaryValue \fR?\fIkey ...\fR? \fIkey default\fR +.TP +\fBdict getwithdefault \fIdictionaryValue \fR?\fIkey ...\fR? \fIkey default\fR +.VS "8.7, TIP342" +This behaves the same as \fBdict get\fR (with at least one \fIkey\fR +argument), returning the value that the key path maps to in the +dictionary \fIdictionaryValue\fR, except that instead of producing an +error because the \fIkey\fR (or one of the \fIkey\fRs on the key path) +is absent, it returns the \fIdefault\fR argument instead. +.RS +.PP +Note that there must always be at least one \fIkey\fR provided, and that +\fBdict getdef\fR and \fBdict getwithdefault\fR are aliases for each other. +.RE +.VE "8.7, TIP342" +.TP \fBdict incr \fIdictionaryVariable key \fR?\fIincrement\fR? . This adds the given increment value (an integer that defaults to 1 if @@ -124,6 +141,11 @@ 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. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the incrementing operation. +.VE TIP508 .TP \fBdict info \fIdictionaryValue\fR . @@ -149,6 +171,11 @@ 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. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the list-appending operation. +.VE TIP508 .TP \fBdict map \fR{\fIkeyVariable valueVariable\fR} \fIdictionaryValue body\fR . @@ -206,6 +233,11 @@ 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. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the value insert/update operation. +.VE TIP508 .TP \fBdict size \fIdictionaryValue\fR . @@ -221,6 +253,11 @@ 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. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the value remove operation. +.VE TIP508 .TP \fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR . @@ -236,6 +273,11 @@ 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. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the update operation. +.VE TIP508 .RS .PP Each \fIvarName\fR is mapped in the scope enclosing the \fBdict update\fR; @@ -270,6 +312,11 @@ dictionary be discarded, and this also happens if the contents 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. +.VS TIP508 +If \fIdictionaryVariable\fR indicates an element that does not exist of an +array that has a default value set, the default value and will be used as the +value of the dictionary prior to the updating operation. +.VE TIP508 .RS .PP The variables are mapped in the scope enclosing the \fBdict with\fR; |