! An instance of this struct has to be registered with a solver to observe ground directives as they are passed to the solver.
!
! @note This interface is closely modeled after the aspif format.
! For more information please refer to the specification of the aspif format.
!
! Not all callbacks have to be implemented and can be set to NULL if not needed.
! If one of the callbacks in the struct fails, grounding is stopped.
! If a non-recoverable clingo API call fails, a callback must return false.
! Otherwise ::clingo_error_unknown should be set and false returned.
!
! @see clingo_control_register_observer()
! Represents a source code location marking its beginnig and end.
!
! @note Not all locations refer to physical files.
! By convention, such locations use a name put in angular brackets as filename.
! The string members of a location object are internalized and valid for the duration of the process.
! Struct used to specify the program parts that have to be grounded.
!
! Programs may be structured into parts, which can be grounded independently with ::clingo_control_ground.
! Program parts are mainly interesting for incremental grounding and multi-shot solving.
! For single-shot solving, program parts are not needed.
!
! @note Parts of a logic program without an explicit #program
! specification are by default put into a program called base without
! arguments.
!
! @see clingo_control_ground()
! An instance of this struct has to be registered with a solver to implement a custom propagator.
!
! Not all callbacks have to be implemented and can be set to NULL if not needed.
! @see Propagator
! A map from AST types to their constructors.
!
! @note The idea of this variable is to provide enough information to auto-generate code for language bindings.
! 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.
!
! @param[in] string the string to internalize
! @param[out] result the internalized string
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! The (positive) literal at the given offset in the assignment.
!
! @param[in] assignment the target
! @param[in] offset the offset of the literal
! @param[out] literal the literal
! @return whether the call was successful
! Determine the decision literal given a decision level.
!
! @param[in] assignment the target assignment
! @param[in] level the level
! @param[out] literal the resulting literal
! @return whether the call was successful
! Check if the given literal is part of a (partial) assignment.
!
! @param[in] assignment the target assignment
! @param[in] literal the literal
! @return whether the literal is valid
! Check if a literal has a fixed truth value.
!
! @param[in] assignment the target assignment
! @param[in] literal the literal
! @param[out] is_false whether the literal is false
! @return whether the call was successful
! @see clingo_assignment_truth_value()
! Check if a literal has a fixed truth value.
!
! @param[in] assignment the target assignment
! @param[in] literal the literal
! @param[out] is_fixed whether the literal is fixed
! @return whether the call was successful
! Check if a literal is true.
!
! @param[in] assignment the target assignment
! @param[in] literal the literal
! @param[out] is_true whether the literal is true
! @return whether the call was successful
! @see clingo_assignment_truth_value()
! Determine the decision level of a given literal.
!
! @param[in] assignment the target assignment
! @param[in] literal the literal
! @param[out] level the resulting level
! @return whether the call was successful
! Get the current root level.
!
! Decisions levels smaller or equal to the root level are not backtracked during solving.
!
! @param[in] assignment the target assignment
! @return the decision level
! Returns the literal at the given position in the trail.
!
! @param[in] assignment the target
! @param[in] offset the offset of the literal
! @param[out] literal the literal
! @return whether the call was successful
! Returns the offset of the decision literal with the given decision level in
! the trail.
!
! @note Literals in the trail are ordered by decision levels, where the first
! literal with a larger level than the previous literals is a decision; the
! following literals with same level are implied by this decision literal.
! Each decision level up to and including the current decision level has a
! valid offset in the trail.
!
! @param[in] assignment the target
! @param[in] level the decision level
! @param[out] offset the offset of the decision literal
! @return whether the call was successful
! Returns the offset following the last literal with the given decision level.
!
! @note This function is the counter part to clingo_assignment_trail_begin().
!
! @param[in] assignment the target
! @param[in] level the decision level
! @param[out] offset the offset
! @return whether the call was successful
! Returns the number of literals in the trail, i.e., the number of assigned literals.
!
! @param[in] assignment the target
! @param[out] size the number of literals in the trail
! @return whether the call was successful
! Determine the truth value of a given literal.
!
! @param[in] assignment the target assignment
! @param[in] literal the literal
! @param[out] value the resulting truth value
! @return whether the call was successful
! Increment the reference count of an AST node.
!
! @note All functions that return AST nodes already increment the reference count.
! The reference count of callback arguments is not incremented.
!
! @param[in] ast the target AST
! Remove an element from an attribute of type “clingo_ast_attribute_type_ast_array” at the given index.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] index the target index
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Remove an element from an attribute of type “clingo_ast_attribute_type_string_array” at the given index.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] index the target index
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Get the value of an attribute of type “clingo_ast_attribute_type_ast”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[out] value the resulting value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Get the value of an attribute of type “clingo_ast_attribute_type_ast_array” at the given index.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] index the target index
! @param[out] value the resulting value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Get the value of an attribute of type “clingo_ast_attribute_type_location”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[out] value the resulting value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Get the value of an attribute of type “clingo_ast_attribute_type_number”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[out] value the resulting value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Get the value of an attribute of type “clingo_ast_attribute_type_optional_ast”.
!
! @note The value might be “NULL”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[out] value the resulting value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Get the value of an attribute of type “clingo_ast_attribute_type_string”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[out] value the resulting value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Get the value of an attribute of type “clingo_ast_attribute_type_string_array” at the given index.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] index the target index
! @param[out] value the resulting value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Get the value of an attribute of type “clingo_ast_attribute_type_symbol”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[out] value the resulting value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Insert a value into an attribute of type “clingo_ast_attribute_type_ast_array” at the given index.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] index the target index
! @param[in] value the value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! - ::clingo_error_bad_alloc
! Insert a value into an attribute of type “clingo_ast_attribute_type_string_array” at the given index.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] index the target index
! @param[in] value the value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! - ::clingo_error_bad_alloc
! Set the value of an attribute of type “clingo_ast_attribute_type_ast”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] value the value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Set the value of an attribute of type “clingo_ast_attribute_type_ast_array” at the given index.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] index the target index
! @param[in] value the value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! - ::clingo_error_bad_alloc
! Set the value of an attribute of type “clingo_ast_attribute_type_location”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] value the value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Set the value of an attribute of type “clingo_ast_attribute_type_number”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] value the value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Set the value of an attribute of type “clingo_ast_attribute_type_optional_ast”.
!
! @note The value might be “NULL”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] value the value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Set the value of an attribute of type “clingo_ast_attribute_type_string”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] value the value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Set the value of an attribute of type “clingo_ast_attribute_type_string_array” at the given index.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] index the target index
! @param[in] value the value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! - ::clingo_error_bad_alloc
! Set the value of an attribute of type “clingo_ast_attribute_type_symbol”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[in] value the value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Get the size of an attribute of type “clingo_ast_attribute_type_ast_array”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[out] size the resulting size
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Get the size of an attribute of type “clingo_ast_attribute_type_string_array”.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[out] size the resulting size
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Get the type of the given AST.
!
! @param[in] ast the target AST
! @param[in] attribute the target attribute
! @param[out] type the resulting type
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Construct an AST of the given type.
!
! @note The arguments corresponding to the given type can be inspected using “g_clingo_ast_constructors.constructors[type]”.
!
! @param[in] type the type of AST to construct
! @param[out] ast the resulting AST
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if one of the arguments is incompatible with the type
! Create a shallow copy of an AST node.
!
! @param[in] ast the AST to copy
! @param[out] copy the resulting AST
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Create a deep copy of an AST node.
!
! @param[in] ast the AST to copy
! @param[out] copy the resulting AST
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Equality compare two AST nodes.
!
! @param[in] a the left-hand-side AST
! @param[in] b the right-hand-side AST
! @return the result of the comparison
! Get the type of an AST node.
!
! @param[in] ast the target AST
! @param[out] type the resulting type
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Check if an AST has the given attribute.
!
! @param[in] ast the target AST
! @param[in] attribute the attribute to check
! @param[out] has_attribute the result
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Less than compare two AST nodes.
!
! @param[in] a the left-hand-side AST
! @param[in] b the right-hand-side AST
! @return the result of the comparison
! Parse the programs in the given list of files and return an abstract syntax tree for each statement via a callback.
!
! The function follows clingo’s handling of files on the command line.
! Filename “-” is treated as “STDIN” and if an empty list is given, then the parser will read from “STDIN”.
!
! @note The control object can be set to a NULL to disable reading input in aspif format.
!
! @param[in] files the beginning of the file name array
! @param[in] size the number of file names
! @param[in] callback the callback reporting statements
! @param[in] callback_data user data for the callback
! @param[in] control object to add ground statements to
! @param[in] logger callback to report messages during parsing
! @param[in] logger_data user data for the logger
! @param[in] message_limit the maximum number of times the logger is called
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime if parsing fails
! - ::clingo_error_bad_alloc
! Parse the given program and return an abstract syntax tree for each statement via a callback.
!
! @note The control object can be set to a NULL to disable reading input in aspif format.
!
! @param[in] program the program in gringo syntax
! @param[in] callback the callback reporting statements
! @param[in] callback_data user data for the callback
! @param[in] control object to add ground statements to
! @param[in] logger callback to report messages during parsing
! @param[in] logger_data user data for the logger
! @param[in] message_limit the maximum number of times the logger is called
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime if parsing fails
! - ::clingo_error_bad_alloc
! Get the string representation of an AST node.
!
! @param[in] ast the target AST
! @param[out] string the string representation
! @param[out] size the size of the string representation
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Get the size of the string representation of an AST node.
!
! @param[in] ast the target AST
! @param[out] size the size of the string representation
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime
! Unpool the given AST.
!
! @param[in] ast the target AST
! @param[in] unpool_type what to unpool
! @param[in] callback the callback to report ASTs
! @param[in] callback_data user data for the callback
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add an edge directive.
!
! @param[in] backend the target backend
! @param[in] node_u the start vertex of the edge
! @param[in] node_v the end vertex of the edge
! @param[in] condition the condition under which the edge is part of the graph
! @param[in] size the number of atoms in the condition
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Get a fresh atom to be used in aspif directives.
!
! @param[in] backend the target backend
! @param[in] symbol optional symbol to associate the atom with
! @param[out] atom the resulting atom
! @return whether the call was successful
! Add an assumption directive.
!
! @param[in] backend the target backend
! @param[in] literals the literals to assume (positive literals are true and negative literals false for the next solve call)
! @param[in] size the number of atoms
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Prepare the backend for usage.
!
! @param[in] backend the target backend
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime
! Finalize the backend after using it.
!
! @param[in] backend the target backend
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime
! Add an external statement.
!
! @param[in] backend the target backend
! @param[in] atom the external atom
! @param[in] type the type of the external statement
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add an heuristic directive.
!
! @param[in] backend the target backend
! @param[in] atom the target atom
! @param[in] type the type of the heuristic modification
! @param[in] bias the heuristic bias
! @param[in] priority the heuristic priority
! @param[in] condition the condition under which to apply the heuristic modification
! @param[in] size the number of atoms in the condition
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add a minimize constraint (or weak constraint) to the program.
!
! @param[in] backend the target backend
! @param[in] priority the priority of the constraint
! @param[in] literals the weighted literals whose sum to minimize
! @param[in] size the number of weighted literals
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add a projection directive.
!
! @param[in] backend the target backend
! @param[in] atoms the atoms to project on
! @param[in] size the number of atoms
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add a rule to the program.
!
! @param[in] backend the target backend
! @param[in] choice determines if the head is a choice or a disjunction
! @param[in] head the head atoms
! @param[in] head_size the number of atoms in the head
! @param[in] body the body literals
! @param[in] body_size the number of literals in the body
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add a theory atom without a guard.
!
! @param[in] backend the target backend
! @param[in] atom_id_or_zero a program atom or zero for theory directives
! @param[in] term_id the term id of the term associated with the theory atom
! @param[in] elements an array of element ids for the theory atoms’s elements
! @param[in] size the number of elements
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add a theory atom with a guard.
!
! @param[in] backend the target backend
! @param[in] atom_id_or_zero a program atom or zero for theory directives
! @param[in] term_id the term id of the term associated with the theory atom
! @param[in] elements an array of element ids for the theory atoms’s elements
! @param[in] size the number of elements
! @param[in] operator_name the string representation of a theory operator
! @param[in] right_hand_side_id the term id of the right hand side term
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add a theory atom element.
!
! @param[in] backend the target backend
! @param[in] tuple the array of term ids represeting the tuple
! @param[in] tuple_size the size of the tuple
! @param[in] condition an array of program literals represeting the condition
! @param[in] condition_size the size of the condition
! @param[out] element_id the resulting element id
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add a theory term representing a function.
!
! @param[in] backend the target backend
! @param[in] name the name of the function
! @param[in] arguments an array of term ids for the theory terms in the arguments
! @param[in] size the number of arguments
! @param[out] term_id the resulting term id
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add a numeric theory term.
!
! @param[in] backend the target backend
! @param[in] number the value of the term
! @param[out] term_id the resulting term id
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add a theory term representing a sequence of theory terms.
!
! @param[in] backend the target backend
! @param[in] type the type of the sequence
! @param[in] arguments the term ids of the terms in the sequence
! @param[in] size the number of elements of the sequence
! @param[out] term_id the resulting term id
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add a theory term representing a string.
!
! @param[in] backend the target backend
! @param[in] string the value of the term
! @param[out] term_id the resulting term id
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Convert the given symbol into a theory term.
!
! @param[in] backend the target backend
! @param[in] symbol the symbol to convert
! @param[out] term_id the resulting term id
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add a weight rule to the program.
!
! @attention All weights and the lower bound must be positive.
! @param[in] backend the target backend
! @param[in] choice determines if the head is a choice or a disjunction
! @param[in] head the head atoms
! @param[in] head_size the number of atoms in the head
! @param[in] lower_bound the lower bound of the weight rule
! @param[in] body the weighted body literals
! @param[in] body_size the number of weighted literals in the body
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Get the subkey at the given offset of an array entry.
!
! @note Some array entries, like fore example the solver configuration, can be accessed past there actual size to add subentries.
! @pre The @link clingo_configuration_type() type@endlink of the entry must be @ref ::clingo_configuration_type_array.
! @param[in] configuration the target configuration
! @param[in] key the key
! @param[in] offset the offset in the array
! @param[out] subkey the resulting subkey
! @return whether the call was successful
! Get the size of an array entry.
!
! @pre The @link clingo_configuration_type() type@endlink of the entry must be @ref ::clingo_configuration_type_array.
! @param[in] configuration the target configuration
! @param[in] key the key
! @param[out] size the resulting size
! @return whether the call was successful
! Get the description of an entry.
!
! @param[in] configuration the target configuration
! @param[in] key the key
! @param[out] description the description
! @return whether the call was successful
! Lookup a subkey under the given name.
!
! @pre The @link clingo_configuration_type() type@endlink of the entry must be @ref ::clingo_configuration_type_map.
! @note Multiple levels can be looked up by concatenating keys with a period.
! @param[in] configuration the target configuration
! @param[in] key the key
! @param[in] name the name to lookup the subkey
! @param[out] subkey the resulting subkey
! @return whether the call was successful
! Query whether the map has a key.
!
! @pre The @link clingo_configuration_type() type@endlink of the entry must be @ref ::clingo_configuration_type_map.
! @note Multiple levels can be looked up by concatenating keys with a period.
! @param[in] configuration the target configuration
! @param[in] key the key
! @param[in] name the name to lookup the subkey
! @param[out] result whether the key is in the map
! @return whether the call was successful
! Get the number of subkeys of a map entry.
!
! @pre The @link clingo_configuration_type() type@endlink of the entry must be @ref ::clingo_configuration_type_map.
! @param[in] configuration the target configuration
! @param[in] key the key
! @param[out] size the resulting number
! @return whether the call was successful
! Get the name associated with the offset-th subkey.
!
! @pre The @link clingo_configuration_type() type@endlink of the entry must be @ref ::clingo_configuration_type_map.
! @param[in] configuration the target configuration
! @param[in] key the key
! @param[in] offset the offset of the name
! @param[out] name the resulting name
! @return whether the call was successful
! Get the root key of the configuration.
!
! @param[in] configuration the target configuration
! @param[out] key the root key
! @return whether the call was successful
! Get the type of a key.
!
! @note The type is bitset, an entry can have multiple (but at least one) type.
!
! @param[in] configuration the target configuration
! @param[in] key the key
! @param[out] type the resulting type
! @return whether the call was successful
! Get the string value of the given entry.
!
! @pre The @link clingo_configuration_type() type@endlink of the entry must be @ref ::clingo_configuration_type_value.
! @pre The given size must be larger or equal to size of the value.
! @param[in] configuration the target configuration
! @param[in] key the key
! @param[out] value the resulting string value
! @param[in] size the size of the given char array
! @return whether the call was successful
! Get the size of the string value of the given entry.
!
! @pre The @link clingo_configuration_type() type@endlink of the entry must be @ref ::clingo_configuration_type_value.
! @param[in] configuration the target configuration
! @param[in] key the key
! @param[out] size the resulting size
! @return whether the call was successful
! Check whether a entry has a value.
!
! @pre The @link clingo_configuration_type() type@endlink of the entry must be @ref ::clingo_configuration_type_value.
! @param[in] configuration the target configuration
! @param[in] key the key
! @param[out] assigned whether the entry has a value
! @return whether the call was successful
! Set the value of an entry.
!
! @pre The @link clingo_configuration_type() type@endlink of the entry must be @ref ::clingo_configuration_type_value.
! @param[in] configuration the target configuration
! @param[in] key the key
! @param[in] value the value to set
! @return whether the call was successful
! Extend the logic program with the given non-ground logic program in string form.
!
! This function puts the given program into a block of form: #program name(parameters).
!
! After extending the logic program, the corresponding program parts are typically grounded with ::clingo_control_ground.
!
! @param[in] control the target
! @param[in] name name of the program block
! @param[in] parameters string array of parameters of the program block
! @param[in] parameters_size number of parameters
! @param[in] program string representation of the program
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if parsing fails
! Assign a truth value to an external atom.
!
! If a negative literal is passed, the corresponding atom is assigned the
! inverted truth value.
!
! If the atom does not exist or is not external, this is a noop.
!
! @param[in] control the target
! @param[in] literal literal to assign
! @param[in] value the truth value
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Get an object to add ground directives to the program.
!
! See the @ref ProgramBuilder module for more information.
!
! @param[in] control the target
! @param[out] backend the backend object
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Get low-level access to clasp.
!
! @attention
! This function is intended for experimental use only and not part of the stable API.
!
! This function may return a nullptr.
! Otherwise, the returned pointer can be casted to a ClaspFacade pointer.
!
! @param[in] control the target
! @param[out] clasp pointer to the ClaspFacade object (may be nullptr)
! @return whether the call was successful
! @param[in] control the target
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
!
! @see clingo_control_get_enable_cleanup()
! @see clingo_control_set_enable_cleanup()
! Get a configuration object to change the solver configuration.
!
! See the @ref Configuration module for more information.
!
! @param[in] control the target
! @param[out] configuration the configuration object
! @return whether the call was successful
! Return the symbol for a constant definition of form: #const name = symbol.
!
! @param[in] control the target
! @param[in] name the name of the constant
! @param[out] symbol the resulting symbol
! @return whether the call was successful
! Check whether the enumeration assumption is enabled.
!
! See ::clingo_control_set_enable_enumeration_assumption().
! @param[in] control the target
! @return whether using the enumeration assumption is enabled
! Ground the selected @link ::clingo_part parts @endlink of the current (non-ground) logic program.
!
! After grounding, logic programs can be solved with ::clingo_control_solve().
!
! @note Parts of a logic program without an explicit #program
! specification are by default put into a program called base without
! arguments.
!
! @param[in] control the target
! @param[in] parts array of parts to ground
! @param[in] parts_size size of the parts array
! @param[in] ground_callback callback to implement external functions
! @param[in] ground_callback_data user data for ground_callback
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - error code of ground callback
!
! @see clingo_part
! Check if there is a constant definition for the given constant.
!
! @param[in] control the target
! @param[in] name the name of the constant
! @param[out] exists whether a matching constant definition exists
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime if constant definition does not exist
!
! @see clingo_control_get_const()
! Check if the solver has determined that the internal program representation is conflicting.
!
! If this function returns true, solve calls will return immediately with an unsatisfiable solve result.
! Note that conflicts first have to be detected, e.g. -
! initial unit propagation results in an empty clause,
! or later if an empty clause is resolved during solving.
! Hence, the function might return false even if the problem is unsatisfiable.
!
! @param[in] control the target
! @return whether the program representation is conflicting
! Extend the logic program with a program in a file.
!
! @param[in] control the target
! @param[in] file path to the file
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if parsing or checking fails
! Create a new control object.
!
! A control object has to be freed using clingo_control_free().
!
! @note Only gringo options (without --output) and clasp’s options are supported as arguments,
! except basic options such as --help.
! Furthermore, a control object is blocked while a search call is active;
! you must not call any member function during search.
!
! If the logger is NULL, messages are printed to stderr.
!
! @param[in] arguments C string array of command line arguments
! @param[in] arguments_size size of the arguments array
! @param[in] logger callback functions for warnings and info messages
! @param[in] logger_data user data for the logger callback
! @param[in] message_limit maximum number of times the logger callback is called
! @param[out] control resulting control object
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if argument parsing fails
! Register a program observer with the control object.
!
! @param[in] control the target
! @param[in] observer the observer to register
! @param[in] replace just pass the grounding to the observer but not the solver
! @param[in] data user data passed to the observer functions
! @return whether the call was successful
! Register a custom propagator with the control object.
!
! If the sequential flag is set to true, the propagator is called
! sequentially when solving with multiple threads.
!
! See the @ref Propagator module for more information.
!
! @param[in] control the target
! @param[in] propagator the propagator
! @param[in] data user data passed to the propagator functions
! @param[in] sequential whether the propagator should be called sequentially
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Release an external atom.
!
! If a negative literal is passed, the corresponding atom is released.
!
! After this call, an external atom is no longer external and subject to
! program simplifications. If the atom does not exist or is not external,
! this is a noop.
!
! @param[in] control the target
! @param[in] literal literal to release
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Configure how learnt constraints are handled during enumeration.
!
! If the enumeration assumption is enabled, then all information learnt from
! the solver’s various enumeration modes is removed after a solve call. This
! includes enumeration of cautious or brave consequences, enumeration of
! answer sets with or without projection, or finding optimal models, as well
! as clauses added with clingo_solve_control_add_clause().
!
! @attention For practical purposes, this option is only interesting for single-shot solving
! or before the last solve call to squeeze out a tiny bit of performance.
! Initially, the enumeration assumption is enabled.
!
! @param[in] control the target
! @param[in] enable whether to enable the assumption
! @return whether the call was successful
! Solve the currently @link ::clingo_control_ground grounded @endlink logic program enumerating its models.
!
! See the @ref SolveHandle module for more information.
!
! @param[in] control the target
! @param[in] mode configures the search mode
! @param[in] assumptions array of assumptions to solve under
! @param[in] assumptions_size number of assumptions
! @param[in] notify the event handler to register
! @param[in] data the user data for the event handler
! @param[out] handle handle to the current search to enumerate models
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if solving could not be started
! Get a statistics object to inspect solver statistics.
!
! Statistics are updated after a solve call.
!
! See the @ref Statistics module for more information.
!
! @attention
! The level of detail of the statistics depends on the stats option
! (which can be set using @ref Configuration module or passed as an option when @link clingo_control_new creating the control object@endlink).
! The default level zero only provides basic statistics,
! level one provides extended and accumulated statistics,
! and level two provides per-thread statistics.
! Furthermore, the statistics object is best accessed right after solving.
! Otherwise, not all of its entries have valid values.
!
! @param[in] control the target
! @param[out] statistics the statistics object
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Get an object to inspect symbolic atoms (the relevant Herbrand base) used
! for grounding.
!
! See the @ref SymbolicAtoms module for more information.
!
! @param[in] control the target
! @param[out] atoms the symbolic atoms object
! @return whether the call was successful
! Get an object to inspect theory atoms that occur in the grounding.
!
! See the @ref TheoryAtoms module for more information.
!
! @param[in] control the target
! @param[out] atoms the theory atoms object
! @return whether the call was successful
! Run clingo with a customized main function (similar to python and lua embedding).
!
! @param[in] application struct with callbacks to override default clingo functionality
! @param[in] arguments command line arguments
! @param[in] size number of arguments
! @param[in] data user data to pass to callbacks in application
! @return exit code to return from main function
! Constant time lookup to test whether an atom is in a model.
!
! @param[in] model the target
! @param[in] atom the atom to lookup
! @param[out] contained whether the atom is contained
! @return whether the call was successful
! Get the associated solve control object of a model.
!
! This object allows for adding clauses during model enumeration.
! @param[in] model the target
! @param[out] control the resulting solve control object
! @return whether the call was successful
! Get the cost vector of a model.
!
! @param[in] model the target
! @param[out] costs the resulting costs
! @param[in] size the number of costs
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if the size is too small
!
! @see clingo_model_cost_size()
! @see clingo_model_optimality_proven()
! Get the number of cost values of a model.
!
! @param[in] model the target
! @param[out] size the number of costs
! @return whether the call was successful
! Add symbols to the model.
!
! These symbols will appear in clingo’s output, which means that this
! function is only meaningful if there is an underlying clingo application.
! Only models passed to the ::clingo_solve_event_callback_t are extendable.
!
! @param[in] model the target
! @param[in] symbols the symbols to add
! @param[in] size the number of symbols to add
! @return whether the call was successful
! Check if a program literal is true in a model.
!
! @param[in] model the target
! @param[in] literal the literal to lookup
! @param[out] result whether the literal is true
! @return whether the call was successful
! Get the running number of the model.
!
! @param[in] model the target
! @param[out] number the number of the model
! @return whether the call was successful
! Whether the optimality of a model has been proven.
!
! @param[in] model the target
! @param[out] proven whether the optimality has been proven
! @return whether the call was successful
!
! @see clingo_model_cost()
! Get the symbols of the selected types in the model.
!
! @note CSP assignments are represented using functions with name “$”
! where the first argument is the name of the CSP variable and the second one its
! value.
!
! @param[in] model the target
! @param[in] show which symbols to select
! @param[out] symbols the resulting symbols
! @param[in] size the number of selected symbols
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if the size is too small
!
! @see clingo_model_symbols_size()
! Get the number of symbols of the selected types in the model.
!
! @param[in] model the target
! @param[in] show which symbols to select
! @param[out] size the number symbols
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Get the id of the solver thread that found the model.
!
! @param[in] model the target
! @param[out] id the resulting thread id
! @return whether the call was successful
! Add an option that is processed with a custom parser.
!
! Note that the parser also has to take care of storing the semantic value of
! the option somewhere.
!
! Parameter option specifies the name(s) of the option.
! For example, “ping,p” adds the short option “-p” and its long form “–ping”.
! It is also possible to associate an option with a help level by adding “,@l” to the option specification.
! Options with a level greater than zero are only shown if the argument to help is greater or equal to l.
!
! @param[in] options object to register the option with
! @param[in] group options are grouped into sections as given by this string
! @param[in] option specifies the command line option
! @param[in] description the description of the option
! @param[in] parse callback to parse the value of the option
! @param[in] data user data for the callback
! @param[in] multi whether the option can appear multiple times on the command-line
! @param[in] argument optional string to change the value name in the generated help output
! @return whether the call was successful
! Add an option that is a simple flag.
!
! This function is similar to @ref clingo_options_add() but simpler because it only supports flags, which do not have values.
! If a flag is passed via the command-line the parameter target is set to true.
!
! @param[in] options object to register the option with
! @param[in] group options are grouped into sections as given by this string
! @param[in] option specifies the command line option
! @param[in] description the description of the option
! @param[in] target boolean set to true if the flag is given on the command-line
! @return whether the call was successful
! 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.
!
! @param[in] string the string to parse
! @param[in] logger optional logger to report warnings during parsing
! @param[in] logger_data user data for the logger
! @param[in] message_limit maximum number of times to call the logger
! @param[out] symbol the resulting symbol
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if parsing fails
! Adds a statement to the program.
!
! @attention @ref clingo_program_builder_begin() must be called before adding statements and @ref clingo_program_builder_end() must be called after all statements have been added.
! @param[in] builder the target program builder
! @param[in] ast the AST node to add
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime for statements of invalid form or AST nodes that do not represent statements
! - ::clingo_error_bad_alloc
! Get an object to add non-ground directives to the program.
!
! See the @ref ProgramBuilder module for more information.
!
! @param[in] control the target
! @param[out] builder the program builder object
! @return whether the call was successful
! Add the given clause to the solver.
!
! This method sets its result to false if the current propagation must be stopped for the solver to backtrack.
!
! @attention No further calls on the control object or functions on the assignment should be called when the result of this method is false.
!
! @param[in] control the target
! @param[in] clause the clause to add
! @param[in] size the size of the clause
! @param[in] type the clause type determining its lifetime
! @param[out] result result indicating whether propagation has to be stopped
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Adds a new volatile literal to the underlying solver thread.
!
! @attention The literal is only valid within the current solving step and solver thread.
! All volatile literals and clauses involving a volatile literal are deleted after the current search.
!
! @param[in] control the target
! @param[out] result the (positive) solver literal
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_logic if the assignment is conflicting
! Add a watch for the solver literal in the given phase.
!
! @note Unlike @ref clingo_propagate_init_add_watch() this does not add a watch to all solver threads but just the current one.
!
! @param[in] control the target
! @param[in] literal the literal to watch
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_logic if the literal is invalid
! @see clingo_propagate_control_remove_watch()
! Check whether a literal is watched in the current solver thread.
!
! @param[in] control the target
! @param[in] literal the literal to check
!
! @return whether the literal is watched
! Propagate implied literals (resulting from added clauses).
!
! This method sets its result to false if the current propagation must be stopped for the solver to backtrack.
!
! @attention No further calls on the control object or functions on the assignment should be called when the result of this method is false.
!
! @param[in] control the target
! @param[out] result result indicating whether propagation has to be stopped
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Removes the watch (if any) for the given solver literal.
!
! @note Similar to @ref clingo_propagate_init_add_watch() this just removes the watch in the current solver thread.
!
! @param[in] control the target
! @param[in] literal the literal to remove
! Get the id of the underlying solver thread.
!
! Thread ids are consecutive numbers starting with zero.
!
! @param[in] control the target
! @return the thread id
! Add the given clause to the solver.
!
! @attention No further calls on the init object or functions on the assignment should be called when the result of this method is false.
!
! @param[in] init the target
! @param[in] clause the clause to add
! @param[in] size the size of the clause
! @param[out] result result indicating whether the problem became unsatisfiable
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add a literal to the solver.
!
! To be able to use the variable in clauses during propagation or add watches to it, it has to be frozen.
! Otherwise, it might be removed during preprocessing.
!
! @attention If varibales were added, subsequent calls to functions adding constraints or ::clingo_propagate_init_propagate() are expensive.
! It is best to add varables in batches.
!
! @param[in] init the target
! @param[in] freeze whether to freeze the literal
! @param[out] result the added literal
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add the given literal to minimize to the solver.
!
! This corresponds to a weak constraint of form :~ literal. [weight@priority].
!
! @param[in] init the target
! @param[in] literal the literal to minimize
! @param[in] weight the weight of the literal
! @param[in] priority the priority of the literal
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Add a watch for the solver literal in the given phase.
!
! @param[in] init the target
! @param[in] solver_literal the solver literal
! @return whether the call was successful
! Add a watch for the solver literal in the given phase to the given solver thread.
!
! @param[in] init the target
! @param[in] solver_literal the solver literal
! @param[in] thread_id the id of the solver thread
! @return whether the call was successful
! Add the given weight constraint to the solver.
!
! This function adds a constraint of form literal <=> { lit=weight | (lit, weight) in literals } >= bound to the solver.
! Depending on the type the <=> connective can be either a left implication, right implication, or equivalence.
!
! @attention No further calls on the init object or functions on the assignment should be called when the result of this method is false.
!
! @param[in] init the target
! @param[in] literal the literal of the constraint
! @param[in] literals the weighted literals
! @param[in] size the number of weighted literals
! @param[in] bound the bound of the constraint
! @param[in] type the type of the weight constraint
! @param[in] compare_equal if true compare equal instead of less than equal
! @param[out] result result indicating whether the problem became unsatisfiable
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Freeze the given solver literal.
!
! Any solver literal that is not frozen is subject to simplification and might be removed in a preprocessing step after propagator initialization.
! A propagator should freeze all literals over which it might add clauses during propagation.
! Note that any watched literal is automatically frozen and that it does not matter which phase of the literal is frozen.
!
! @param[in] init the target
! @param[in] solver_literal the solver literal
! @return whether the call was successful
! Get the current check mode of the propagator.
!
! @param[in] init the target
! @return bitmask when to call the propagator
! @see clingo_propagate_init_set_check_mode()
! Get the number of threads used in subsequent solving.
!
! @param[in] init the target
! @return the number of threads
! @see clingo_propagate_control_thread_id()
! Propagates consequences of the underlying problem excluding registered propagators.
!
! @note The function has no effect if SAT-preprocessing is enabled.
! @attention No further calls on the init object or functions on the assignment should be called when the result of this method is false.
!
! @param[in] init the target
! @param[out] result result indicating whether the problem became unsatisfiable
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Remove the watch for the solver literal in the given phase.
!
! @param[in] init the target
! @param[in] solver_literal the solver literal
! @return whether the call was successful
! Remove the watch for the solver literal in the given phase from the given solver thread.
!
! @param[in] init the target
! @param[in] solver_literal the solver literal
! @param[in] thread_id the id of the solver thread
! @return whether the call was successful
! Configure when to call the check method of the propagator.
!
! @param[in] init the target
! @param[in] mode bitmask when to call the propagator
! @see @ref ::clingo_propagator::check()
! Map the given program literal or condition id to its solver literal.
!
! @param[in] init the target
! @param[in] aspif_literal the aspif literal to map
! @param[out] solver_literal the resulting solver literal
! @return whether the call was successful
! Get an object to inspect the symbolic atoms.
!
! @param[in] init the target
! @param[out] atoms the resulting object
! @return whether the call was successful
! Get an object to inspect the theory atoms.
!
! @param[in] init the target
! @param[out] atoms the resulting object
! @return whether the call was successful
! Add a custom scripting language to clingo.
!
! @param[in] name the name of the scripting language
! @param[in] script struct with functions implementing the language
! @param[in] data user data to pass to callbacks in the script
! @return whether the call was successful
! Create a new signature.
!
! @param[in] name name of the signature
! @param[in] arity arity of the signature
! @param[in] positive false if the signature has a classical negation sign
! @param[out] signature the resulting signature
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Check if a signature is less than another signature.
!
! Signatures are compared first by sign (unsigned < signed), then by arity,
! then by name.
!
! @param[in] a first signature
! @param[in] b second signature
! @return whether a < b
! Whether the signature is positive (is not classically negated).
!
! @param[in] signature the target signature
! @return whether the signature has no sign
! Get the name of a signature.
!
! @note
! The string is internalized and valid for the duration of the process.
!
! @param[in] signature the target signature
! @return the name of the signature
! Add a clause that applies to the current solving step during model
! enumeration.
!
! @note The @ref Propagator module provides a more sophisticated
! interface to add clauses - even on partial assignments.
!
! @param[in] control the target
! @param[in] clause array of literals representing the clause
! @param[in] size the size of the literal array
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if adding the clause fails
! Get an object to inspect the symbolic atoms.
!
! @param[in] control the target
! @param[out] atoms the resulting object
! @return whether the call was successful
! Stop the running search and block until done.
!
! @param[in] handle the target
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if solving fails
! Stops the running search and releases the handle.
!
! Blocks until the search is stopped (as if an implicit cancel was called before the handle is released).
!
! @param[in] handle the target
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if solving fails
! When a problem is unsatisfiable, get a subset of the assumptions that made the problem unsatisfiable.
!
! If the program is not unsatisfiable, core is set to NULL and size to zero.
!
! @param[in] handle the target
! @param[out] core pointer where to store the core
! @param[out] size size of the given array
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Get the next solve result.
!
! Blocks until the result is ready.
! When yielding partial solve results can be obtained, i.e.,
! when a model is ready, the result will be satisfiable but neither the search exhausted nor the optimality proven.
!
! @param[in] handle the target
! @param[out] result the solve result
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if solving fails
! Get the next model (or zero if there are no more models).
!
! @param[in] handle the target
! @param[out] model the model (it is NULL if there are no more models)
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if solving fails
! Discards the last model and starts the search for the next one.
!
! If the search has been started asynchronously, this function continues the search in the background.
!
! @note This function does not block.
!
! @param[in] handle the target
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if solving fails
! Wait for the specified amount of time to check if the next result is ready.
!
! If the time is set to zero, this function can be used to poll if the search is still active.
! If the time is negative, the function blocks until the search is finished.
!
! @param[in] handle the target
! @param[in] timeout the maximum time to wait
! @param[out] result whether the search has finished
! Get the subkey at the given offset of an array entry.
!
! @pre The @link clingo_statistics_type() type@endlink of the entry must be @ref ::clingo_statistics_type_array.
! @param[in] statistics the target statistics
! @param[in] key the key
! @param[in] offset the offset in the array
! @param[out] subkey the resulting subkey
! @return whether the call was successful
! Create the subkey at the end of an array entry.
!
! @pre The @link clingo_statistics_type() type@endlink of the entry must be @ref ::clingo_statistics_type_array.
! @param[in] statistics the target statistics
! @param[in] key the key
! @param[in] type the type of the new subkey
! @param[out] subkey the resulting subkey
! @return whether the call was successful
! Get the size of an array entry.
!
! @pre The @link clingo_statistics_type() type@endlink of the entry must be @ref ::clingo_statistics_type_array.
! @param[in] statistics the target statistics
! @param[in] key the key
! @param[out] size the resulting size
! @return whether the call was successful
! Add a subkey with the given name.
!
! @pre The @link clingo_statistics_type() type@endlink of the entry must be @ref ::clingo_statistics_type_map.
! @param[in] statistics the target statistics
! @param[in] key the key
! @param[in] name the name of the new subkey
! @param[in] type the type of the new subkey
! @param[out] subkey the index of the resulting subkey
! @return whether the call was successful
! Lookup a subkey under the given name.
!
! @pre The @link clingo_statistics_type() type@endlink of the entry must be @ref ::clingo_statistics_type_map.
! @note Multiple levels can be looked up by concatenating keys with a period.
! @param[in] statistics the target statistics
! @param[in] key the key
! @param[in] name the name to lookup the subkey
! @param[out] subkey the resulting subkey
! @return whether the call was successful
! Test if the given map contains a specific subkey.
!
! @pre The @link clingo_statistics_type() type@endlink of the entry must be @ref ::clingo_statistics_type_map.
! @param[in] statistics the target statistics
! @param[in] key the key
! @param[in] name name of the subkey
! @param[out] result true if the map has a subkey with the given name
! @return whether the call was successful
! Get the number of subkeys of a map entry.
!
! @pre The @link clingo_statistics_type() type@endlink of the entry must be @ref ::clingo_statistics_type_map.
! @param[in] statistics the target statistics
! @param[in] key the key
! @param[out] size the resulting number
! @return whether the call was successful
! Get the name associated with the offset-th subkey.
!
! @pre The @link clingo_statistics_type() type@endlink of the entry must be @ref ::clingo_statistics_type_map.
! @param[in] statistics the target statistics
! @param[in] key the key
! @param[in] offset the offset of the name
! @param[out] name the resulting name
! @return whether the call was successful
! Get the root key of the statistics.
!
! @param[in] statistics the target statistics
! @param[out] key the root key
! @return whether the call was successful
! Get the type of a key.
!
! @param[in] statistics the target statistics
! @param[in] key the key
! @param[out] type the resulting type
! @return whether the call was successful
! Get the value of the given entry.
!
! @pre The @link clingo_statistics_type() type@endlink of the entry must be @ref ::clingo_statistics_type_value.
! @param[in] statistics the target statistics
! @param[in] key the key
! @param[out] value the resulting value
! @return whether the call was successful
! Set the value of the given entry.
!
! @pre The @link clingo_statistics_type() type@endlink of the entry must be @ref ::clingo_statistics_type_value.
! @param[in] statistics the target statistics
! @param[in] key the key
! @param[out] value the new value
! @return whether the call was successful
! Get the arguments of a symbol.
!
! @param[in] symbol the target symbol
! @param[out] arguments the resulting arguments
! @param[out] arguments_size the number of arguments
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime if symbol is not of type ::clingo_symbol_type_function
! Construct a symbol representing a function or tuple.
!
! @note To create tuples, the empty string has to be used as name.
!
! @param[in] name the name of the function
! @param[in] arguments the arguments of the function
! @param[in] arguments_size the number of arguments
! @param[in] positive whether the symbol has a classical negation sign
! @param[out] symbol the resulting symbol
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Construct a symbol representing an id.
!
! @note This is just a shortcut for clingo_symbol_create_function() with
! empty arguments.
!
! @param[in] name the name
! @param[in] positive whether the symbol has a classical negation sign
! @param[out] symbol the resulting symbol
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Construct a symbol representing a string.
!
! @param[in] string the string
! @param[out] symbol the resulting symbol
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! 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.
!
! @param[in] a first symbol
! @param[in] b second symbol
! @return whether a < b
! Check if a function is negative (has a sign).
!
! @param[in] symbol the target symbol
! @param[out] negative the result
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime if symbol is not of type ::clingo_symbol_type_function
! Check if a function is positive (does not have a sign).
!
! @param[in] symbol the target symbol
! @param[out] positive the result
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime if symbol is not of type ::clingo_symbol_type_function
! Get the name of a symbol.
!
! @note
! The string is internalized and valid for the duration of the process.
!
! @param[in] symbol the target symbol
! @param[out] name the resulting name
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime if symbol is not of type ::clingo_symbol_type_function
! Get the number of a symbol.
!
! @param[in] symbol the target symbol
! @param[out] number the resulting number
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime if symbol is not of type ::clingo_symbol_type_number
! Get the string of a symbol.
!
! @note
! The string is internalized and valid for the duration of the process.
!
! @param[in] symbol the target symbol
! @param[out] string the resulting string
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime if symbol is not of type ::clingo_symbol_type_string
! Get the string representation of a symbol.
!
! @param[in] symbol the target symbol
! @param[out] string the resulting string
! @param[in] size the size of the string
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
!
! @see clingo_symbol_to_string_size()
! Get the size of the string representation of a symbol (including the terminating 0).
!
! @param[in] symbol the target symbol
! @param[out] size the resulting size
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Get a forward iterator to the beginning of the sequence of all symbolic
! atoms optionally restricted to a given signature.
!
! @param[in] atoms the target
! @param[in] signature optional signature
! @param[out] iterator the resulting iterator
! @return whether the call was successful
! Iterator pointing to the end of the sequence of symbolic atoms.
!
! @param[in] atoms the target
! @param[out] iterator the resulting iterator
! @return whether the call was successful
! Find a symbolic atom given its symbolic representation.
!
! @param[in] atoms the target
! @param[in] symbol the symbol to lookup
! @param[out] iterator iterator pointing to the symbolic atom or to the end
! of the sequence if no corresponding atom is found
! @return whether the call was successful
! Check whether an atom is external.
!
! An atom is external if it has been defined using an external directive and
! has not been released or defined by a rule.
!
! @param[in] atoms the target
! @param[in] iterator iterator to the atom
! @param[out] external whether the atom is a external
! @return whether the call was successful
! Check whether an atom is a fact.
!
! @note This does not determine if an atom is a cautious consequence. The
! grounding or solving component’s simplifications can only detect this in
! some cases.
!
! @param[in] atoms the target
! @param[in] iterator iterator to the atom
! @param[out] fact whether the atom is a fact
! @return whether the call was successful
! Check whether the given iterator points to some element with the sequence
! of symbolic atoms or to the end of the sequence.
!
! @param[in] atoms the target
! @param[in] iterator the iterator
! @param[out] valid whether the iterator points to some element within the
! sequence
! @return whether the call was successful
! Check if two iterators point to the same element (or end of the sequence).
!
! @param[in] atoms the target
! @param[in] a the first iterator
! @param[in] b the second iterator
! @param[out] equal whether the two iterators are equal
! @return whether the call was successful
! Returns the (numeric) aspif literal corresponding to the given symbolic atom.
!
! Such a literal can be mapped to a solver literal (see the \ref Propagator
! module) or be used in rules in aspif format (see the \ref ProgramBuilder
! module).
!
! @param[in] atoms the target
! @param[in] iterator iterator to the atom
! @param[out] literal the associated literal
! @return whether the call was successful
! Get an iterator to the next element in the sequence of symbolic atoms.
!
! @param[in] atoms the target
! @param[in] iterator the current iterator
! @param[out] next the succeeding iterator
! @return whether the call was successful
! Get the predicate signatures occurring in a logic program.
!
! @param[in] atoms the target
! @param[out] signatures the resulting signatures
! @param[in] size the number of signatures
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! - ::clingo_error_runtime if the size is too small
!
! @see clingo_symbolic_atoms_signatures_size()
! Get the number of different predicate signatures used in the program.
!
! @param[in] atoms the target
! @param[out] size the number of signatures
! @return whether the call was successful
! Get the number of different atoms occurring in a logic program.
!
! @param[in] atoms the target
! @param[out] size the number of atoms
! @return whether the call was successful
! Get the symbolic representation of an atom.
!
! @param[in] atoms the target
! @param[in] iterator iterator to the atom
! @param[out] symbol the resulting symbol
! @return whether the call was successful
! Get the theory elements associated with the theory atom.
!
! @param[in] atoms container where the atom is stored
! @param[in] atom id of the atom
! @param[out] elements the resulting array of elements
! @param[out] size the number of elements
! @return whether the call was successful
! Get the guard consisting of a theory operator and a theory term of the given theory atom.
!
! @note
! The lifetime of the string is tied to the current solve step.
!
! @param[in] atoms container where the atom is stored
! @param[in] atom id of the atom
! @param[out] connective the resulting theory operator
! @param[out] term the resulting term
! @return whether the call was successful
! Whether the theory atom has a guard.
!
! @param[in] atoms container where the atom is stored
! @param[in] atom id of the atom
! @param[out] has_guard whether the theory atom has a guard
! @return whether the call was successful
! Get the aspif literal associated with the given theory atom.
!
! @param[in] atoms container where the atom is stored
! @param[in] atom id of the atom
! @param[out] literal the resulting literal
! @return whether the call was successful
! Get the theory term associated with the theory atom.
!
! @param[in] atoms container where the atom is stored
! @param[in] atom id of the atom
! @param[out] term the resulting term id
! @return whether the call was successful
! Get the string representation of the given theory atom.
!
! @param[in] atoms container where the atom is stored
! @param[in] atom id of the element
! @param[out] string the resulting string
! @param[in] size the size of the string
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime if the size is too small
! - ::clingo_error_bad_alloc
! Get the size of the string representation of the given theory atom (including the terminating 0).
!
! @param[in] atoms container where the atom is stored
! @param[in] atom id of the element
! @param[out] size the resulting size
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Get the condition (array of aspif literals) of the given theory element.
!
! @param[in] atoms container where the element is stored
! @param[in] element id of the element
! @param[out] condition the resulting array of aspif literals
! @param[out] size the number of term literals
! @return whether the call was successful
! Get the id of the condition of the given theory element.
!
! @note
! This id can be mapped to a solver literal using clingo_propagate_init_solver_literal().
! This id is not (necessarily) an aspif literal;
! to get aspif literals use clingo_theory_atoms_element_condition().
!
! @param[in] atoms container where the element is stored
! @param[in] element id of the element
! @param[out] condition the resulting condition id
! @return whether the call was successful
! Get the string representation of the given theory element.
!
! @param[in] atoms container where the element is stored
! @param[in] element id of the element
! @param[out] string the resulting string
! @param[in] size the size of the string
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime if the size is too small
! - ::clingo_error_bad_alloc
! Get the size of the string representation of the given theory element (including the terminating 0).
!
! @param[in] atoms container where the element is stored
! @param[in] element id of the element
! @param[out] size the resulting size
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Get the tuple (array of theory terms) of the given theory element.
!
! @param[in] atoms container where the element is stored
! @param[in] element id of the element
! @param[out] tuple the resulting array of term ids
! @param[out] size the number of term ids
! @return whether the call was successful
! Get the total number of theory atoms.
!
! @param[in] atoms the target
! @param[out] size the resulting number
! @return whether the call was successful
! Get the arguments of the given function theory term.
!
! @pre The term must be of type ::clingo_theory_term_type_function.
! @param[in] atoms container where the term is stored
! @param[in] term id of the term
! @param[out] arguments the resulting arguments in form of an array of term ids
! @param[out] size the number of arguments
! @return whether the call was successful
! Get the name of the given constant or function theory term.
!
! @note
! The lifetime of the string is tied to the current solve step.
!
! @pre The term must be of type ::clingo_theory_term_type_function or ::clingo_theory_term_type_symbol.
! @param[in] atoms container where the term is stored
! @param[in] term id of the term
! @param[out] name the resulting name
! @return whether the call was successful
! Get the number of the given numeric theory term.
!
! @pre The term must be of type ::clingo_theory_term_type_number.
! @param[in] atoms container where the term is stored
! @param[in] term id of the term
! @param[out] number the resulting number
! @return whether the call was successful
! Get the string representation of the given theory term.
!
! @param[in] atoms container where the term is stored
! @param[in] term id of the term
! @param[out] string the resulting string
! @param[in] size the size of the string
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_runtime if the size is too small
! - ::clingo_error_bad_alloc
!
! @see clingo_theory_atoms_term_to_string_size()
! Get the size of the string representation of the given theory term (including the terminating 0).
!
! @param[in] atoms container where the term is stored
! @param[in] term id of the term
! @param[out] size the resulting size
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! Get the type of the given theory term.
!
! @param[in] atoms container where the term is stored
! @param[in] term id of the term
! @param[out] type the resulting type
! @return whether the call was successful
! Obtain the clingo version.
!
! @param[out] major major version number
! @param[out] minor minor version number
! @param[out] revision revision number
! Represents a (partial) assignment of a particular solver.
!
! An assignment assigns truth values to a set of literals.
! A literal is assigned to either @link clingo_assignment_truth_value() true or false, or is unassigned@endlink.
! Furthermore, each assigned literal is associated with a @link clingo_assignment_level() decision level@endlink.
! There is exactly one @link clingo_assignment_decision() decision literal@endlink for each decision level greater than zero.
! Assignments to all other literals on the same level are consequences implied by the current and possibly previous decisions.
! Assignments on level zero are immediate consequences of the current program.
! Decision levels are consecutive numbers starting with zero up to and including the @link clingo_assignment_decision_level() current decision level@endlink.
! Enumeration of clause types determining the lifetime of a clause.
!
! Clauses in the solver are either cleaned up based on a configurable deletion policy or at the end of a solving step.
! The values of this enumeration determine if a clause is subject to one of the above deletion strategies.
! Enumeration of error codes.
!
! @note Errors can only be recovered from if explicitly mentioned; most
! functions do not provide strong exception guarantees. This means that in
! case of errors associated objects cannot be used further. If such an
! object has a free function, this function can and should still be called.
! Callback function to implement external functions.
!
! If an external function of form @name(parameters) occurs in a logic program,
! then this function is called with its location, name, parameters, and a callback to inject symbols as arguments.
! The callback can be called multiple times; all symbols passed are injected.
!
! If a (non-recoverable) clingo API function fails in this callback, for example, the symbol callback, the callback must return false.
! In case of errors not related to clingo, this function can set error ::clingo_error_unknown and return false to stop grounding with an error.
!
! @param[in] location location from which the external function was called
! @param[in] name name of the called external function
! @param[in] arguments arguments of the called external function
! @param[in] arguments_size number of arguments
! @param[in] data user data of the callback
! @param[in] symbol_callback function to inject symbols
! @param[in] symbol_callback_data user data for the symbol callback
! (must be passed untouched)
! @return whether the call was successful
! @see clingo_control_ground()
!
! The following example implements the external function @f() returning 42.
! ~~~~~~~~~~~~~~~{.c}
! bool
! ground_callback(clingo_location_t const *location,
! char const *name,
! clingo_symbol_t const *arguments,
! size_t arguments_size,
! void *data,
! clingo_symbol_callback_t symbol_callback,
! void *symbol_callback_data) {
! if (strcmp(name, “f”) == 0 && arguments_size == 0) {
! clingo_symbol_t sym;
! clingo_symbol_create_number(42, &sym);
! return symbol_callback(&sym, 1, symbol_callback_data);
! }
! clingo_set_error(clingo_error_runtime, “function not found”);
! return false;
! }
! ~~~~~~~~~~~~~~~
! An instance of this struct has to be registered with a solver to observe ground directives as they are passed to the solver.
!
! @note This interface is closely modeled after the aspif format.
! For more information please refer to the specification of the aspif format.
!
! Not all callbacks have to be implemented and can be set to NULL if not needed.
! If one of the callbacks in the struct fails, grounding is stopped.
! If a non-recoverable clingo API call fails, a callback must return false.
! Otherwise ::clingo_error_unknown should be set and false returned.
!
! @see clingo_control_register_observer()
! Represents a source code location marking its beginnig and end.
!
! @note Not all locations refer to physical files.
! By convention, such locations use a name put in angular brackets as filename.
! The string members of a location object are internalized and valid for the duration of the process.
! Callback to customize clingo main function.
!
! @param[in] control corresponding control object
! @param[in] files files passed via command line arguments
! @param[in] size number of files
! @param[in] data user data for the callback
!
! @return whether the call was successful
! Callback to customize model printing.
!
! @param[in] model the model
! @param[in] printer the default model printer
! @param[in] printer_data user data for the printer
! @param[in] data user data for the callback
!
! @return whether the call was successful
! Struct used to specify the program parts that have to be grounded.
!
! Programs may be structured into parts, which can be grounded independently with ::clingo_control_ground.
! Program parts are mainly interesting for incremental grounding and multi-shot solving.
! For single-shot solving, program parts are not needed.
!
! @note Parts of a logic program without an explicit #program
! specification are by default put into a program called base without
! arguments.
!
! @see clingo_control_ground()
! Object to initialize a user-defined propagator before each solving step.
!
! Each @link SymbolicAtoms symbolic@endlink or @link TheoryAtoms theory atom@endlink is uniquely associated with an aspif atom in form of a positive integer (@ref ::clingo_literal_t).
! Aspif literals additionally are signed to represent default negation.
! Furthermore, there are non-zero integer solver literals (also represented using @ref ::clingo_literal_t).
! There is a surjective mapping from program atoms to solver literals.
!
! All methods called during propagation use solver literals whereas clingo_symbolic_atoms_literal() and clingo_theory_atoms_atom_literal() return program literals.
! The function clingo_propagate_init_solver_literal() can be used to map program literals or @link clingo_theory_atoms_element_condition_id() condition ids@endlink to solver literals.
! Supported check modes for propagators.
!
! Note that total checks are subject to the lock when a model is found.
! This means that information from previously found models can be used to discard assignments in check calls.
! An instance of this struct has to be registered with a solver to implement a custom propagator.
!
! Not all callbacks have to be implemented and can be set to NULL if not needed.
! @see Propagator
! Callback function called during search to notify when the search is finished or a model is ready.
!
! If a (non-recoverable) clingo API function fails in this callback, it must return false.
! In case of errors not related to clingo, set error code ::clingo_error_unknown and return false to stop solving with an error.
!
! The event is either a pointer to a model, a pointer to an int64_t* and a size_t, a pointer to two statistics objects (per step and accumulated statistics), or a solve result.
! @attention If the search is finished, the model is NULL.
!
! @param[in] event the current event.
! @param[in] data user data of the callback
! @param[out] goon can be set to false to stop solving
! @return whether the call was successful
!
! @see clingo_control_solve()
! Callback function to inject symbols.
!
! @param symbols array of symbols
! @param symbols_size size of the symbol array
! @param data user data of the callback
! @return whether the call was successful; might set one of the following error codes:
! - ::clingo_error_bad_alloc
! @see ::clingo_ground_callback_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.
! Object to iterate over symbolic atoms.
!
! Such an iterator either points to a symbolic atom within a sequence of
! symbolic atoms or to the end of the sequence.
!
! @note Iterators are valid as long as the underlying sequence is not modified.
! Operations that can change this sequence are ::clingo_control_ground(),
! ::clingo_control_cleanup(), and functions that modify the underlying
! non-ground program.
! Object to inspect symbolic atoms in a program—the relevant Herbrand base
! gringo uses to instantiate programs.
!
! @see clingo_control_symbolic_atoms()