Language Reference/Built-in entities

Visual Prolog contains an embedded hidden class, which provides declarations and implementations to all built-in constants, domains, and predicates.

These built-in constants, domains, and predicates can be used both during compilation (for example, in #if ... constructions) and in implementations (which are supported for runtime).

Each compilation unit implicitly contains the declaration of this embedded hidden class. To disambiguate from other entities with the same name you can use "::" before names of built-in items.

Notice that the clause variable This is automatically defined in the clauses for object predicates.

Operators

See also Operators.

Operator	Description	Remark
^	Power operation	Not defined for 64 bit integral numbers
- (unary)	Unary minus
*, /	Multiplication and division
div, mod	The quotient and remainder of an integral division rounded towards minus infinity	Not defined for real's
quot, rem	The quotient and remainder of an integral division rounded towards zero	Not defined for real's
+, -	Addition and subtraction
otherwise	Otherwise expression

• The operators are listed from highest to lowest precedence
• All division and multiplication operators have same precedence.
• The power operator ^ and otherwise are right associative.
• All other operators are left associative.

All binary operators takes two arguments of same base type and returns a value of that base type. Operands and result may be converted using ordinary subtype rules.

Integral division

div and quot are different integral division operators.

• div truncates towards minus infinite. mod is the remainder corresponding to div.
• quot truncates towards zero. rem is the remainder corresponding to quot.

For positive results div and quot have same functionality.

The difference can be seen in this table:

A	B	A div B	A mod B	A quot B	A rem B
15	7	2	1	2	1
-15	7	-3	6	-2	-1
15	-7	-3	-6	-2	1
-15	-7	2	-1	2	-1

Constants

compilation_date	Compilation date
compilation_time	Compilation time
compiler_buildDate	Build date of the compiler
compiler_version	Compiler version number
maxFloatDigits	Maximum supported digits for real domains
null	The default NULL pointer
nullHandle	A constant of type handle with value 0
invalidHandle	A constant of type handle with value −1 (invalid)
platform_bits	Bitness of the compilation platform (32 or 64)
platform_name	Target platform name

compilation_date

Compilation date in the format YYYY-MM-DD.

compilation_date : string = "YYYY-MM-DD".

compilation_time

Compilation time in the format HH:MM:SS (24-hour clock).

compilation_time : string = "HH:MM:SS".

compiler_buildDate

Build date of the compiler in the format YYYY-MM-DD HH:MM.

compiler_buildDate : string = "YYYY-MM-DD HH:MM".

compiler_version

Compiler version number (value depends on the compiler).

compiler_version = 1100.

maxFloatDigits

Maximum supported value of digits for real domains.

maxFloatDigits = 16.

null

A constant of type pointer with the value 0.

null : pointer = uncheckedConvert(pointer, 0).

null is also implicitly defined on all interfaces as a null pointer of the interface type. If it were defined explicitly, it would look like this:

interface xxx
...
constants
    null : xxx = uncheckedConvert(xxx, null).  % already implicitly defined
...
end interface xxx

Example This example shows how the constant can be used in a clause.

interface xxx
end interface xxx
 
...
clauses
    isNullXxx(X) :-
        xxx::null = X.

nullHandle

A constant of type handle with the value 0.

nullHandle : handle = uncheckedConvert(handle, 0).

invalidHandle

A constant of type handle with the value -1 (invalid for a handle).

invalidHandle : handle = uncheckedConvert(handle, -1).

platform_bits

Bitness of the compilation platform.

platform_bits = 32.
or
platform_bits = 64.

platform_name

Target platform name.

platform_name : string = "Windows 32bits".
or
platform_name : string = "Windows 64bits".

Domains

any	Universal term type
char	Unicode character (16-bit)
string	UTF-16 zero-terminated string
string8	Zero-terminated 8-bit string typically in UTF-8 encoding
symbol	Interned UTF-16 string (global symbol table)
binary	Byte sequence (non-scanned)
binaryNonAtomic	Byte sequence (GC-scanned; may contain pointers)
integer	32-bit signed integer
integer64	64-bit signed integer
integerNative	Platform-sized signed integer (32/64-bit)
unsigned	32-bit unsigned integer
unsigned64	64-bit unsigned integer
unsignedNative	Platform-sized unsigned integer (32/64-bit)
real	Floating-point number (64-bit)
real32	Floating-point number (32-bit)
pointer	Pointer value
pointerTo	Pointer to a value of a given type
handle	Operating system handle (e.g., Windows)
boolean	Boolean values
factDB	Descriptor of a named internal database
compareResult	Result of a comparison

any

Universal term type.

any

Values of this domain can hold any term. Such a value contains a reference to the type library of the term and the term itself.

char

Unicode character.

char

Values of this domain are Unicode characters implemented as two unsigned bytes.

Only assignment and comparison (lexicographical) are defined. The image of a character has the following syntax:

Char_image :
      ' Char_value '
Char_value :
      Letter
      Digit
      Graphical_symbol
      Escape_seq
Escape_seq:
      \t
      \n
      \r
      \\
      \'
      \"
      \u<HHHH>

In the syntax above HHHH corresponds to four hexadecimal digits. The backslash and single quote can only be represented by escape sequences.

compareResult

The result domain for comparisons (e.g., compare/2->).

domains
   compareResult = less; equal; greater.

string

UTF-16 strings.

string

A string is a pointer to a zero-terminated sequence of UTF-16 code units. Elements are 16-bit values; certain characters are encoded using surrogate pairs. Strings are immutable.

In source code a string literal is one or more parts surrounded by double quotes:

StringLiteral:
   StringLiteralPart-list

StringLiteralPart :
   @" AnyCharacter-list-opt "
   " CharacterValue-list-opt "

Parts starting with @ do not use escape sequences; parts without @ use the following escapes:

• \\ representing \
• \t representing a tab character
• \n representing a newline character
• \r representing a carriage return
• \' representing a single quote
• \" representing a double quote
• \u followed by exactly four HexadecimalDigit values representing the Unicode character

Double quotes in strings must be written using the escape sequence (single quotes may be written directly or escaped).

string8

A built-in domain whose elements are sequences of one-byte characters (bytes). Implemented as a pointer to a zero-terminated array of bytes.

Literals. The same string literal syntax (`"..."`) can be used both as a string literal and as a string8 literal, depending on context:

• When a string8 value is expected, the literal is compiled as UTF-8 bytes with a trailing zero
• When a string value is expected, the literal is compiled as UTF-16 code units with a trailing zero

If the context is ambiguous, disambiguate by using a typed context (e.g., a predicate parameter of type string8) or by explicit conversion.

Example

predicates
    use8  : (string8 S8).
    use16 : (string  S).
 
clauses
    demo() :-
        use8("Hello"),   % literal used as string8 (UTF-8)
        use16("Hello").  % the same literal used as string (UTF-16)

symbol

UTF-16 strings with the same representation as string, but also stored in a global symbol table.

symbol

A symbol is interned in a global symbol table; identical symbols share the same pointer value. Symbols are never reclaimed, so they should not be used for large, short-lived text.

symbol is a subtype of string, so a symbol can be used wherever a string is expected. The opposite is not automatic; to obtain a symbol from a string, explicitly convert to the symbol domain (or a subtype).

Equality is efficient for symbol values (pointer equality). Other comparisons behave like the corresponding string operations.

binary

Sequence of bytes.

binary

Used for holding binary data. A value is a pointer to the byte sequence that represents the contents of the binary term.

The length of a binary term is stored in the four bytes immediately preceding the sequence:

TotalNumberOfBytesOccupiedByBinary = ByteLen + 4

where ByteLen is the length of the sequence and 4 is the size field.

Only assignment and comparison are defined.

Two binaries are compared as follows:

• If sizes differ, the larger size is greater
• Otherwise, compare bytes (as unsigned) until a difference is found; equal if sizes match and all bytes are equal

The text syntax for binary images is determined by Binary:

Binary :
       $ [ Byte_value-comma-sep-list-opt ]
Byte_value :
      Expression

Each expression must be computable at compile time and have a value in the range 0.. 255.

binaryNonAtomic

Sequence of bytes.

binaryNonAtomic

Same as binary, but may contain pointers and is scanned by the garbage collector.

integer

32-bit signed integer.

integer

Values occupy 4 bytes. Arithmetic (+, -, /, *, ^), comparison, assignment, div/2->, mod/2->, quot/2->, and rem/2-> are defined.

Range: -2147483648 .. 2147483647.

Literals follow Integer:

Integer :
      Add_operation-opt 0o Oct_number
      Add_operation-opt Dec_number
      Add_operation-opt 0x Hex_number
Add_operation :
      +
      -
Oct_number :
      Oct_digit-list
Oct_digit : one of
      0 1 2 3 4 5 6 7
Dec_number :
      Dec_digit-list
Dec_digit : one of
      Oct_digit 8 9
Hex_number :
      Hex_digit-list
Hex_digit : one of
      Dec_digit a b c d e f A B C D E F

integer64

64-bit signed integer.

integer64

Values occupy 8 bytes.

Range: -2^63 = -9223372036854775808 .. 2^63-1 = 9223372036854775807.

Literals use the same syntax as Integer. The available operations mirror those for Integer.

integerNative

Platform-sized signed integer (32-bit in 32-bit programs; 64-bit in 64-bit programs).

integerNative

unsigned

32-bit unsigned integer.

unsigned

Values occupy 4 bytes. Arithmetic (+, -, /, *, ^), comparison, assignment, div/2->, mod/2->, rem/2->, and quot/2-> are defined.

Range: 0 .. 4294967295.

Literals use the same syntax as integer numbers. A leading minus (UnaryMinus) is not allowed for an unsigned literal.

unsigned64

64-bit unsigned integer.

unsigned64

Values occupy 8 bytes.

Range: 0 .. 2^64-1 = 18,446,744,073,709,551,615.

Literals use the same syntax as integer64 numbers. A leading minus (UnaryMinus) is not allowed for an unsigned64 literal.

Operations mirror those for Unsigned.

unsignedNative

Platform-sized unsigned integer (32-bit in 32-bit programs; 64-bit in 64-bit programs).

unsignedNative

real

Floating-point number.

real

Values occupy 8 bytes. All arithmetic, comparison, and assignment operations are defined.

Range: approximately -1.7e+308 .. 1.7e+308. Integral values are implicitly converted to real when needed.

Floating-point literals follow Real:

Real :
      Add_operation-opt Fraction Exponent-opt
Fraction :
      Dec_number Fractional_part-opt
Fractional_part :
      . Dec_number
Exponent :
      Exp Add_operation-opt Dec_number
Exp :
      e
      E
Add_operation :
      +
      -
Dec_number :
      Dec_digit-list
Dec_digit : one of
      0 1 2 3 4 5 6 7 8 9

real32

Floating-point number.

real32

Values occupy 4 bytes. All arithmetic, comparison, and assignment operations are defined.

Range: approximately -3.4e+38 .. 3.4e+38.

The syntax of real32 literals is the same as for real literals.

pointer

A pointer to a memory address.

pointer

Corresponds directly to memory addresses. Only equality comparison is defined. There is a built-in null constant for this type.

pointerTo

pointerTo{Type} represents a pointer to a value of type Type. Conceptually (it is built-in), it can be viewed as:

domains
    pointerTo{Type} = pointerTo(Type Value).

handle

Used for Windows API calls. Values have the same size as a pointer (4 bytes on 32-bit, 8 bytes on 64-bit platforms).

No operations are defined for this domain, and values cannot be converted to/from other domains (except via uncheckedConvert).

There are built-in constants: nullHandle and invalidHandle.

boolean

Boolean values.

boolean

This domain is provided for convenience and is treated as a normal compound domain:

domains
   boolean = false; true.

factDB

Descriptors of named internal databases.

factDB

This domain has the following hidden meta-declaration:

domains
   factDB = struct @factdb( named_internal_database_domain, object ).

All user-defined names of facts sections are constants of this domain. The compiler automatically builds the corresponding compound terms when needed. At runtime, the first field holds the address of the corresponding domain descriptor, and the second holds either zero (for class facts sections) or a pointer to an object (e.g., This for object facts sections).

Predicates

and/2 ,/2	Term "and"
assert/1	Insert the specified fact at the end of the matched internal facts database.
asserta/1	Insert a fact at the beginning of the matched internal facts database.
assertz/1	Insert a fact at the end of the matched internal facts database.
bound/1 determ	Test whether the specified variable is bound to a value.
class_name/0->	This compile time predicate returns the string ClassName that represents the name of the current interface or class.
compare/2->	Returns the result of the variables' comparison.
constant_name/0->	This compile time predicate returns the string ConstantName that represents the name of the current constant. Typically used in execepion definitions.
convert/2->	Checked term conversion.
digitsOf/1->	Returns precision of the specified floating-point domain.
errorExit/1 erroneous	Performs a run-time error with the specified return code ErrorNumber and sets the internal error information.
fact_address/1->	Returns the address of a fact variable.
fail/0 failure	Invoke backtracking.
free/1 determ	Check whether a variable is free.
fromEllipsis/1->	Creates the list of terms of the universal type any from the EllipsisBlock.
hasDomain/2 hasDomain/2->	Declares/restricts the type of a variable or value.
in/2 determ in/2 nondeterm	Infix operator "in" (in-test and in-iterator).
isErroneous/1 determ	Returns the lower bound value of the specified numeric domain.
lowerBound/1->	Returns the lower bound value of the specified numeric domain.
maxDigits/1->	Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain domainName.
not/1 determ	Negate the result (success/fail) of subgoal.
otherwise/2	Infix expression operator providing a value when a determ expression fails
or/2 ;/2	Nondeterministic term "or"
orelse	Deterministic term "or"
predicate_fullname/1->	This compile time predicate returns the string PredicateFullName that represent the name of the predicate in which clause body predicate_name is called. The returned predicate name is qualified with a scope name.
predicate_name/1->	This compile time predicate returns the string PredicateName that represent the name of the predicate in which clause body predicate_name is called. The returned predicate name is not qualified with a scope name.
programPoint/0->	This compile time predicate returns the programPoint corresponding to the place where it is called.
retract/1 nondeterm	Remove a matched fact from the matched internal facts database.
retractall/1	Remove all matching facts from the matched internal facts database.
retractFactDb/1	Remove all facts from the specified named internal facts database.
sizeBitsOf/1->	Retrieves the number of bits occupied in memory by an entity of the specified domain DomainName.
sizeOf/1->	Retrieves the number of bytes occupied in memory by the specified term.
sizeOfDomain/1->	Retrieves the number of bytes occupied in memory by the entity of the specified domain DomainName.
sourcefile_lineno/0->	Returns the current line number in the source file processed by the compiler .
sourcefile_name/0->	Returns the name of the source file processed by the compiler.
sourcefile_timestamp/0->	Returns the string representing the date and time of the source file processed by the compiler.
succeed/0	The predicate succeed/0 will always succeed.
toAny/1->	Converts the specified Term to the value of the universal term type any.
toBinary/1->	Converts the specified Term to the binary representation.
toBoolean/1->	The purpose of this meta-predicate is to convert the deterministic call (to a predicate or fact) to the procedure that returns the value of boolean domain.
toEllipsis/1->	Creates the EllipsisBlock from the list of any type values.
toString/1->	Converts the specified Term to the string representation.
toTerm/1-> toTerm/2->	Converts the string/binary representation of the specified term SrcTerm into representation corresponding to the domain of PrologTerm variable of the return value.
tryToTerm/1-> determ tryToTerm/2-> determ	Converts the string/binary representation of the specified term SrcTerm into representation corresponding to the domain of PrologTerm variable of the return value.
tryConvert/2-> determ	Checks whether the input term InputTerm can be strictly converted into the specified domain returnDomain and returns the converted term ReturnTerm.
typeDescriptorOf/1->	Returns the typeDescriptor of a value.
typeLibraryOf/1->	Returns the typeLibrary of a value.
uncheckedConvert/2->	Unchecked conversion of domains.
upperBound/1->	Returns the upper bound value of the specified numeric domain.

The following predicates are deprecated:

finally/2	Use try-finally constuction instead.
findall/3	Use list comprehension [ ... || ...  ] instead
trap/3 determ	Use try-catch constuction instead.

and

See and (,).

assert

assert : (<fact-term> FactTerm).

Insert the specified fact at the end of the matched internal facts database

assert(Fact) inserts Fact in the matched internal facts database after any other stored facts for the corresponding database predicate. Fact must be a term belonging to the domain of an internal facts database. assert/1 applied to a single fact changes the existing instance of a fact to the specified one. assert/1 has the same effect as assertz/1. See also asserta/1.

Notice that the combination of retract/1 and assert/1 like the following can lead to endless loop:

loop() :-
  retract(fct(X)),
     ...           % creating Y from X
     assert(fct(Y)),
  fail.

The problem is that the retract in first line will eventually retract the fact asserted in the last line, because that fact is inserted last in the fact chain.

Exceptions:

• Attempt to assert a second instance to a fact declared as determ.

asserta

asserta : (<fact-term> FactTerm).

Insert a fact at the beginning of the matched internal facts database.

The asserta(Fact) predicate inserts a Fact in the matched internal facts database before any other stored facts for the corresponding predicate. The Fact must be a term belonging to the domain of an internal facts database. The asserta/1 applied to a single fact changes the existing instance of a fact to the specified one. See also assert/1 and assertz/1.

Exceptions:

• Attempt to a fact declared as determ, but the fact instance already exists.

assertz

assertz : (<fact-term> FactTerm).

assertz does exactly the same as the assert/1 predicate.

bound

bound : (<variable> Variable) determ.

Test whether the specified variable is bound to a value.

The bound(Variable) succeeds if Variable is bound and fails if it is free. The bound predicate is used to control flow patterns and to check the binding of reference variables. The bound predicate treats the specified Variable as bound if any of it's part is instantiated.

See also free/1.

class_name

class_Name : () -> string ClassName.

This compile time predicate returns the string ClassName that represents the name of the current interface or class.

compare

compare : (A Left, A Right) -> compareResult CompareResult.

Comparison of two terms of the same domain, resturns the value of compareResult domain.

CompareResult = compare("bar", "foo")

constant_name

constant_name : () -> string ConstantName.

This compile time predicate returns the string ConstantName that represents the name of the current constant. It is typically used in exception definitions.

convert

convert : (<type> Type, Term) -> <type> Converted.

Checked term conversion.

Call-template for this function is:

ReturnTerm = convert(returnDomain, InputTerm)

• returnDomain: Specifies a domain to which function convert/2-> converts InputTerm. Here returnDomain must be a name of built-in Visual Prolog domain, an interface domain, a name of such user defined domain that is synonym to one of built-in Visual Prolog domains, a numeric domain, binary and pointer domains. The domain name returnDomain must be specified at compile-time, i.e. it cannot come from a variable.

• InputTerm: Specifies the value that must be converted. InputTerm may be any Prolog term or an expression. If InputTerm is an expression, then it will be evaluated before the conversion.

• ReturnTerm: Returned parameter ReturnTerm will be of returnDomain type.

The convert predicate performs a clean and genuine conversion of the given InputTerm, returning a new term ReturnTerm of the specified new domain returnDomain. If convert cannot perform the required conversion, it rises errors. The similar functionality is provided by the tryConvert/2-> predicate, but tryConvert-> fails and does not produce any runtime errors if it cannot perform the conversion.

Allowed conversions

• Between numerical domains.
• Between interface types.
• Between string and symbol domains.
• From binary to pointer.
• For synonyms of mentioned domains.
• Between reference domains and corresponding non-reference domains.

The contrast to these is uncheckedConvert/2-> predicate, which performs an unchecked conversion between terms from any domains, which have the same bit-size.

The convert/2-> (or tryConvert/2->) predicate accomplishes a checked explicit conversion, when the source and target domains are statically known during the compilation. The result of an explicit conversion can be one of the following:

• ok the successful conversion to the target domain;
• run-time-check the conversion to the target domain with generation of run-time checking for compatibility;
• error the conversion is impossible, error output.

Rules of Checked Explicit Conversions

• Synonyms of domains are converted using the same rules that are applied to the domains themselves.
• Numerical domains can be converted to the numerical domains only.
• Integral constants are the representatives of the anonymous integral domain: [const .. const].
• Real constants are the representatives of the anonymous real domain: digits dig [const .. const], where dig is the number of the digits in mantissa without insignificant zeroes.
• A value of the symbol domain can be converted to the string domain and vice versa.
• A value of binary domain can be converted to the pointer domain.
• The domains that are implicitly introduced for interfaces can be converted only to the interface domains according to the rules specified below.
• All other domains cannot be converted.

Conversions of Numerical Domains

• The range is considered first during such conversion. If the ranges of source and target do not intersect, then an error is produced. If the ranges of source and target only partially intersect, then run-time checking is generated. Also, if one of domains is real and another is an integral one, then the integer range is converted to the real range before the comparison.
• When input term in real and output is integer, then convert/2-> and tryConvert/2-> predicates truncate the input value to the nearest integer value, which is nearer to zero.

Conversions of Interface Types

Predicate convert/2-> allow to convert any object to any interface type. The actual correctness of such conversion is checked at runtime. When object is created, its type is internally stored, therefore when the object is passed as argument it still remember about its original type. This original type is used for checking allowed conversions. The example:

interface x
      supports a, b
end interface x

If object is created by class, which implements x interface, and then object is passed as parameter of type a to some predicate, then it is allowed to convert the object to b type.

Exceptions:

• Check range error.
• Unsupported interface type.

digitsOf

digitsOf : (<real-domain> Domain) -> unsigned.

Returns precision of the specified floating-point domain.

Call-template for this function is:

Precision = digitsof(domainName)

The input parameter domainName of this compiling-time predicate is a floating-point domain, it should be explicitly specified at compile-time (that is, domainName cannot come from a variable). The predicate returns the number Precision that was determined by the digits attribute in the domain declaration.

The compiler guarantees that values of the domain domainName will have at least Precision number of significant decimal digits.

errorExit

errorExit : (unsigned ErrorNumber) erroneous.

Performs a run-time error with the specified return code ErrorNumber, which can be used in the try-catch-finally.

fact_address

fact_address : (FactType FactVariable) -> pointerTo{FactType} PointerToFactVariable.

The fact_address predicate returns the address (as a pointerTo{FactType}) of a fact variable FactVariable of type FactType.

FactVariable must be a fact variable.

fail

fail : () failure.

The fail predicate forces failure and, hence, always causes backtracking. A clause that fails (with fail or for some other reason) cannot bind output arguments.

free

free : (<variableName> Variable) determ.

Check whether a variable is free.

Call-template for this predicate is:

free(Variable)

The free predicate succeeds if the specified Variable is free and fails if Variable is bound. The free predicate treats the specified Variable as bound if any of it's part are instantiated.

See also bound/1.

fromEllipsis

fromEllipsis : (...) -> any* AnyTermList.

This predicate creates the list of terms of the universal type any from the EllipsisBlock ... (i.e. from the special varying parameters block).

Call-template for this function is:

AnyTermList = fromEllipsis(EllipsisBlock )

See also toEllipsis/1->.

hasDomain

hasDomain is not really a predicate, but more a type declaration/restriction. It has two forms a non-function for declaring/restricting the type of a variable and a function form for declaring/restricting the type of a value.

The non-function form is called with a type as first parmeter and a variable as second parameter.

hasDomain : (<type> Type, Type Variable).

The only effect of the call is that the Variable will be restricted to the type Type.

The variable can be free, bound or of some mixed flow and the binding of the variable will not change in any way.

The function form is called with a type as first argument and a value as second argument, and it returns the same value.

hasDomain : (<type> Type, Type Value) -> Type Value.

The only effect of the call is to ensure that the Value will be restricted to the type Type.

lowerBound

lowerBound : (<numeric-domain> NumericDomain) -> <numeric-domain> LowerBound.

Returns the lower bound of the specified NumericDomain.

Call-template for this function is:

LowerBoundValue = lowerBound(domainName)

The lowerBound is a compiling-time predicate. The lowerBound returns the lower bound value LowerBoundValue of the specified numeric domain domainName. The return value LowerBoundValue belongs to the same domain domainName. The domainName parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, domainName cannot come from a variable). See also upperBound/1->.

