Functions for working directly with atoms. More...

Classes
struct	atom_ref_t
	Refers to an Atom owned by another object. More...
struct	atom_t
	Represents an Atom of any type. More...

Typedefs
typedef void(*	c_atom_callback_t) (atom_ref_t atom, void *context)
	Function signature for a callback providing access to an atom.

Enumerations
enum	atom_type_t { SYMBOL , VARIABLE , EXPR , GROUNDED }
	Represents whether an atom is a Symbol, Variable, Expression, or Grounded atom. More...

Functions
atom_ref_t	atom_ref (const atom_t *atom)
	Create an atom_ref_t that points to another atom you own.
atom_ref_t	atom_ref_null (void)
	Create an atom_ref_t that points nothing.
atom_t	atom_sym (const char *name)
	Create a new Symbol atom with the specified name.
atom_t	atom_expr (atom_t *children, uintptr_t size)
	Create a new Expression atom with the specified children atoms.
atom_t	atom_expr_from_vec (struct atom_vec_t children)
	Create a new Expression atom with the children contained in an atom_vec_t
atom_t	atom_var (const char *name)
	Create a new Variable atom with the specified name.
atom_t	atom_var_parse_name (const char *name)
	Create a new Variable atom parsing full formatted name of the variable.
atom_t	atom_gnd (struct gnd_t *gnd)
atom_t	atom_bool (bool b)
atom_t	atom_int (int64_t n)
atom_t	atom_float (double f)
atom_t	atom_gnd_for_space (const struct space_t *space)
	Creates a Grounded Atom referencing a Space.
void	atom_free (atom_t atom)
	Frees an atom and all associated resources.
atom_t	atom_clone (const atom_ref_t *atom)
	Makes a "deep copy" of an atom. Useful to turn an atom_ref_t into an atom_t
bool	atom_eq (const atom_ref_t a, const atom_ref_t b)
	Checks if two atom objects represent the same conceptual atom.
bool	atoms_are_equivalent (const atom_ref_t a, const atom_ref_t b)
	Checks if two atoms are alpha equivalent.
enum atom_type_t	atom_get_metatype (const atom_ref_t *atom)
	Returns the metatype of an atom.
bool	atom_is_null (const atom_ref_t *atom)
	Returns true if the referenced atom is invalid, otherwise returns false
uintptr_t	atom_to_str (const atom_ref_t atom, char buf, uintptr_t buf_len)
	Renders a human-readable text description of an atom.
uintptr_t	atom_get_name (const atom_ref_t atom, char buf, uintptr_t buf_len)
	Renders the name of an atom into a text buffer.
void	atom_get_children (const atom_ref_t atom, c_atom_vec_callback_t callback, void context)
	Provides access to all children atoms within an expression atom.
void	atom_iterate (const atom_ref_t atom, c_atom_callback_t callback, void context)
	Performs a depth-first exhaustive iteration of an atom and all its children recursively.
atom_t	atom_get_grounded_type (const atom_ref_t *atom)
	Retrieve the grounded type of a Grounded Atom.
struct gnd_t *	atom_get_object (const atom_ref_t *atom)
	Access a pointer to an object backing a Grounded Atom.
bool	atom_is_cgrounded (const atom_ref_t *atom)
	Check if the atom refers to CGrounded object.
struct space_t	atom_get_space (const atom_ref_t *atom)
	Access the space wrapped inside a Grounded atom.

Detailed Description

Functions for working directly with atoms.

These functions are used to create, inspect, modify, and free atoms.

Typedef Documentation

◆ c_atom_callback_t

typedef void(* c_atom_callback_t) (atom_ref_t atom, void *context)

Function signature for a callback providing access to an atom.

Parameters

[in]	atom	A reference to the atom. This atom should not be modified or freed by the callback.
[in]	context	The context state pointer initially passed to the upstream function initiating the callback.

Enumeration Type Documentation

◆ atom_type_t

enum atom_type_t

Represents whether an atom is a Symbol, Variable, Expression, or Grounded atom.

Enumerator
SYMBOL	The atom is a Symbol atom.
VARIABLE	The atom is a Variable atom.
EXPR	The atom is an Expression atom.
GROUNDED	The atom is a Grounded atom.

Function Documentation

◆ atom_bool()

atom_t atom_bool ( bool b )

Parameters

[in] b boolean value

Returns: an atom_t for the Bool Grounded atom

Note: The caller must take ownership responsibility for the returned atom_t

◆ atom_clone()

atom_t atom_clone ( const atom_ref_t * atom )

Makes a "deep copy" of an atom. Useful to turn an atom_ref_t into an atom_t

Parameters

[in] atom A pointer to an atom_t or an atom_ref_t to clone

Returns: A newly created atom_t for the cloned atom

Note: The caller must take ownership responsibility for the returned atom_t

◆ atom_eq()

