Did you know ... Search Documentation:
dicts.pl -- Dict utilities
PublicShow source

This library defines utilities that operate on lists of dicts, notably to make lists of dicts consistent by adding missing keys, converting between lists of compounds and lists of dicts, joining and slicing lists of dicts.

Source mapdict(:Goal, +Dict)
Source mapdict(:Goal, ?Dict, ?Dict2)
Source mapdict(:Goal, ?Dict, ?Dict2, ?Dict3)
True when all dicts have the same set of keys and call(Goal, Key, V1, ...) is true for all keys in the dicts. At least one of the dicts must be instantiated.
Errors
- instantiation_error if no dict is bound
- type_error(dict, Culprit) if one of the dict arguments is not a dict.
- domain_error(incompatible_dict, Culprit) if Culprit does not have the same keys as one of the other dicts.
Source dicts_same_tag(+List, -Tag) is semidet
True when List is a list of dicts that all have the tag Tag.
Source dict_size(+Dict, -KeyCount) is det
True when KeyCount is the number of keys in Dict.
Source dict_keys(+Dict, -Keys) is det
True when Keys is an ordered set of the keys appearing in Dict.
Source dicts_same_keys(+List, -Keys) is semidet
True if List is a list of dicts that all have the same keys and Keys is an ordered set of these keys.
Source dicts_to_same_keys(+DictsIn, :OnEmpty, -DictsOut)
DictsOut is a copy of DictsIn, where each dict contains all keys appearing in all dicts of DictsIn. Values for keys that are added to a dict are produced by calling OnEmpty as below. The predicate dict_fill/4 provides an implementation that fills all new cells with a predefined value. 
call(:OnEmpty, +Key, +Dict, -Value)
Source dict_fill(+ValueIn, +Key, +Dict, -Value) is det
Implementation for the dicts_to_same_keys/3 OnEmpty closure that fills new cells with a copy of ValueIn. Note that copy_term/2 does not really copy ground terms. Below are two examples. Note that when filling empty cells with a variable, each empty cell is bound to a new variable. 
?- dicts_to_same_keys([r{x:1}, r{y:2}], dict_fill(null), L).
L = [r{x:1, y:null}, r{x:null, y:2}].
?- dicts_to_same_keys([r{x:1}, r{y:2}], dict_fill(_), L).
L = [r{x:1, y:_G2005}, r{x:_G2036, y:2}].

Use dict_no_fill/3 to raise an error if a dict is missing a key.

 dict_no_fill is det[private]
Can be used instead of dict_fill/4 to raise an exception if some dict is missing a key.
Source dicts_join(+Key, +DictsIn, -Dicts) is semidet
Join dicts in Dicts that have the same value for Key, provided they do not have conflicting values on other keys. For example: 
?- dicts_join(x, [r{x:1, y:2}, r{x:1, z:3}, r{x:2,y:4}], L).
L = [r{x:1, y:2, z:3}, r{x:2, y:4}].
Errors
- existence_error(key, Key, Dict) if a dict in Dicts1 or Dicts2 does not contain Key.
Source dicts_join(+Key, +Dicts1, +Dicts2, -Dicts) is semidet
Join two lists of dicts (Dicts1 and Dicts2) on Key. Each pair D1-D2 from Dicts1 and Dicts2 that have the same (==) value for Key creates a new dict D with the union of the keys from D1 and D2, provided D1 and D2 to not have conflicting values for some key. For example: 
?- DL1 = [r{x:1,y:1},r{x:2,y:4}],
   DL2 = [r{x:1,z:2},r{x:3,z:4}],
   dicts_join(x, DL1, DL2, DL).
   DL = [r{x:1, y:1, z:2}, r{x:2, y:4}, r{x:3, z:4}].
Errors
- existence_error(key, Key, Dict) if a dict in Dicts1 or Dicts2 does not contain Key.
Source dicts_slice(+Keys, +DictsIn, -DictsOut) is det
DictsOut is a list of Dicts only containing values for Keys.
Source dicts_to_compounds(?Dicts, +Keys, :OnEmpty, ?Compounds) is semidet
True when Dicts and Compounds are lists of the same length and each element of Compounds is a compound term whose arguments represent the values associated with the corresponding keys in Keys. When converting from dict to row, OnEmpty is used to compute missing values. The functor for the compound is the same as the tag of the pair. When converting from dict to row and the dict has no tag, the functor row is used. For example: 
?- Dicts = [_{x:1}, _{x:2, y:3}],
   dicts_to_compounds(Dicts, [x], dict_fill(null), Compounds).
Compounds = [row(1), row(2)].
?- Dicts = [_{x:1}, _{x:2, y:3}],
   dicts_to_compounds(Dicts, [x,y], dict_fill(null), Compounds).
Compounds = [row(1, null), row(2, 3)].
?- Compounds = [point(1,1), point(2,4)],
   dicts_to_compounds(Dicts, [x,y], dict_fill(null), Compounds).
Dicts = [point{x:1, y:1}, point{x:2, y:4}].

When converting from Dicts to Compounds Keys may be computed by dicts_same_keys/2.

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.

Source mapdict(:Goal, +Dict)
Source mapdict(:Goal, ?Dict, ?Dict2)
Source mapdict(:Goal, ?Dict, ?Dict2, ?Dict3)
True when all dicts have the same set of keys and call(Goal, Key, V1, ...) is true for all keys in the dicts. At least one of the dicts must be instantiated.
Errors
- instantiation_error if no dict is bound
- type_error(dict, Culprit) if one of the dict arguments is not a dict.
- domain_error(incompatible_dict, Culprit) if Culprit does not have the same keys as one of the other dicts.
Source mapdict(:Goal, +Dict)
Source mapdict(:Goal, ?Dict, ?Dict2)
Source mapdict(:Goal, ?Dict, ?Dict2, ?Dict3)
True when all dicts have the same set of keys and call(Goal, Key, V1, ...) is true for all keys in the dicts. At least one of the dicts must be instantiated.
Errors
- instantiation_error if no dict is bound
- type_error(dict, Culprit) if one of the dict arguments is not a dict.
- domain_error(incompatible_dict, Culprit) if Culprit does not have the same keys as one of the other dicts.

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

Source dict_no_fill(Arg1, Arg2, Arg3)