It will give a compile time error if the specified domain domainName is not numeric domain.

in

See in/2.

isErroneous

isErroneous : (<fact-variable> FactVariable) determ.

The predicate succeeds if the specified fact variable is erroneous.

Call-template for this predicate is:

isErroneous(factVariableName)

The predicate succeeds if the specified fact variable factVariableName has the erroneous value, otherwise it fails.

See also notErroneous.

maxDigits

maxDigits : (<real-domain> RealDomain) -> unsigned MaxDigits

Retrieves the value of digits (precision) of the basic domain corresponding to the specified floating-point domain RealDomain.

Call-template for this function is:

MaxDigitsNumber = maxdigits(domainName)

The return maximal number of digits MaxDigitsNumber for the domainName parameter, which should be the name of a real domain.

not

See not.

notErroneous

The notErroneous/1-> predicate will succeed with the value of a fact if the fact is not erroneous. The main purpose of the predicate is to get an atomic view of the fact in a multi-threaded application.

Example

facts
    theFact : integer := erroneous.
clauses
    ppp() :-
        if F = notErroneous(theFact) then
            % theFact was not erroneous, its value was F
        end if.

The related code using isErroneous/1 is not threadsafe:

clauses
    ppp() :-
        if not(isErroneous(theFact)) then
            % theFact was not erroneous, but it can be in the next line
            F = theFact              
        end if.

