Clingo C API
C API for clingo providing high level functions to control grounding and solving.
Classes | Typedefs | Enumerations | Functions
Symbols

Detailed Description

Working with (evaluated) ground terms and related functions.

Note
All functions in this module are thread-safe.

For an example, see symbol.c.

Classes

struct  clingo_symbolic_literal
 Represents a symbolic literal. More...
 

Typedefs

typedef uint64_t clingo_signature_t
 Represents a predicate signature. More...
 
typedef int clingo_symbol_type_t
 Corresponding type to clingo_symbol_type.
 
typedef uint64_t clingo_symbol_t
 Represents a symbol. More...
 
typedef struct clingo_symbolic_literal clingo_symbolic_literal_t
 Represents a symbolic literal.
 

Enumerations

enum  clingo_symbol_type {
  clingo_symbol_type_infimum = 0, clingo_symbol_type_number = 1, clingo_symbol_type_string = 4, clingo_symbol_type_function = 5,
  clingo_symbol_type_supremum = 7
}
 Enumeration of available symbol types. More...
 

Functions

bool clingo_add_string (char const *string, char const **result)
 Internalize a string. More...
 
bool clingo_parse_term (char const *string, clingo_logger_t *logger, void *logger_data, unsigned message_limit, clingo_symbol_t *symbol)
 Parse a term in string form. More...
 

Signature Functions

bool clingo_signature_create (char const *name, uint32_t arity, bool positive, clingo_signature_t *signature)
 Create a new signature. More...
 
char const * clingo_signature_name (clingo_signature_t signature)
 Get the name of a signature. More...
 
uint32_t clingo_signature_arity (clingo_signature_t signature)
 Get the arity of a signature. More...
 
bool clingo_signature_is_positive (clingo_signature_t signature)
 Whether the signature is positive (is not classically negated). More...
 
bool clingo_signature_is_negative (clingo_signature_t signature)
 Whether the signature is negative (is classically negated). More...
 
bool clingo_signature_is_equal_to (clingo_signature_t a, clingo_signature_t b)
 Check if two signatures are equal. More...
 
bool clingo_signature_is_less_than (clingo_signature_t a, clingo_signature_t b)
 Check if a signature is less than another signature. More...
 
size_t clingo_signature_hash (clingo_signature_t signature)
 Calculate a hash code of a signature. More...
 

Symbol Construction Functions

void clingo_symbol_create_number (int number, clingo_symbol_t *symbol)
 Construct a symbol representing a number. More...
 
void clingo_symbol_create_supremum (clingo_symbol_t *symbol)
 Construct a symbol representing #sup. More...
 
void clingo_symbol_create_infimum (clingo_symbol_t *symbol)
 Construct a symbol representing #inf. More...
 
bool clingo_symbol_create_string (char const *string, clingo_symbol_t *symbol)
 Construct a symbol representing a string. More...
 
bool clingo_symbol_create_id (char const *name, bool positive, clingo_symbol_t *symbol)
 Construct a symbol representing an id. More...
 
bool clingo_symbol_create_function (char const *name, clingo_symbol_t const *arguments, size_t arguments_size, bool positive, clingo_symbol_t *symbol)
 Construct a symbol representing a function or tuple. More...
 

Symbol Inspection Functions

bool clingo_symbol_number (clingo_symbol_t symbol, int *number)
 Get the number of a symbol. More...
 
bool clingo_symbol_name (clingo_symbol_t symbol, char const **name)
 Get the name of a symbol. More...
 
bool clingo_symbol_string (clingo_symbol_t symbol, char const **string)
 Get the string of a symbol. More...
 
bool clingo_symbol_is_positive (clingo_symbol_t symbol, bool *positive)
 Check if a function is positive (does not have a sign). More...
 
bool clingo_symbol_is_negative (clingo_symbol_t symbol, bool *negative)
 Check if a function is negative (has a sign). More...
 
bool clingo_symbol_arguments (clingo_symbol_t symbol, clingo_symbol_t const **arguments, size_t *arguments_size)
 Get the arguments of a symbol. More...
 
clingo_symbol_type_t clingo_symbol_type (clingo_symbol_t symbol)
 Get the type of a symbol. More...
 
bool clingo_symbol_to_string_size (clingo_symbol_t symbol, size_t *size)
 Get the size of the string representation of a symbol (including the terminating 0). More...
 
bool clingo_symbol_to_string (clingo_symbol_t symbol, char *string, size_t size)
 Get the string representation of a symbol. More...
 

Symbol Comparison Functions

bool clingo_symbol_is_equal_to (clingo_symbol_t a, clingo_symbol_t b)
 Check if two symbols are equal. More...
 
