2.20.4 Atom map utilities

The include file SWI-cpp2-atommap.h contains a templated class AtomMap for mapping atoms to atoms or terms. The typical use case is for when it is desired to open a database or stream and, instead of passing around the blob, an atom can be used to identify the blob.

The keys in the map must be standard Prolog atoms and not blobs - the code depends on the fact that an atom has a unique ID.

The AtomMap is thread-safe (it contains a mutex). It also takes care of reference counts for both the key and the value. Here is a typical use case:

static AtomMap<PlAtom, PlAtom> map_atom_my_blob("alias", "my_blob");

// look up an entry:
   auto value = map_atom_my_blob(A1.as_atom());
   PlCheckFail(value.not_null());

// insert an entry:
   map_atom_my_blob.insert(A1.as_atom(), A2.as_atom());

// remove an entry:
   map_atom_my_blob.erase(A1.as_atom());

The constructor and methods are as follows:

• template<ValueType, StoredValueType> AtomMap::AtomMap(const std::string& insert_op)
  const std::string& insert_type Construct an AtomMap. The ValueType and StoredValueType specify what type you wish for the value. Currently, two value types are supported:

  • PlAtom - the StoredValueType should be PlAtom.
  • PlTerm - the StoredValueType shoud be PlRecord (because the term needs to be put on the global stack).

  The insert_op and insert_type values are used in constructing error terms - these correspond to the operation and type arguments to Pl_permission_error().

  insert PlAtom key, ValueType value(I)
  nserts a new value; raises a permission_error if the value is already in the map, unless the value is identical to the value in the map. The insert() method converts the value to the StoredValueType. The insertion code takes care of atom reference counts.

  ValueType find(PlAtom key)
  Look up an entry. Success/failure can be determined by using ValueType::is_null() or ValueType::not_null(). The stored value is converted from StoredValueType to ValueType.

  erase PlAtom(r)
  emoves the entry from the map. If there was no entry in the map with that key, this is a no-op. The erasure code takes care of atom reference counts.