See also isErroneous.

otherwise

See otherwise.

or

See or (;).

orelse

See orelse.

predicate_fullname

predicate_fullname : () -> string PredicateFullName.

This predicate returns the name PredicateFullName of the predicate in which it is invoked. The returned predicate name is qualified with a scope name.

predicate_fullname can only be used inside a clause. Use of predicate_fullname in other places causes a compile time error. See also predicate_name.

predicate_name

predicate_name : () -> string PredicateName.

This predicate returns the name PredicateName of the predicate in which it is invoked.

predicate_name can only be used inside a clause. Use of predicate_name in other places causes a compile time error. See also predicate_fullname

programPoint

programPoint : () -> core::programPoint ProgramPoint.

This predicate returns the name programPoint corresponding to the place where it is invoked.

retract

retract : (<fact-term> FactTerm) nondeterm anyflow.

Successively removes the first matching fact from the facts database. Fails when no more facts match.

Call-template for this predicate is:

retract(FactTemplate)

Here FactTemplate should be a fact term. The retract/1 predicate deletes the first fact that matches the FactTemplate in the appropriated facts database. During backtracking, the rest of the matching facts will be deleted.

Notice that FactTemplate can have any level of instantiation. The FactTemplate is matched with the facts in the facts database, which means that any free variables will be bound in the call to retract/1.

