Clingo C API
C API for clingo providing high level functions to control grounding and solving.
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.

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

Enumerations

enum  clingo_symbol_type_e {
  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

CLINGO_VISIBILITY_DEFAULT bool clingo_add_string (char const *string, char const **result)
 Internalize a string. More...
 
CLINGO_VISIBILITY_DEFAULT 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

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

Symbol Construction Functions

CLINGO_VISIBILITY_DEFAULT void clingo_symbol_create_number (int number, clingo_symbol_t *symbol)
 Construct a symbol representing a number. More...
 
CLINGO_VISIBILITY_DEFAULT void clingo_symbol_create_supremum (clingo_symbol_t *symbol)
 Construct a symbol representing #sup. More...
 
CLINGO_VISIBILITY_DEFAULT void clingo_symbol_create_infimum (clingo_symbol_t *symbol)
 Construct a symbol representing #inf. More...
 
CLINGO_VISIBILITY_DEFAULT bool clingo_symbol_create_string (char const *string, clingo_symbol_t *symbol)
 Construct a symbol representing a string. More...
 
CLINGO_VISIBILITY_DEFAULT bool clingo_symbol_create_id (char const *name, bool positive, clingo_symbol_t *symbol)
 Construct a symbol representing an id. More...
 
CLINGO_VISIBILITY_DEFAULT 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

CLINGO_VISIBILITY_DEFAULT bool clingo_symbol_number (clingo_symbol_t symbol, int *number)
 Get the number of a symbol. More...
 
CLINGO_VISIBILITY_DEFAULT bool clingo_symbol_name (clingo_symbol_t symbol, char const **name)
 Get the name of a symbol. More...
 
CLINGO_VISIBILITY_DEFAULT bool clingo_symbol_string (clingo_symbol_t symbol, char const **string)
 Get the string of a symbol. More...
 
CLINGO_VISIBILITY_DEFAULT bool clingo_symbol_is_positive (clingo_symbol_t symbol, bool *positive)
 Check if a function is positive (does not have a sign). More...
 
CLINGO_VISIBILITY_DEFAULT bool clingo_symbol_is_negative (clingo_symbol_t symbol, bool *negative)
 Check if a function is negative (has a sign). More...
 
CLINGO_VISIBILITY_DEFAULT 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_VISIBILITY_DEFAULT clingo_symbol_type_t clingo_symbol_type (clingo_symbol_t symbol)
 Get the type of a symbol. More...
 
CLINGO_VISIBILITY_DEFAULT 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...
 
CLINGO_VISIBILITY_DEFAULT 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

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

Typedef Documentation

◆ clingo_signature_t

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

◆ clingo_symbol_t

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

◆ clingo_symbol_type_e

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

◆ clingo_add_string()

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

Parameters
[in]stringthe string to internalize
[out]resultthe internalized string
Returns
whether the call was successful; might set one of the following error codes:

◆ clingo_parse_term()

CLINGO_VISIBILITY_DEFAULT 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:

◆ clingo_signature_arity()

CLINGO_VISIBILITY_DEFAULT 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

◆ clingo_signature_create()

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

◆ clingo_signature_hash()

CLINGO_VISIBILITY_DEFAULT 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

◆ clingo_signature_is_equal_to()

CLINGO_VISIBILITY_DEFAULT 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

◆ clingo_signature_is_less_than()

CLINGO_VISIBILITY_DEFAULT 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

◆ clingo_signature_is_negative()

CLINGO_VISIBILITY_DEFAULT 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

◆ clingo_signature_is_positive()

CLINGO_VISIBILITY_DEFAULT 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

◆ clingo_signature_name()

CLINGO_VISIBILITY_DEFAULT char const* clingo_signature_name ( clingo_signature_t  signature)

Get the name of a signature.

Note
The string is internalized and valid for the duration of the process.
Parameters
[in]signaturethe target signature
Returns
the name of the signature

◆ clingo_symbol_arguments()

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

◆ clingo_symbol_create_function()

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

◆ clingo_symbol_create_id()

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

◆ clingo_symbol_create_infimum()

CLINGO_VISIBILITY_DEFAULT void clingo_symbol_create_infimum ( clingo_symbol_t symbol)

Construct a symbol representing #inf.

Parameters
[out]symbolthe resulting symbol

◆ clingo_symbol_create_number()

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

◆ clingo_symbol_create_string()

CLINGO_VISIBILITY_DEFAULT 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:

◆ clingo_symbol_create_supremum()

CLINGO_VISIBILITY_DEFAULT void clingo_symbol_create_supremum ( clingo_symbol_t symbol)

Construct a symbol representing #sup.

Parameters
[out]symbolthe resulting symbol

◆ clingo_symbol_hash()

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

◆ clingo_symbol_is_equal_to()

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

◆ clingo_symbol_is_less_than()

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

◆ clingo_symbol_is_negative()

CLINGO_VISIBILITY_DEFAULT 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:

◆ clingo_symbol_is_positive()

CLINGO_VISIBILITY_DEFAULT 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:

◆ clingo_symbol_name()

CLINGO_VISIBILITY_DEFAULT bool clingo_symbol_name ( clingo_symbol_t  symbol,
char const **  name 
)

Get the name of a symbol.

Note
The string is internalized and valid for the duration of the process.
Parameters
[in]symbolthe target symbol
[out]namethe resulting name
Returns
whether the call was successful; might set one of the following error codes:

◆ clingo_symbol_number()

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

◆ clingo_symbol_string()

CLINGO_VISIBILITY_DEFAULT bool clingo_symbol_string ( clingo_symbol_t  symbol,
char const **  string 
)

Get the string of a symbol.

Note
The string is internalized and valid for the duration of the process.
Parameters
[in]symbolthe target symbol
[out]stringthe resulting string
Returns
whether the call was successful; might set one of the following error codes:

◆ clingo_symbol_to_string()

CLINGO_VISIBILITY_DEFAULT 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, statistics.c, symbol.c, symbolic-atoms.c, and theory-atoms.c.

◆ clingo_symbol_to_string_size()

CLINGO_VISIBILITY_DEFAULT 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, statistics.c, symbol.c, symbolic-atoms.c, and theory-atoms.c.

◆ clingo_symbol_type()

CLINGO_VISIBILITY_DEFAULT clingo_symbol_type_t clingo_symbol_type ( clingo_symbol_t  symbol)

Get the type of a symbol.

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