[ 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

- must_be(+, ?) is det

## See Also

type_of / 2