The FactTemplate can contain any anonymous variables. That is, variables with names consisting from the single underscore _ or a variable with a name starting with an underscore _AnyValue if the variable occurs only once in the clause. For example.

retract(person("Hans", _Age)),

will retract the first matched person fact that has "Hans" as the first argument and anything as the second argument.

When retracting a fact, which is declared to be determ, the call to retract/1 will be deterministic.

See also retractall/1 and retractFactDb.

The retract/1 predicate cannot be applied to single facts or fact variables.

Be careful calling retract/1 with free FactTemplate variable if any single fact is declared in the project current scope. If you retract a single fact, then the run-time error is generated. The retract/1 predicate fails when there are no more matches.

retractall

retractall : (<fact-term> FactTerm) .

Remove all matching facts from the facts database.

Call-template for this predicate is:

retractall(FactTemplate)

Here FactTemplate should be a fact term.

The retractall/1 retracts all facts which match the given FactTemplate. It always succeeds, even if no facts were retracted.

Attempting to retract a single fact will cause a compile time error.

It is not possible to obtain any output values from retractall/1. For this reason, the variables in the call must be bound or be a single underscores (anonymous). Notice that FactTemplate can have any level of instantiation, but free variables must be single underscores ("unconditionally anonymous"). In difference to retract/1 "conditionally" anonymous variables with names starting from the underscore (like _AnyValue) cannot be used in retractall/1.

