10.24 Term Utilities—library(terms)

This library module provides miscellaneous operations on terms. Exported predicates:

subsumeschk(+General, +Specific)

is true when Specific is an instance of General. It does not bind any variables.

subsumes(+General, +Specific)

is true when Specific is an instance of General. It will bind variables in General (but not those in Specific) so that General becomes identical to Specific.

variant(+Term, +Variant)

is true when Term and Variant are identical modulo renaming of variables, provided Term and Variant have no variables in common.

term_subsumer(+Term1, +Term2, -Term)

binds Term to a most specific generalisation of Term1 and Term2. Using Plotkin's algorithm [Machine Intelligence 5, 1970], extended by Dan Sahlin to handle cyclic structures.

term_hash(+Term, -Hash)

If Term is ground, an integer hash value corresponding to Term is unified with Hash. Otherwise, the goal just succeeds.

term_hash(+Term, +Depth, +Range, -Hash)

If Term is instantiated to the given Depth, an integer hash value in the range [0,Range) corresponding to Term is unified with Hash. Otherwise, the goal just succeeds.

term_variables(+Term, -Variables)

True if Variables is the set of variables occurring in Term.

term_variables_bag(+Term, -Variables)

True if Variables is the list of variables occurring in Term, in first occurrence order.

acyclic_term(+X)

True if X is finite (acyclic). Runs in linear time.

cyclic_term(+X)

True if X is infinite (cyclic). Runs in linear time.

term_order(+X, +Y, -R)

is true when X and Y are arbitrary terms, and R is <, =, or > according as X @< Y, X == Y, or X @> Y. This is the same as compare/3, except for the argument order.

contains_term(+Kernel, +Expression)

is true when the given Kernel occurs somewhere in the Expression. It can only be used as a test; to generate sub-terms use sub_term/2.

free_of_term(+Kernel, +Expression)

is true when the given Kernel does not occur anywhere in the Expression. NB: if the Expression contains an unbound variable, this must fail, as the Kernel might occur there. Since there are infinitely many Kernels not contained in any Expression, and also infinitely many Expressions not containing any Kernel, it doesn't make sense to use this except as a test.

occurrences_of_term(+Kernel, +Expression, -Tally)

is true when the given Kernel occurs exactly Tally times in Expression. It can only be used to calculate or test Tally; to enumerate Kernels you'll have to use sub_term/2 and then test them with this routine. If you just want to find out whether Kernel occurs in Expression or not, use contains_term/2 or free_of_term/2.

contains_var(+Variable, +Term)

is true when the given Term contains at least one sub-term which is identical to the given Variable. We use == to check for the variable (contains_term/2 uses =) so it can be used to check for arbitrary terms, not just variables.

free_of_var(+Variable, +Term)

is true when the given Term contains no sub-term identical to the given Variable (which may actually be any term, not just a var). For variables, this is precisely the "occurs check" which is needed for sound unification.

occurrences_of_var(+Term, +Variable, -Tally)

is true when the given Variable occurs exactly Tally times in Term. It can only be used to calculate or test Tally; to enumerate Variables you'll have to use sub_term/2 and then test them with this routine. If you just want to find out whether Variable occurs in Term or not, use contains_var/2 or free_of_var/2.

sub_term(?Kernel, +Term)

is true when Kernel is a sub-term of Term. It enumerates the sub-terms of Term in an arbitrary order. Well, it is defined that a sub-term of Term will be enumerated before its own sub-terms are (but of course some of those sub-terms might be elsewhere in Term as well).

depth_bound(+Term, +Bound)

is true when the term depth of Term is no greater than Bound, that is, when constructor functions are nested no more than Bound deep. Later variable bindings may invalidate this bound. To find the (current) depth, use term_depth/2.

length_bound(?List, +Bound)

is true when the length of List is no greater than Bound. It can be used to enumerate Lists up to the bound.

size_bound(+Term, +Bound)

is true when the number of constant and function symbols in Term is (currently) at most Bound. If Term is non-ground, later variable bindings may invalidate this bound. To find the (current) size, use term_size/2.

term_depth(+Term, -Depth)

          calculates the Depth of a Term, using the definition
              term_depth(Var) = 0
              term_depth(Const) = 0
              term_depth(F(T1,...,Tn)) = 1+max(term_depth(T1),...,term_depth(Tn))
     

term_size(+Term, -Size)

calculates the Size of a Term, defined to be the number of constant and function symbol occurrences in it.

same_functor(?T1, ?T2)

is true when T1 and T2 have the same principal functor. If one of the terms is a variable, it will be instantiated to a new term with the same principal functor as the other term (which should be instantiated) and with arguments being new distinct variables. If both terms are variables, an error is reported.

same_functor(?T1, ?T2, ?N)

is true when T1 and T2 have the same principal functor, and their common arity is N. Like same_functor/3, at least one of T1 and T2 must be bound, or an error will be reported.

same_functor(?T1, ?T2, ?F, ?N)

is true when T1 and T2 have the same principal functor, and their common functor is F/N. Given T1 (or T2) the remaining arguments can be computed. Given F and N, the remaining arguments can be computed. If too many arguments are unbound, an error is reported.