Language Reference/Built-in entities

From wiki.visual-prolog.com
Language Reference

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 a compiler.
compiler_version A compiler version.
maxFloatDigits Defines the maximal value of "digits", which is supported by the compiler.
null The default NULL pointer.
nullHandle A special constant of a handle type with the zero value.
invalidHandle A special constant of a handle type with the invalid (-1) value.
platform_bits Defines the digital capacity of compilation platform.
platform_name Defines the target platform name.

compilation_date

Compilation date. Here YYYY means the number of a year, MM means a month number, and DD means a day number. 

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

compilation_time

Compilation time. Here HH means hours, MM means minutes, and SS means seconds. 

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

compiler_buildDate

Build date of the compiler. 

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

compiler_version

A compiler version. This value depends upon the compiler version. 

compiler_version = 6003.

maxFloatDigits

Defines the maximal value of "digits", which is supported by the compiler. 

maxFloatDigits = 16.

null

A constant of type pointer with the value 0. 

null : pointer = uncheckedConvert(pointer, 0).

nullHandle

A constant of type handle with the value 0. 

nullHandle : handle = uncheckedConvert(handle, 0).

invalidHandle

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

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

platform_bits

Defines the digital capacity of compilation platform. 

platform_bits = 32.
or
platform_bits = 64.

platform_name

Defines the target platform name. 

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

Domains

any Universal term type.
char Wide (two-bytes) character.
string Wide zero-terminated sequence of wide characters.
string8 Zero-terminated sequence of ASCII (one-byte) characters.
symbol Wide zero-terminated sequence of wide characters.
binary Sequence of bytes.
binaryNonAtomic Sequence of bytes.
integer 32 bit signed integer.
integer64 64 bit signed integer.
integerNative Signed integer with platform size (32 bit in a 32 bit program; 64 bit in a 64 bit program).
unsigned 32 bit unsigned integer.
unsigned64 64 bit unsigned integer.
unsignedNative Unsigned integer with platform size (32 bit in a 32 bit program; 64 bit in a 64 bit program).
real Float-pointing number.
real32 Float-pointing number.
pointer pointer to a memory address.
handle a handle (e.g. native file and windows handles).
boolean Boolean values.
factDB Descriptors of named internal databases.
compareResult Values of comparison result.

any

Universal term type. 

any

The values of this domain are any terms. Such a value contains the reference to the term type library and a term itself.

char

Wide character. 

char

The values of this domain are UNICODE characters. Implemented as 2 unsigned bytes.

Only assignment and comparison (in the lexicographical sense) operations are applied to the values of this domain. 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 correspond to 4 hexadecimal digits. Also, the backslash symbol and the single quote can be represented by an escape-sequence only.

compareResult

The result of a comparison. For instance, the built-in procedure compare/2-> has "compareResult" as the domain of its result. 

domains
   compareResult = less; equal; greater.

string

Utf-16 strings. 

string

A string represented as a pointer to a zero terminated sequence of characters in utf-16 encoding. Values in the sequence are 16 bits, but certain rare characters (code points) are encoded using two such values. Strings are immutable.

In source code a string literal can be specified as a set of sequences of characters surrounded by the double quotes. 

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

A string literal consists of one or more StringLiteralPart's, which are concatenated. StringLiteralPart's starting with @ does not use escape sequences, whereas StringLiteralPart's without @ uses the following escape sequences:

  • \\ representing \
  • \t representing Tab-character
  • \n representing newline-character
  • \r representing carriage return
  • \' representing single quote
  • \" representing double quote
  • \u followed by exactly four HexadecimalDigit's representing the Unicode character corresponding to the digits.

The double quotes in the string can be represented by the escape-sequence only (the single quote can be represented both with an escape-sequence and a graphical symbol).

string8

A built-in domain who's elements are sequences of (one-byte) ASCII-characters. It is implemented as a pointer to the zero terminated array of ASCII characters. Only assignment and comparison for equality (in the lexicographical sense) operations are applied to the values of this domain. Currently no literals are allowed for this domain.

symbol

Utf-16 strings with same representation as string, but they are also stored in a global symbol table. 

symbol

A symbol is stored in a global symbol table, and that storage guarenties that the pointer value of symbols will be the same for the same symbol. Once a symbol is put into the symbol table it is never removed again, so symbols are never reclaimed. Their storage will live untill the program terminates. So the symbol data type should not be used for large documents, etc.

The symbol domain is a subtype of the string domain, so a symbol can be used everywhere instead of a string. The opposite is not the case because a string will have to be found or inserted in the global symbol table to become a symbol. So to create a symbol from a string you will have to convert the string to the symbol domain (or a subtype of the symbol domain).

The equality operation is very efficient for symbols since their pointer value will be the same if the symbol is the same. I.e. there is no need to compare the actual characters to determine equality.