See also retract/1 and retractFactDb/1.

retractFactDb

retractFactDb : (factDB FactDB).

Remove all facts from the named internal facts database FactDB.

Call-template for this predicate is:

retractFactDb(FactDB)

The retractFactDb/1 removes all facts from the named facts database FactDB.

Notice, it is impossible to retract single facts and fact variables, so the predicate leaves such ones as they are.

See also retractall/1 and retract/1.

retractAll/2

Obsolete predicate! Use retractFactDb/1 instead.

sizeBitsOf

sizeBitsOf : (<domain> DomainName) -> unsigned BitSize.

Retrieves the number of bits occupied in memory by an entity of the specified domain DomainName.

Call-template for this function is:

BitSize = sizeBitsOf(DomainName)

This compiling-time predicate receives the domain DomainName as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bits. For the integer domains sizeBitsOf/1-> predicate returns the value that was defined for the size-field in a domain's declaration.

The following is always true for the integral domains:

sizeOfDomain(domain)*8 - 7 <= sizeBitsOf(domain) <= sizeOfDomain(domain)*8

See also sizeOfDomain/1->.

sizeOf

sizeOf : (Type Term) -> integer ByteSize.

Retrieves the number of bytes occupied in memory by the specified term Term.

Call-template for this function is:

ByteSize = sizeOf(Term)

