Functions for accessing a space directly. More...

Classes
struct	space_t
	A Space handle, providing access to a Space in which atoms may exist in relation to other atoms. More...

Functions
struct space_t	space_new (const struct space_api_t api, void payload)
	Creates a new Space, backed by an implementation in C.
void	space_free (struct space_t space)
	Frees a space_t handle.
struct space_t	space_clone_handle (const struct space_t *space)
	Creates a new space_t handle that refers to the same underlying space as another space_t
bool	space_eq (const struct space_t a, const struct space_t b)
	Checks if two space_t handles refer to the same underlying Space.
void *	space_get_payload (struct space_t *space)
	Access the payload object belonging to a space implemented in C.
void	space_add (struct space_t *space, atom_t atom)
	Adds an atom to the Space.
bool	space_remove (struct space_t space, const atom_ref_t atom)
	Removes a specific atom from the Space.
bool	space_replace (struct space_t space, const atom_ref_t from, atom_t to)
	Replaces an Atom in the Space with another Atom.
struct bindings_set_t	space_query (const struct space_t space, const atom_ref_t pattern)
	Queries a Space for atoms matching a pattern.
void	space_subst (const struct space_t space, const atom_ref_t pattern, const atom_ref_t templ, c_atom_vec_callback_t callback, void context)
	Substitutes all Atoms matching a pattern with Atoms constructed from a template.
intptr_t	space_atom_count (const struct space_t *space)
	Returns the number of top-level atoms in a Space, if it can be readily determined.
bool	space_iterate (const struct space_t space, c_atom_callback_t callback, void context)
	Iterates all top-level Atoms in a Space, if that is possible.
struct space_t	space_new_grounding_space (void)
	Creates a new Space, backed by a GroundSpace.

Detailed Description

Functions for accessing a space directly.

These functions are used to manage spaces, including to create new spaces, free spaces, manipulate the atoms in a space as well as to query a space directly.

Function Documentation

◆ space_add()

void space_add	(	struct space_t *	space,
		atom_t	atom )

Adds an atom to the Space.

Parameters

[in]	space	A pointer to the space_t handle to access
[in]	atom	An atom_t representing the Atom to add

Warning: This function takes ownership of the supplied atom, and it should not be freed or accessed after it has been provided to this function

◆ space_atom_count()

intptr_t space_atom_count ( const struct space_t * space )

Returns the number of top-level atoms in a Space, if it can be readily determined.

Parameters

[in] space A pointer to the space_t handle to access

Returns: The number of top-level atoms in the Space, or -1 for spaces in which it is impossible or impractical to determine the number of atoms

◆ space_clone_handle()

struct space_t space_clone_handle ( const struct space_t * space )

Creates a new space_t handle that refers to the same underlying space as another space_t

Parameters

[in] space A pointer to the space_t handle to clone

Returns: A newly created space_t handle, providing access to the same underlying Space

Note: Each space_t is an independent object and must be individually freed, but both space_t objects reference the same underlying space, which is only deallocated when all references to it have been freed.; The caller must take ownership responsibility for the returned space_t, and free it with space_free()

◆ space_eq()

bool space_eq	(	const struct space_t *	a,
		const struct space_t *	b )

Checks if two space_t handles refer to the same underlying Space.

Parameters

[in]	a	A pointer to the first space_t
[in]	b	A pointer to the second space_t

Returns: true is the underlying Space is the same for both space_t objects, and false otherwise

◆ space_free()

void space_free ( struct space_t space )

Frees a space_t handle.

Parameters

[in] space The handle to free

Note: The underlying Space may be deallocated if all handles that refer to it have been freed, otherwise the Space itself won't be freed

◆ space_get_payload()

void * space_get_payload ( struct space_t * space )

Access the payload object belonging to a space implemented in C.

Parameters

[in] space A pointer to the space_t handle to access

Returns: The pointer to the payload object orginally used to create the Space

Note: This function is only valid for Spaces implemented via the HyperonC API; This API is likely to change in the future to implement multi-threading as the space's payload object must not be modified while other operations can access the space