Other comparison operations (less than, case insensitive comparison, etc) are the same as for string in fact all other operations on symbol is simply carried out by the corresponding string operations.

binary

Sequence of bytes. 

binary

Values of this domain are used for holding binary data. A binary value is implemented as a pointer to the sequence of bytes that represents the contents of a binary term.

The length of a binary term is situated in the 4 bytes immediately preceding this sequence of bytes. The 4 bytes contains: 

TotalNumberOfBytesOccupiedByBinary = ByteLen + 4

where ByteLen - is the length of the binary term and 4 is number of bytes occupied by size field.

Only assignment and comparison operations are applied to values of binary domain.

Two binary terms are compared in the following way:

  • If they are of different sizes, the bigger is considered larger.
  • Otherwise, they are compared byte by byte, as unsigned values. Comparison stops when two differing bytes are found and the result of their comparison is the result of the comparison of the binary terms. Two binary terms are equal if they have the same sizes and all bytes are equal.

The text syntax for binary images is determined by the Binary rules: 

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

Each expression should be calculate on compiling time and its value should be in the range from 0 to 255.

binaryNonAtomic

Sequence of bytes. 

binaryNonAtomic

Same as binary, but can contain pointers because it is scanned by the garbage collector.

integer

32 bit signed integer. 

integer

Values of this domain occupy 4 bytes. Arithmetic operations (+, -, /, *, ^), comparison, assignment, div/2->, mod/2->, quot/2->, and rem/2-> operations are applied to values of this domain.

The permitted number range is from -2147483648 to 2147483647.

The syntax for the integer literal is determined by the Integer rule: 

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 integers. 

integer64

Values of this domain occupy 8 bytes.

The permitted number range is from -2^63 = -9223372036854775808 to 2^63-1 = 9223372036854775807.

The syntax for integer64 literal is the same as Integer rule.

The set of operations for integer64 is similar to the one for Integer.

integerNative

Signed integer number with platform size (32 bit in a 32 bit program; 64 bit in a 64 bit program). 

integerNative

unsigned

32 bit unsigned integer. 

unsigned

Values of this domain occupy 4 bytes. Arithmetic operations (+, -, /, *, ^), comparison, assignment, div/2->, mod/2->, rem/2->, and quot/2-> operations are applied to values of this domain.

The permitted number range is from 0 to 4294967295.

The syntax for unsigned number images is the same as for integer numbers. The usage of minus sign (UnaryMinus) is not allowed for an image of an unsigned number.

unsigned64

64 bit unsigned integer. 

unsigned64

Values of this domain occupy 8 bytes.

The permitted number range is from 0 to 2^64-1 = 18,446,744,073,709,551,615.

The syntax for unsigned64 number images is the same as for integer64 numbers. The usage of minus sign (UnaryMinus) is not allowed for an image of an unsigned64 number.

The set of operations for unsigned64 is similar to the one for Unsigned.

unsignedNative

Unsigned integer number with platform size (32 bit in a 32 bit program; 64 bit in a 64 bit program). 

unsignedNative

real

Float-pointing number. 

real

Values of this domain occupy 8 bytes. This numerical real domain is introduced for the user's convenience only. All arithmetic, comparison, and assignment operations are applied to values of real domain.

The permitted number range is -1.7e+308 to 1.7e+308. Values from integral domains are automatically converted to real numbers when necessary.

The syntax for the floating-point number literal is determined by the Real rule: 

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

Float-pointing number. 

real32

Values of this domain occupy 4 bytes. This numerical real32 domain is introduced for the user's convenience only. All arithmetic, comparison, and assignment operations can be applied to values of real32 domain.

The permitted number range is -3.4e+38 to 3.4e+38.

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

pointer

A pointer to a memory address. 

pointer

A pointer directly corresponds to memory addresses. Only the equality operation can be applied to the values of this domain. There is a built-in null constant for this type

pointerTo

pointerTo{Type} represents a pointer to a value of type Type. It's definition is like this (but it is built-in): 

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

handle

A handle is used for Windows API function call. Values of this domain has the same size as a pointer (i.e. 4 on 32bit platfor and 8 on 64bit platform).

There are no operations for this domain and cannot be converted (except uncheckedConvert) to/from other domains.

There is a built-in nullHandle and invalidHandle constant for this type

boolean

Boolean values. 

boolean

This domain is introduced for the user convenience only. It is treated as usual compound domain with the following definition: 

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 the constants of this domain. The compiler automatically builds the corresponding compound terms from such constants whenever it's in need. At the runtime the 1st field of this structure contains the address of the corresponding domain descriptor and the 2nd field contains either zero (for class facts sections) or pointer to an object (i.e. 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.

Retrieved from "https://wiki.visual-prolog.com/index.php?title=Language_Reference/Built-in_entities&oldid=2902"