The sizeOf/1-> function receives a term as input parameter and returns value ByteSize that specifies the number of bytes occupied in memory by this term Term.

sizeOfDomain

sizeOfDomain : (<domain> Domain) -> integer ByteSize.

Retrieves the number of bytes occupied in memory by the entity of the specified domain DomainName.

Call-template for this function is:

ByteSize = sizeOfDomain(DomainName)

This compiling-time predicate receives the domain DomainName as input parameter and return the size of memory that is occupied by the entity of the given domain. The result is measured in bytes. The returned value ByteSize belongs to the integer domain. Compare with sizeBitsOf/1->, which returns size of a domain measured in bits.

sourcefile_lineno

sourcefile_lineno : () -> unsigned LineNumber.

Returns the current line number in the source file processed by the compiler.

sourcefile_name

sourcefile_name : () -> string FileName.

Returns the name of the source file processed by the compiler.

sourcefile_timestamp

sourcefile_timestamp : () -> string TimeStamp..

Returns a string that represents the date and time of the currently compiled source file in format YYYY-MM-DD HH:mm:ss. Where:

• YYYY - Year.
• MM - Month.
• DD - Day.
• HH - Hour.
• mm - Minute.
• ss - Second.

succeed

succeed : ().

The predicate succeed/0 will always succeed.

