[ 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