bool atom_eq	(	const atom_ref_t *	a,
		const atom_ref_t *	b )

Checks if two atom objects represent the same conceptual atom.

Parameters

[in]	a	A pointer to an atom_t or an atom_ref_t representing the first atom
[in]	b	A pointer to an atom_t or an atom_ref_t representing the second atom

Returns: true is the atoms are conceptually identical

◆ atom_expr()

atom_t atom_expr	(	atom_t *	children,
		uintptr_t	size )

Create a new Expression atom with the specified children atoms.

Parameters

[in]	children	A packed buffer of atom_t *, representing the children atoms
[in]	size	The number of elements in children

Returns: An atom_t for the Expression atom, containing all 'children' atoms

Note: The caller must take ownership responsibility for the returned atom_t

Warning: This function takes ownership of all children atoms, so they must not be subsequently accessed

◆ atom_expr_from_vec()

atom_t atom_expr_from_vec ( struct atom_vec_t children )

Create a new Expression atom with the children contained in an atom_vec_t

Parameters

[in] children An atom_vec_t containing all children atoms

Returns: An atom_t for the Expression atom, containing all 'children' atoms

Note: The caller must take ownership responsibility for the returned atom_t

Warning: This function takes ownership of the children vec, so it must not be subsequently accessed

◆ atom_float()

atom_t atom_float ( double f )

Parameters

[in] f float number

Returns: an atom_t for the Number Grounded atom

Note: The caller must take ownership responsibility for the returned atom_t

◆ atom_free()

void atom_free ( atom_t atom )

Frees an atom and all associated resources.

Parameters

[in] atom The atom to free

◆ atom_get_children()

void atom_get_children	(	const atom_ref_t *	atom,
		c_atom_vec_callback_t	callback,
		void *	context )

Provides access to all children atoms within an expression atom.

Parameters

[in]	atom	A pointer to an atom_t or an atom_ref_t to access
[in]	callback	A function that will be called to return access to each atom
[in]	context	A pointer to a caller-defined structure to facilitate communication with the callback function

Note: This function should only be called with Expression atoms

◆ atom_get_grounded_type()

atom_t atom_get_grounded_type ( const atom_ref_t * atom )

Retrieve the grounded type of a Grounded Atom.

Parameters

[in] atom A pointer to an atom_t or an atom_ref_t to access

Returns: The atom_t expressing the grounded type of atom

Note: Grounded Types are themselves atoms used by the MeTTa type system for customized behavior. A grounded type is different from a generic atom type, expressed by atom_type_t. Only Grounded atoms have grounded types. TODO: Where to LINK to learn more??; The caller must take ownership responsibility for the returned atom_t

◆ atom_get_metatype()

enum atom_type_t atom_get_metatype ( const atom_ref_t * atom )

Returns the metatype of an atom.

Parameters

[in] atom A pointer to an atom_t or an atom_ref_t to inspect

Returns: An atom_type_t indicating the type of atom

◆ atom_get_name()

uintptr_t atom_get_name	(	const atom_ref_t *	atom,
		char *	buf,
		uintptr_t	buf_len )

Renders the name of an atom into a text buffer.

Parameters

[in]	atom	A pointer to an atom_t or an atom_ref_t to get the name of
[out]	buf	A buffer into which the text will be written
[in]	buf_len	The maximum allocated size of buf

Returns: The length of the name string, minus the string terminator character. If return_value > buf_len + 1, then the text was not fully written and this function should be called again with a larger buffer.

◆ atom_get_object()

struct gnd_t * atom_get_object ( const atom_ref_t * atom )

Access a pointer to an object backing a Grounded Atom.

Parameters

[in] atom A pointer to an atom_t or an atom_ref_t to access

Returns: The pointer to the gnd_t orginally used to create the Grounded Atom

Note: This function is only valid for Grounded Atoms implemented via the HyperonC API

Warning: The returned pointer must not be accessed after the atom has been freed or modified elsewhere

◆ atom_get_space()

struct space_t atom_get_space ( const atom_ref_t * atom )

Access the space wrapped inside a Grounded atom.

See also: atom_gnd_for_space

Parameters

[in] atom A pointer to an atom_t or an atom_ref_t that wraps a Space

Returns: A Space handle to the space inside a grounded atom

Note: The returned space is borrowed from the atom. It must not be accessed after the atom has been freed or modified elsewhere

◆ atom_gnd()

atom_t atom_gnd ( struct gnd_t * gnd )

Parameters

[in] gnd A pointer to a buffer to back the new Grounded Atom. See the documentation of gnd_t for more info.

Returns: an atom_t for the Grounded atom

Note: The caller must take ownership responsibility for the returned atom_t

◆ atom_gnd_for_space()

atom_t atom_gnd_for_space ( const struct space_t * space )

Creates a Grounded Atom referencing a Space.

Parameters

[in] space A pointer to an space_t for accessing the space

