4.5 Verify Type of a Term

Type tests are semi-deterministic predicates that succeed if the argument satisfies the requested type. Type-test predicates have no error condition and do not instantiate their argument. They have no first-order “logical” interpretation; instead they inspect the state of the computation at call time and are mainly used in clause guards and assertions. See also library library(error), must_be/2 and assertion/1.

[ISO]var(@Term)

True if Term currently is a free variable. The compiler warns if Term is syntactically not a variable.

[ISO]nonvar(@Term)

True if Term currently is not a free variable. This is the logical complement of var/1: var(X) is true iff nonvar(X) fails.

[ISO]integer(@Term)

True if Term is bound to an integer.

[ISO]float(@Term)

True if Term is bound to a floating point number.

rational(@Term)

True if Term is bound to a rational number. Rational numbers include integers.

rational(@Term, -Numerator, -Denominator)

True if Term is a rational number with given Numerator and Denominator. The Numerator and Denominator are in canonical form, which means Denominator is a positive integer and there are no common divisors between Numerator and Denominator.

[ISO]number(@Term)

True if Term is bound to a rational number (including integers) or a floating point number.

[ISO]atom(@Term)

True if Term is bound to an atom.

blob(@Term, ?Type)

True if Term is a blob of type Type. See section 12.4.10. For a blob read using the blob(dead) option of read_term/3, Type is the type the blob stands for, while current_blob/2 reports its real type unavailable.

blob_released(@Term)

True if Term is a blob whose data was released using PL_free_blob(). Such a blob still exists as a term and keeps its type, but the object it referred to is gone: it writes as <Type>(freed) and every predicate that expects the real thing rejects it. Note that only blobs can be released; an ordinary atom is reclaimed as a whole by the atom garbage collector and remains valid for as long as it exists.

string(@Term)

True if Term is bound to a string. Note that string here refers to the built-in atomic type string as described in section 5.2. Starting with version 7, the syntax for a string object is text between double quotes, such as "hello".^{65In traditional Prolog systems, double quoted text is often mapped to a list of character codes.} See also the Prolog flag double_quotes.

[ISO]atomic(@Term)

True if Term is bound (i.e., not a variable) and is not compound. Thus, atomic acts as if defined by:

atomic(Term) :-
        nonvar(Term),
        \+ compound(Term).

SWI-Prolog defines the following atomic datatypes: atom (atom/1), string (string/1), integer (integer/1), floating point number (float/1), rational (rational/1) and blob (blob/2). In addition, the symbol [] (empty list) is atomic, but not an atom. See section 5.1.

[ISO]compound(@Term)

True if Term is bound to a compound term. See also compound_name_arity/3, compound_name_arguments/3, functor/3 and =../2.

[ISO]callable(@Term)

True if Term is bound to an atom or a compound term. This was intended as a type-test for arguments to call/1, call/2 etc. Note that callable only tests the surface term. Terms such as (22,true) are considered callable, but cause call/1 to raise a type error. Module-qualification of meta-argument (see meta_predicate/1) using :/2 causes callable to succeed on any meta-argument.^{66We think that callable/1 should be deprecated and there should be two new predicates, one performing a test for callable that is minimally module aware and possibly consistent with type-checking in call/1 and a second predicate that tests for atom or compound.} Consider the program and query below:

:- meta_predicate p(0).

p(G) :- callable(G), call(G).

?- p(22).
ERROR: Type error: `callable' expected, found `22'
ERROR: In:
ERROR:    [6] p(user:22)

[ISO]ground(@Term)

True if Term holds no free variables. See also nonground/2 and term_variables/2.

cyclic_term(@Term)

True if Term contains cycles, i.e. is an infinite term (also known as a rational tree). See also acyclic_term/1 and section 2.16.^{67The predicates cyclic_term/1 and acyclic_term/1 are compatible with SICStus Prolog. Some Prolog systems supporting cyclic terms use is_cyclic/1 .}

[ISO]acyclic_term(@Term)

True if Term does not contain cycles, i.e. can be processed recursively in finite time. This includes Term being an unbound variable. See also cyclic_term/1 and section 2.16.