[ library(error) | Reference Manual | Alphabetic Index ]

must_be(+Type, ?Term)

Test a term for an expected type and throw an error if it does not match
Type
The name or descriptor of the expected type
Term
The term to be tested

Description

This predicate performs a runtime type test and throws an error if the test fails. The supported type descriptors include:

acyclic
an acyclic term, see acyclic/1
array
an array, i.e. a structure with functor []/N
atom
an atom, see atom/1
atomic
not a compound term, see atomic/1
between(L,H)
number between L and H, must be integer if L,H are integer
boolean
one of the atoms 'true' or 'false'
breal
a bounded real, see breal/1
callable
an atom or compound term, see callable/1
char
a single-character atom
chars
a list of single-character atoms
code
an integer character code
codes
a list of integer character codes
compound
a compound term (including list and array)
cyclic
a cyclic term, see cyclic/1
encoding
an atom specifying a character encoding, such as 'iso_latin_1'
float
a floating point number, see float/2
ground
a ground (i.e. fully instantiated) term, see ground/1
handle
a handle, see is_handle/1
handle(Class)
a handle of the given class, see is_handle/2
list
a proper list
list(Type)
a proper list with elements of Type
list_or_partial_list
a proper or partial (i.e. ending in a variable) list
negative_integer
integer less than zero
nonneg
integer greater or equal to zero
nonvar
any non-variables, see nonvar/1
number
any number, see number/1
oneof(Values)
a member of the list Values
positive_integer
integer greater than zero
rational
a rational number, see rational/1
real
a float or breal number, see real/1
string
a string, see string/1
text
string, atom, chars or codes
var
an (uninstantiated) variable
Many of these correspond to a simple type testing predicate. Note that tests that require traversal of compound terms (such as 'cyclic' or 'list') can be expensive.

If Term does not satisfy the expected type, one of the following error terms is thrown, as appropriate:

error(instantiation_error, _)
an variable was detected where an instantiated term was expected
error(uninstantiation_error(Term), _)
an instantiated term was detected where a variable was expected
error(type_error(Type,Term), _)
Term is not of type Type
error(domain_error(Type,Term), _)
Term is of the right general type but has an unacceptable value
A domain error is used instead of a type error when a number is outside an expected range, or an atom is not in the expected set.

If Type is not one of the recognized types, it is assumed that the type test failed, and one of the following error terms is thrown:

error(instantiation_error, _)
if Term was a variable
error(type_error(Type,Term), _)
otherwise

Modes and Determinism

See Also

type_of / 2