Returns: an atom_t for the Grounded atom

Note: The caller must take ownership responsibility for the returned atom_t; This function does not consume the space and the space still must be freed with space_free()

◆ atom_int()

atom_t atom_int ( int64_t n )

Parameters

[in] n integer number

Returns: an atom_t for the Number Grounded atom

Note: The caller must take ownership responsibility for the returned atom_t

◆ atom_is_cgrounded()

bool atom_is_cgrounded ( const atom_ref_t * atom )

Check if the atom refers to CGrounded object.

Parameters

[in] atom A pointer to an atom_t or an atom_ref_t to access

Returns: True if the atom_get_object can be used on this atom without panic

◆ atom_is_null()

bool atom_is_null ( const atom_ref_t * atom )

Returns true if the referenced atom is invalid, otherwise returns false

Parameters

[in] atom A pointer to an atom_t or an atom_ref_t to inspect

Returns: true if the referenced atom is invalid, otherwise returns false

◆ atom_iterate()

void atom_iterate	(	const atom_ref_t *	atom,
		c_atom_callback_t	callback,
		void *	context )

Performs a depth-first exhaustive iteration of an atom and all its children recursively.

Parameters

[in]	atom	A pointer to an atom_t or an atom_ref_t to iterate
[in]	callback	A function that will be called to return access to each contained atom
[in]	context	A pointer to a caller-defined structure to facilitate communication with the callback function

Note: The first result returned will be the atom itself. Only Expression atoms contain deeper trees to iterate.

◆ atom_ref()

atom_ref_t atom_ref ( const atom_t * atom )

Create an atom_ref_t that points to another atom you own.

Parameters

[in] atom The atom to reference

Returns: an atom_ref_t referencing atom

Warning: The returned atom_ref_t must not be accessed after the atom it refers to has been freed, or after ownership of the original atom has been transferred to another function

Returns an atom_ref_t that points to the supplied atom.

◆ atom_ref_null()

atom_ref_t atom_ref_null ( void )

Create an atom_ref_t that points nothing.

Returns: an atom_ref_t referencing nothing

Returns an atom_ref_t that does not point to any atom

◆ atom_sym()

atom_t atom_sym ( const char * name )

Create a new Symbol atom with the specified name.

Parameters

[in] name The name of the symbol

Returns: A newly created atom_t for the Symbol Atom

Note: The caller must take ownership responsibility for the returned atom_t

Create a new Symbol atom with the specified name.

◆ atom_to_str()

uintptr_t atom_to_str	(	const atom_ref_t *	atom,
		char *	buf,
		uintptr_t	buf_len )

Renders a human-readable text description of an atom.

Parameters

[in]	atom	A pointer to an atom_t or an atom_ref_t to render
[out]	buf	A buffer into which the text will be rendered
[in]	buf_len	The maximum allocated size of buf

Returns: The length of the description string, minus the string terminator character. If return_value > buf_len + 1, then the text was not fully rendered and this function should be called again with a larger buffer.

◆ atom_var()

atom_t atom_var ( const char * name )

Create a new Variable atom with the specified name.

Parameters

[in] name The name for the newly created Variable atom

Returns: An atom_t for the Variable atom

Note: The caller must take ownership responsibility for the returned atom_t

◆ atom_var_parse_name()

atom_t atom_var_parse_name ( const char * name )

Create a new Variable atom parsing full formatted name of the variable.

Parameters

[in] name The name for the newly created Variable atom in a format <name>#id

Returns: An atom_t for the Variable atom, returns atom_t::null() when parsing fails

Note: The caller must take ownership responsibility for the returned atom_t

◆ atoms_are_equivalent()

bool atoms_are_equivalent	(	const atom_ref_t *	a,
		const atom_ref_t *	b )

Checks if two atoms are alpha equivalent.

Parameters

[in]	a	A pointer to an atom_t or an atom_ref_t representing the first atom
[in]	b	A pointer to an atom_t or an atom_ref_t representing the second atom

Returns: true if the atoms can be converted to each other by renaming variables, otherwise false

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ c_atom_callback_t

Enumeration Type Documentation

◆ atom_type_t

Function Documentation

◆ atom_bool()

◆ atom_clone()

◆ atom_eq()

◆ atom_expr()

◆ atom_expr_from_vec()

◆ atom_float()

◆ atom_free()

◆ atom_get_children()

◆ atom_get_grounded_type()

◆ atom_get_metatype()

◆ atom_get_name()

◆ atom_get_object()

◆ atom_get_space()

◆ atom_gnd()

◆ atom_gnd_for_space()

◆ atom_int()

◆ atom_is_cgrounded()

◆ atom_is_null()

◆ atom_iterate()

◆ atom_ref()

◆ atom_ref_null()

◆ atom_sym()

◆ atom_to_str()

◆ atom_var()

◆ atom_var_parse_name()

◆ atoms_are_equivalent()