[ 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 singlecharacter atom
 chars

a list of singlecharacter 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 nonvariables, 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