bool clingo_symbol_is_less_than (clingo_symbol_t a, clingo_symbol_t b)
 Check if a symbol is less than another symbol. More...
 
size_t clingo_symbol_hash (clingo_symbol_t symbol)
 Calculate a hash code of a symbol. More...
 

Typedef Documentation

typedef uint64_t clingo_signature_t

Represents a predicate signature.

Signatures have a name and an arity, and can be positive or negative (to represent classical negation).

typedef uint64_t clingo_symbol_t

Represents a symbol.

This includes numbers, strings, functions (including constants when arguments are empty and tuples when the name is empty), #inf and #sup.

Enumeration Type Documentation

Enumeration of available symbol types.

Enumerator
clingo_symbol_type_infimum 

the #inf symbol

clingo_symbol_type_number 

a numeric symbol, e.g., 1

clingo_symbol_type_string 

a string symbol, e.g., "a"

clingo_symbol_type_function 

a numeric symbol, e.g., c, (1, "a"), or f(1,"a")

clingo_symbol_type_supremum 

the #sup symbol

Function Documentation

bool clingo_add_string ( char const *  string,
char const **  result 
)

Internalize a string.

This functions takes a string as input and returns an equal unique string that is (at the moment) not freed until the program is closed. All strings returned from clingo API functions are internalized and must not be freed.

Parameters
[in]stringthe string to internalize
[out]resultthe internalized string
Returns
whether the call was successful; might set one of the following error codes:
bool clingo_parse_term ( char const *  string,
clingo_logger_t logger,
void *  logger_data,
unsigned  message_limit,
clingo_symbol_t symbol 
)

Parse a term in string form.

The result of this function is a symbol. The input term can contain unevaluated functions, which are evaluated during parsing.

Parameters
[in]stringthe string to parse
[in]loggeroptional logger to report warnings during parsing
[in]logger_datauser data for the logger
[in]message_limitmaximum number of times to call the logger
[out]symbolthe resulting symbol
Returns
whether the call was successful; might set one of the following error codes:
uint32_t clingo_signature_arity ( clingo_signature_t  signature)

Get the arity of a signature.

Parameters
[in]signaturethe target signature
Returns
the arity of the signature
bool clingo_signature_create ( char const *  name,
uint32_t  arity,
bool  positive,
clingo_signature_t signature 
)

Create a new signature.

Parameters
[in]namename of the signature
[in]arityarity of the signature
[in]positivefalse if the signature has a classical negation sign
[out]signaturethe resulting signature
Returns
whether the call was successful; might set one of the following error codes:
Examples:
propagator.c.
size_t clingo_signature_hash ( clingo_signature_t  signature)

Calculate a hash code of a signature.

Parameters
[in]signaturethe target signature
Returns
the hash code of the signature
bool clingo_signature_is_equal_to ( clingo_signature_t  a,
clingo_signature_t  b 
)

Check if two signatures are equal.

Parameters
[in]afirst signature
[in]bsecond signature
Returns
whether a == b
bool clingo_signature_is_less_than ( clingo_signature_t  a,
clingo_signature_t  b 
)

Check if a signature is less than another signature.

Signatures are compared first by sign (unsigned < signed), then by arity, then by name.

Parameters
[in]afirst signature
[in]bsecond signature
Returns
whether a < b
bool clingo_signature_is_negative ( clingo_signature_t  signature)

Whether the signature is negative (is classically negated).

Parameters
[in]signaturethe target signature
Returns
whether the signature has a sign
bool clingo_signature_is_positive ( clingo_signature_t  signature)

Whether the signature is positive (is not classically negated).

Parameters
[in]signaturethe target signature
Returns
whether the signature has no sign
char const* clingo_signature_name ( clingo_signature_t  signature)

Get the name of a signature.

Parameters
[in]signaturethe target signature
Returns
the name of the signature
bool clingo_symbol_arguments ( clingo_symbol_t  symbol,
clingo_symbol_t const **  arguments,
size_t *  arguments_size 
)

Get the arguments of a symbol.

Parameters
[in]symbolthe target symbol
[out]argumentsthe resulting arguments
[out]arguments_sizethe number of arguments
Returns
whether the call was successful; might set one of the following error codes:
Examples:
propagator.c, and symbol.c.
bool clingo_symbol_create_function ( char const *  name,
clingo_symbol_t const *  arguments,
size_t  arguments_size,
bool  positive,
clingo_symbol_t symbol 
)

Construct a symbol representing a function or tuple.

Note
To create tuples, the empty string has to be used as name.
Parameters
[in]namethe name of the function
[in]argumentsthe arguments of the function
[in]arguments_sizethe number of arguments
[in]positivewhether the symbol has a classical negation sign
[out]symbolthe resulting symbol
Returns
whether the call was successful; might set one of the following error codes:
Examples:
symbol.c.
bool clingo_symbol_create_id ( char const *  name,
bool  positive,
clingo_symbol_t symbol 
)

