
must_be(+Type, ?Term)

   Test a term for an expected type and throw an error if it does not match

Arguments
   Type                The name or descriptor of the expected type
   Term                The term to be tested

Type
   library(error)

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