toAny

toAny : (Term) -> any UniversalTypeValue.

Converts the specified Term to the value of universal term type any.

Call-template for this function is:

UniversalTypeValue = toAny(Term)

A term of the any domain can be converted back to its original type using the toTerm predicates (see toTerm).

toBinary

toBinary : (Term) -> binary Serialized.

Converts the specified Term to binary representation.

Call-template for this function is:

Serialized = toBinary(Term)

When a Term (of some domain domainName) is converted into a binary, it can safely be stored in a file or sent over a network to another program. Later the obtained binary value Serialized can be converted back to a Visual Prolog term, using toTerm/1-> function (the domain for the reversed term should be adequate to domainName) for the reverse conversion.

toBoolean

toBoolean : (<deterministic_expression> SubGoal) -> boolean Succeed.

The purpose of this meta-predicate is to convert an expression to the value of boolean domain.

Call-template for this meta-predicate is:

True_or_False = toBoolean(deterministic_expression)

this is equivalent to

True_or_False = if deterministic_expression then true else false end if

The toBoolean/1-> meta-predicate returns boolean value. The result is true if deterministic_call succeeds. The result is false if deterministic_call fails.

toEllipsis

toEllipsis : (any* AnyTermList) -> ....

This predicate creates EllipsisBlock ... (i.e. the special varying parameters block) from the list of terms of the universal type any. Such EllipsisBlock can be later passed to a predicate which expects the varying number of arguments (i.e. is declared with the ellipsis (...)), like write/..., at the position of the ellipsis (...).

Call-template for this function is:

EllipsisBlock = toEllipsis(<any_term_list>), write(EllipsisBlock)

See also fromEllipsis/1->.

toString

toString : (Term) -> string Serialized.

Converts the specified Term to string representation.

Call-template for this function is:

Serialized = toString(Term)

When a Term (of some domain domainName) is converted into a string, it can safely be stored in a file or sent over a network to another program. Later the obtained string value can be converted back to a Visual Prolog term, using toTerm/1-> function (the domain of the return value should be adequate to domainName) for the reverse conversion.

toTerm

toTerm : (string Serialized) -> Term.
toTerm : (binary Serialized) -> Term.
toTerm : (any Serialized) -> Term.
toTerm : (<domain> Type, string Serialized) -> Term.
toTerm : (<domain> Type, binary Serialized) -> Term.
toTerm : (<domain> Type, any Serialized) -> Term.

Converts the string/binary/any representation of the specified term Serialized into representation corresponding to the domain of Term variable of the return value. The domain can be stated explicitly or it can be left to the compiler to determine a suitable domain.

Call-template for this function is:

Term = toTerm(Serialized) % with implicit domain
Term = toTerm(domainName, Serialized) % with explicit domain, domainName

If the domain is not specified the compiler must be able to determine the domain for the returned value Term at compile-time. Notice that binary version of toTerm predicate performs almost byte to byte conversion and only checking general compatibility of Serialized data with the domain required to the return value Term. The programmer is wholly responsible for providing binary data of Serialized that can be correctly converted to the term of the desired domain. The toTerm predicates are counterparts to predicates toBinary/1-> and toString/1->. When a Term (of some domain domainName) is converted into a binary or string representation Serialized (by toBinary/1-> or toString/1-> or toAny/1-> correspondingly), it can safely be stored in a file or sent over a network to another program. Later the corresponding toTerm/1-> function can convert the obtained string/binary value Serialized back to a Visual Prolog term Term. For correctness of the reverse conversion the domain of the clause variable Term should be adequate to the initial domain domainName.