Warning: The returned payload ptr must not be freed, nor may it be accessed after the space has been freed or modified

◆ space_iterate()

bool space_iterate	(	const struct space_t *	space,
		c_atom_callback_t	callback,
		void *	context )

Iterates all top-level Atoms in a Space, if that is possible.

Parameters

[in]	space	A pointer to the space_t handle to access
[in]	callback	A function that will be called for each top-level Atom in the Space
[in]	context	A pointer to a caller-defined structure to facilitate communication with the callback function

Returns: true if the space was sucessfully iterated, or false if the space does not support iteration

◆ space_new()

struct space_t space_new	(	const struct space_api_t *	api,
		void *	payload )

Creates a new Space, backed by an implementation in C.

Parameters

[in]	api	A pointer to the table of functions that implement the Space's behavior
[in]	payload	A pointer to a buffer to back the new Space

Returns: A newly created space_t handle, to access the Space

Warning: This function takes ownership of the payload buffer, and it should not be freed or accessed after it has been provided to this function

Note: The caller must take ownership responsibility for the returned space_t, and free it with space_free()

◆ space_new_grounding_space()

struct space_t space_new_grounding_space ( void )

Creates a new Space, backed by a GroundSpace.

Returns: a space_t handle to the newly created Grounding Space

Note: The caller takes ownership responsibility for the returned space_t, and it must be freed with space_free()

◆ space_query()

struct bindings_set_t space_query	(	const struct space_t *	space,
		const atom_ref_t *	pattern )

Queries a Space for atoms matching a pattern.

Parameters

[in]	space	A pointer to the space_t handle to access
[in]	pattern	A pointer to an atom_t or atom_ref_t to specify the pattern to match within the Space

Returns: A bindings_set_t representing all possible results of the match

Note: The caller must take ownership responsibility for the returned bindings_set_t, and free it with bindings_set_free()

◆ space_remove()

bool space_remove	(	struct space_t *	space,
		const atom_ref_t *	atom )

Removes a specific atom from the Space.

Parameters

[in]	space	A pointer to the space_t handle to access
[in]	atom	A pointer to an atom_t or atom_ref_t to specifying the atom to remove from the Space

Returns: true if the atom was found and removed from the Space, false otherwise

◆ space_replace()

bool space_replace	(	struct space_t *	space,
		const atom_ref_t *	from,
		atom_t	to )

Replaces an Atom in the Space with another Atom.

Parameters

[in]	space	A pointer to the space_t handle to access
[in]	from	A pointer to an atom_t or atom_ref_t to specify the atom to replace
[in]	to	An atom_t to provide a new Atom, to replace the from atom in the Space

Returns: true if an Atom was replaced in the Space, false otherwise

Note: The to atom will only be added to the Space if the from atom is found. Regardless, this functino will take ownership of the to atom.

Warning: This function takes ownership of the to atom, and it should not be freed or accessed after it has been provided to this function

◆ space_subst()

void space_subst	(	const struct space_t *	space,
		const atom_ref_t *	pattern,
		const atom_ref_t *	templ,
		c_atom_vec_callback_t	callback,
		void *	context )

Substitutes all Atoms matching a pattern with Atoms constructed from a template.

Parameters

[in]	space	A pointer to the space_t handle to access
[in]	pattern	A pointer to an atom_t or atom_ref_t to match Atom(s) in the Space
[in]	templ	A pointer to an atom_t or atom_ref_t to specify a template from which to construct the new atoms
[in]	callback	A function that will be called to provide access to a vec of newly created atoms
[in]	context	A pointer to a caller-defined structure to facilitate communication with the callback function

Classes

Functions

Detailed Description

Function Documentation

◆ space_add()

◆ space_atom_count()

◆ space_clone_handle()

◆ space_eq()

◆ space_free()

◆ space_get_payload()

◆ space_iterate()

◆ space_new()

◆ space_new_grounding_space()

◆ space_query()

◆ space_remove()

◆ space_replace()

◆ space_subst()