1.11.1 A Basic API for Interned Tries

new_trie(-Root)

intern
Root is instantiated to a handle for a new trie.

trie_intern(+Term,+Root)

intern
Effectively asserts Term by interning into the trie designated by Root. If a variant of Term is already in Root the predicate succeeds, but a new copy of Term is not added to the trie.

Error Cases

• Root is uninstantiated
  • instantiation_error
• Root is instantiated, but not an integer (trie handle)
  • type_error(integer,Root)

trie_interned(?Term,+Root)

intern
This predicate backtracks through the terms that unify with Term and that are interned into the trie represented by the handle Root. Term may be free, or partially bound.

Error Cases

• Root is uninstantiated
  • instantiation_error
• Root is instantiated, but not an integer (trie handle)
  • type_error(integer,Root)

trie_retractall(?Term,+Root)

intern
Uninterns from Root all terms that unify with Term. If there are no failure continuations pointing to nodes in Root, space is reclaimed for the uninterned nodes; otherwise they are marked as deleted but space is not reclaimed.

Error Cases

• Root is uninstantiated
  • instantiation_error
• Root is instantiated, but not an integer (trie handle)
  • type_error(integer,Root)

bulk_trie_insert(+Generator,+Root)

intern
Used to insert multiple terms into Root. Generator is a callable term. Upon backtracking through Generator its first argument should successively be instantiated to the terms to be interned in Root. When inserting many terms, bulk_trie_insert/2 is faster than trie_insert as it does not need to make multiple checks that the choice point stack is free of failure continuations that point to nodes in the trie pointed to by Root.

Example 1.11.1   Given the predicate

bulk_create(p(One,Two,Three),N):- 
     for(One,1,N),
     for(Two,1,N),
     for(Three,1,N).

The goal bulk_trie_intern(bulk_create(_Term,N),Trie) will add $N^3$ terms to the trie with root Root.

Error Cases

• Root is uninstantiated
  • instantiation_error
• Root is instantiated, but not an integer (trie handle)
  • type_error(integer,Root)

delete_trie(+Root)

intern
Deletes all the terms in the trie pointed to by Root.

Error Cases

• Root is uninstantiated
  • instantiation_error
• Root is instantiated, but not an integer (trie handle)
  • type_error(integer,Root)
• Failure continuations point to one or more nodes in the trie with root Root
  • misc_error