See also tryToTerm.

It gives a compile time error if the compiler cannot determine the return domain.

Exceptions

• Run time errors are generated when the toTerm predicate cannot convert the string or binary into a term of the specified domain.

tryToTerm

tryToTerm : (string Serialized) -> Term.
tryToTerm : (binary Serialized) -> Term.
tryToTerm : (any Serialized) -> Term.
tryToTerm : (<domain> Type, string Serialized) -> Term.
tryToTerm : (<domain> Type, binary Serialized) -> Term.
tryToTerm : (<domain> Type, any Serialized) -> Term.

Converts the string/binary/any representation Serialized into a term Term like toTerm. The only difference between the predicates is that tryToTerm fails if it cannot convert the string or binary or any into a term of the specified domain whereas toTerm raises an exception.

See also toTerm.

tryConvert

tryConvert : (<type> Type, Value) -> <type> Converted determ.

Checks whether the input term Value can be strictly converted into the specified domain Type and returns the converted term Converted.

Call-template for this function is:

ReturnTerm = tryConvert(returnDomain, InputTerm)

Arguments:

• returnDomain: Specifies a domain to which tryConvert/2-> predicate tries to convert the specified InputTerm. Here returnDomain can be any domain accessible in the current scope. The domain name returnDomain must be specified at compile-time, i.e. it cannot come from a variable.
• InputTerm: Specifies the term that must be converted. InputTerm may be any Prolog term or an expression. If InputTerm is an expression, then it will be evaluated before conversion.
• ReturnTerm: Returned term ReturnTerm will be of returnDomain domain.

The conversion rules are the same as of the embedded predicate convert/2->, but tryConvert/2-> fails when convert/2-> generates conversion errors.

This predicate succeeds if the corresponding conversion succeeds. Otherwise it fails. The tryConvert/2-> predicate tries to perform a clean and genuine conversion of the given InputTerm into a value of the specified domain returnDomain. The tryConvert/2-> predicate will fail if the required conversion cannot be performed. When tryConvert/2-> predicate succeeds, it returns the term ReturnTerm converted to the specified domain returnDomain.

For allowed conversions and rules of checked explicit conversions see convert/2-> predicate.

See also uncheckedConvert/2->.

typeDescriptorOf

typeDescriptorOf : (<type> Type) -> typeDescriptor TypeDescriptor.
typeDescriptorOf : (Type Value) -> typeDescriptor TypeDescriptor.

Reflection predicate that returns the typeDescriptor of a type or a value.

A typeDescriptor is the reflection descriptor of an uninstantiated type/domain.

typeLibraryOf

typeLibraryOf : (<type> Type) -> typeLibrary TypeLibrary.
typeLibraryOf : (Type Value) -> typeLibrary TypeLibrary.

Reflection predicate that returns the typeLibrary of a type or a value.

A typeLibrary is the reflection descriptor of an instantiated type/domain.

uncheckedConvert

uncheckedConvert : (<type> Type, Value) -> <type> Converted.

Unchecked conversion of a value to another type.

Call-template for this function is:

ReturnTerm = uncheckedConvert(returnDomain, InputTerm)

Arguments:

• returnDomain: Specifies a domain to which uncheckedConvert predicate unsafely converts the specified InputTerm. Here returnDomain can be any domain accessible in the current scope, the ReturnTerm should has the same bit-size as the InputTerm. The domain name returnDomain must be specified at compile-time, i.e. it cannot come from a variable.
• InputTerm: Specifies the value that must be converted. InputTerm may be any Prolog term or an expression. If InputTerm is an expression, then it will be evaluated before conversion.
• ReturnTerm: Returned parameter ReturnTerm will be of returnDomain type.

uncheckedConvert evaluates InputTerm, change the type to returnDomain without any modification of the memory pattern and unifies with ReturnTerm. The uncheckedConvert predicate performs no runtime checks. It makes only compile time checking of bit-size equality of the converted domains. So almost any term may be quite recklessly converted to any other term. So quite disastrous results may occur if you try to use variables incorrectly converted by uncheckedConvert. Be extremely careful implementing uncheckedConvert; we strongly recommend you always, when it is possible, using of convert/2-> and tryConvert/2->. But notice that, when an object is returned by COM system it is necessary to convert it by uncheckedConvert, as Prolog program does not have information about its actual type.

upperBound

upperBound : (<numeric-domain> NumericDomain) -> <numeric-domain> UpperBound.

Returns the upper bound value of the specified numeric domain.

Call-template for this function is:

UpperBound = upperBound(domainName)

The upperBound is a compiling-time predicate. The upperBound returns the upper bound value of the specified numeric domain domainName. The return value UpperBound belongs to the same domain domainName. The domainName parameter should be the name of any numerical domain; this domain name should be explicitly specified at compile-time (that is, domainName cannot come from a variable).

See also lowerBound/1->.

Will cause a compile time error if the specified domain domainName is not numeric domain.