Construct a symbol representing an id.

Note
This is just a shortcut for clingo_symbol_create_function() with empty arguments.
Parameters
[in]namethe name
[in]positivewhether the symbol has a classical negation sign
[out]symbolthe resulting symbol
Returns
whether the call was successful; might set one of the following error codes:
Examples:
ast.c, backend.c, and symbol.c.
void clingo_symbol_create_infimum ( clingo_symbol_t symbol)

Construct a symbol representing #inf.

Parameters
[out]symbolthe resulting symbol
void clingo_symbol_create_number ( int  number,
clingo_symbol_t symbol 
)

Construct a symbol representing a number.

Parameters
[in]numberthe number
[out]symbolthe resulting symbol
Examples:
propagator.c, and symbol.c.
bool clingo_symbol_create_string ( char const *  string,
clingo_symbol_t symbol 
)

Construct a symbol representing a string.

Parameters
[in]stringthe string
[out]symbolthe resulting symbol
Returns
whether the call was successful; might set one of the following error codes:
void clingo_symbol_create_supremum ( clingo_symbol_t symbol)

Construct a symbol representing #sup.

Parameters
[out]symbolthe resulting symbol
size_t clingo_symbol_hash ( clingo_symbol_t  symbol)

Calculate a hash code of a symbol.

Parameters
[in]symbolthe target symbol
Returns
the hash code of the symbol
Examples:
symbol.c.
bool clingo_symbol_is_equal_to ( clingo_symbol_t  a,
clingo_symbol_t  b 
)

Check if two symbols are equal.

Parameters
[in]afirst symbol
[in]bsecond symbol
Returns
whether a == b
Examples:
symbol.c.
bool clingo_symbol_is_less_than ( clingo_symbol_t  a,
clingo_symbol_t  b 
)

Check if a symbol is less than another symbol.

Symbols are first compared by type. If the types are equal, the values are compared (where strings are compared using strcmp). Functions are first compared by signature and then lexicographically by arguments.

Parameters
[in]afirst symbol
[in]bsecond symbol
Returns
whether a < b
Examples:
symbol.c.
bool clingo_symbol_is_negative ( clingo_symbol_t  symbol,
bool *  negative 
)

Check if a function is negative (has a sign).

Parameters
[in]symbolthe target symbol
[out]negativethe result
Returns
whether the call was successful; might set one of the following error codes:
bool clingo_symbol_is_positive ( clingo_symbol_t  symbol,
bool *  positive 
)

Check if a function is positive (does not have a sign).

Parameters
[in]symbolthe target symbol
[out]positivethe result
Returns
whether the call was successful; might set one of the following error codes:
bool clingo_symbol_name ( clingo_symbol_t  symbol,
char const **  name 
)

Get the name of a symbol.

Parameters
[in]symbolthe target symbol
[out]namethe resulting name
Returns
whether the call was successful; might set one of the following error codes:
bool clingo_symbol_number ( clingo_symbol_t  symbol,
int *  number 
)

Get the number of a symbol.

Parameters
[in]symbolthe target symbol
[out]numberthe resulting number
Returns
whether the call was successful; might set one of the following error codes:
Examples:
propagator.c.
bool clingo_symbol_string ( clingo_symbol_t  symbol,
char const **  string 
)

Get the string of a symbol.

Parameters
[in]symbolthe target symbol
[out]stringthe resulting string
Returns
whether the call was successful; might set one of the following error codes:
bool clingo_symbol_to_string ( clingo_symbol_t  symbol,
char *  string,
size_t  size 
)

Get the string representation of a symbol.

Parameters
[in]symbolthe target symbol
[out]stringthe resulting string
[in]sizethe size of the string
Returns
whether the call was successful; might set one of the following error codes:
See also
clingo_symbol_to_string_size()
Examples:
ast.c, backend.c, configuration.c, control.c, model.c, propagator.c, solve-async.c, solve-iteratively.c, statistics.c, symbol.c, symbolic-atoms.c, and theory-atoms.c.
bool clingo_symbol_to_string_size ( clingo_symbol_t  symbol,
size_t *  size 
)

Get the size of the string representation of a symbol (including the terminating 0).

Parameters
[in]symbolthe target symbol
[out]sizethe resulting size
Returns
whether the call was successful; might set one of the following error codes:
Examples:
ast.c, backend.c, configuration.c, control.c, model.c, propagator.c, solve-async.c, solve-iteratively.c, statistics.c, symbol.c, symbolic-atoms.c, and theory-atoms.c.

Get the type of a symbol.

Parameters
[in]symbolthe target symbol
Returns
the type of the symbol