Implementation of the C API for Sista. More...

#include <sista/api.h>
#include <sista/sista.hpp>
#include <stdexcept>

Include dependency graph for api.cpp:

Functions
FieldHandler_t	sista_createField (size_t width, size_t height)
	Creates a Field with the specified width and height.

void	sista_destroyField (FieldHandler_t field)
	Deallocates the Field from memory.

SwappableFieldHandler_t	sista_createSwappableField (size_t width, size_t height)
	Creates a SwappableField with the specified width and height.

void	sista_destroySwappableField (SwappableFieldHandler_t field)
	Deallocates the SwappableField from memory.

void	sista_printField (FieldHandler_t field, char border)
	Prints the specified Field with a given border.

void	sista_printSwappableField (SwappableFieldHandler_t field, char border)
	Prints the specified Field with a given border.

void	sista_resetAnsi ()
	Resets ANSI settings to default.

void	sista_setForegroundColor (enum sista_ForegroundColor color)
	Sets the foreground color using a predefined color.

void	sista_setBackgroundColor (enum sista_BackgroundColor color)
	Sets the background color using a predefined color.

void	sista_setAttribute (enum sista_Attribute attribute)
	Sets a text attribute.

void	sista_resetAttribute (enum sista_Attribute attribute)
	Resets a text attribute.

void	sista_setForegroundColorRGB (const struct sista_RGBColor *color)
	Sets the foreground color using an RGB color.

void	sista_setBackgroundColorRGB (const struct sista_RGBColor *color)
	Sets the background color using an RGB color.

ANSISettingsHandler_t	sista_createANSISettings (enum sista_ForegroundColor fgColor, enum sista_BackgroundColor bgColor, enum sista_Attribute attribute)
	Creates an ANSISettings object.

ANSISettingsHandler_t	sista_createANSISettingsRGB (struct sista_RGBColor fgColor, struct sista_RGBColor bgColor, sista_Attribute attribute)

void	sista_destroyANSISettings (ANSISettingsHandler_t settings)
	Deallocates the ANSISettings from memory.

void	sista_applyANSISettings (ANSISettingsHandler_t settings)
	Applies the ANSI settings to the terminal.

BorderHandler_t	sista_createBorder (char symbol, ANSISettingsHandler_t settings)
	Creates a Border object.

void	sista_destroyBorder (BorderHandler_t border)
	Deallocates the Border from memory.

void	sista_printFieldWithBorder (FieldHandler_t field, BorderHandler_t border)
	Prints the field with the specified border.

void	sista_printSwappableFieldWithBorder (SwappableFieldHandler_t field, BorderHandler_t border)
	Prints the field with the specified border.

PawnHandler_t	sista_createPawnInSwappableField (SwappableFieldHandler_t field, char symbol, ANSISettingsHandler_t settings, struct sista_Coordinates position)
	Creates a Pawn object in a given field.

PawnHandler_t	sista_createPawnInField (FieldHandler_t field, char symbol, ANSISettingsHandler_t settings, struct sista_Coordinates position)
	Creates a Pawn object in a given field.

int	sista_movePawn (FieldHandler_t field, PawnHandler_t pawn, struct sista_Coordinates destination)
	Moves the pawn to a new position.

int	sista_addPawnToSwap (SwappableFieldHandler_t field, PawnHandler_t pawn, struct sista_Coordinates destination)
	Adds the Pawn to a list of pawns to be moved ("swapped") later.

int	sista_applySwaps (SwappableFieldHandler_t field)
	Executes all pending pawn swaps.

Detailed Description

Implementation of the C API for Sista.

This file contains the implementation of the C API functions declared in api.h. It provides a C-compatible interface to interact with the Sista library, allowing for operations on SwappableField objects.

Author: FLAK-ZOSO

Date: 2025

Version: 3.0.0

Copyright: GNU General Public License v3.0

Function Documentation

◆ sista_addPawnToSwap()

int sista_addPawnToSwap	(	SwappableFieldHandler_t	field,
		PawnHandler_t	pawn,
		struct sista_Coordinates	destination
	)

Adds the Pawn to a list of pawns to be moved ("swapped") later.

Parameters

field	The SwappableField containing the Pawn.
pawn	The Pawn to add to the swap list.
destination	The destination coordinates.

Returns: Status code

This function adds the specified Pawn to a list of pawns that will be moved (swapped) when sista_executeSwaps is called. The pawn will be moved to the specified destination coordinates.

Return values

0	If the pawn was successfully added to the swap list.
1	If adding the pawn to the swap list failed for any other reason.
2	If the destination is out of bounds.
3	If the destination is occupied by another pawn.
4	If the field is a nullptr.
5	If the pawn is a nullptr.

See also: sista::SwappableField::addPawnToSwap

◆ sista_applyANSISettings()

void sista_applyANSISettings ( ANSISettingsHandler_t settings )

Applies the ANSI settings to the terminal.

Parameters

settings The ANSISettings to apply.

This function applies the specified ANSI settings to the terminal by outputting the corresponding ANSI escape codes to standard output.

See also: sista::ANSISettings::apply

◆ sista_applySwaps()

int sista_applySwaps ( SwappableFieldHandler_t field )

Executes all pending pawn swaps.

Parameters

field The SwappableField containing the pawns to swap.

Returns: Status code

This function executes all pending pawn swaps that have been added using sista_addPawnToSwap. It attempts to move each pawn to its specified destination, handling any conflicts or errors that arise.

Note: The swaps that cannot be applied (due to more than one pawn trying to move to the same destination, generally) are skipped.

Todo:: In future versions, the function may return a list of the swaps that could not be applied.

Return values

0	If all possible (read note) swaps were successful.
1	If executing the swaps failed for any other reason.

See also: sista::SwappableField::applySwaps

◆ sista_createANSISettings()

ANSISettingsHandler_t sista_createANSISettings	(	enum	sista_ForegroundColor,
		enum	sista_BackgroundColor,
		enum	sista_Attribute
	)

Creates an ANSISettings object.

Parameters

fgColor	The foreground color (predefined).
bgColor	The background color (predefined).
attribute	The text attribute to apply.

Returns: A handler to the created ANSISettings object.

This function allocates and initializes a new ANSISettings object. It returns a pointer that can be used to reference the ANSISettings in subsequent API calls.

Return values

NULL	If memory allocation fails.

Warning: The caller is responsible for managing the lifetime of the returned ANSISettings object, including deallocation if necessary.

See also: sista::ANSISettings; sista_destroyANSISettings

◆ sista_createANSISettingsRGB()

ANSISettingsHandler_t sista_createANSISettingsRGB	(	struct sista_RGBColor	fgColor,
		struct sista_RGBColor	bgColor,
		sista_Attribute	attribute
	)

◆ sista_createBorder()

BorderHandler_t sista_createBorder	(	char	symbol,
		ANSISettingsHandler_t	settings
	)

Creates a Border object.

Parameters

symbol	The character symbol for the border brick.
settings	The ANSISettings to apply to the border brick.

Returns: A handler to the created Border object.

This function allocates and initializes a new Border object with the specified symbol and ANSI settings. It returns a pointer that can be used to reference the Border in subsequent API calls.

Return values

NULL	If memory allocation fails.

Warning: The caller is responsible for managing the lifetime of the returned Border object, including deallocation if necessary.

See also: sista::Border; sista_destroyBorder

◆ sista_createField()

FieldHandler_t sista_createField	(	size_t	width,
		size_t	height
	)

Creates a Field with the specified width and height.

Parameters

width	The width of the Field.
height	The height of the Field.

Returns: A handler to the created Field.

This function allocates and initializes a new Field object with the given dimensions. It returns a pointer that can be used to reference the Field in subsequent API calls.

Return values

NULL	If memory allocation fails.

Warning: The caller is responsible for managing the lifetime of the returned Field object, including deallocation if necessary.

See also: Field

◆ sista_createPawnInField()

PawnHandler_t sista_createPawnInField	(	FieldHandler_t	field,
		char	symbol,
		ANSISettingsHandler_t	settings,
		struct sista_Coordinates	position
	)

Creates a Pawn object in a given field.

Parameters

field	The Field to add the pawn to.
symbol	The character symbol for the pawn.
settings	The ANSISettings to apply to the pawn.
position	The initial position of the pawn.

Returns: A handler to the created Pawn object.

This function allocates and initializes a new Pawn object with the specified symbol, ANSI settings, and initial position. It returns a pointer that can be used to reference the Pawn in subsequent API calls.

Return values

NULL	If memory allocation fails.

Warning: Unlike with other objects, the caller is NOT responsible for managing the lifetime of the returned Pawn object. Pawns are managed by the Field they are added to, and will be deallocated when the Field is destroyed.

See also: sista::Pawn; sista_destroyPawn

◆ sista_createPawnInSwappableField()

PawnHandler_t sista_createPawnInSwappableField	(	SwappableFieldHandler_t	field,
		char	symbol,
		ANSISettingsHandler_t	settings,
		struct sista_Coordinates	position
	)

Creates a Pawn object in a given field.

Parameters

field	The SwappableField to add the pawn to.
symbol	The character symbol for the pawn.
settings	The ANSISettings to apply to the pawn.
position	The initial position of the pawn.

Returns: A handler to the created Pawn object.

This function allocates and initializes a new Pawn object with the specified symbol, ANSI settings, and initial position. It returns a pointer that can be used to reference the Pawn in subsequent API calls.

Return values

NULL	If memory allocation fails.

Warning: Unlike with other objects, the caller is NOT responsible for managing the lifetime of the returned Pawn object. Pawns are managed by the SwappableField they are added to, and will be deallocated when the SwappableField is destroyed.

See also: sista::Pawn; sista_destroyPawn

◆ sista_createSwappableField()

SwappableFieldHandler_t sista_createSwappableField	(	size_t	width,
		size_t	height
	)

Creates a SwappableField with the specified width and height.

Parameters

width	The width of the SwappableField.
height	The height of the SwappableField.

Returns: A handler to the created SwappableField.

This function allocates and initializes a new SwappableField object with the given dimensions. It returns a pointer that can be used to reference the SwappableField in subsequent API calls.

Return values

NULL	If memory allocation fails.

Warning: The caller is responsible for managing the lifetime of the returned SwappableField object, including deallocation if necessary.

See also: SwappableField

◆ sista_destroyANSISettings()

void sista_destroyANSISettings ( ANSISettingsHandler_t settings )

Deallocates the ANSISettings from memory.

Parameters

settings The ANSISettings to delete.

This function deallocates the ANSISettings from memory through the opaque handler pointing to it.

See also: sista::ANSISettings; sista_createANSISettings

◆ sista_destroyBorder()

void sista_destroyBorder ( BorderHandler_t border )

Deallocates the Border from memory.

Parameters

border The Border to delete.

This function deallocates the Border from memory through the opaque handler pointing to it.

See also: sista::Border; sista_createBorder

◆ sista_destroyField()

void sista_destroyField ( FieldHandler_t field )

Deallocates the Field from memory.

Parameters

field The Field to delete

This function deallocates the Field from memory through the opaque handler pointing to it.

See also: Field

◆ sista_destroySwappableField()

void sista_destroySwappableField ( SwappableFieldHandler_t field )

Deallocates the SwappableField from memory.

Parameters

field The SwappableField to delete

This function deallocates the SwappableField from memory through the opaque handler pointing to it.

See also: SwappableField

◆ sista_movePawn()

int sista_movePawn	(	FieldHandler_t	field,
		PawnHandler_t	pawn,
		struct sista_Coordinates	destination
	)

Moves the pawn to a new position.

Parameters

field	The Field containing the Pawn.
pawn	The Pawn to move.
destination	The destination coordinates.

Returns: Status code

Return values

0	If the move was successful.
1	If the move failed for any other reason.
2	If the destination is out of bounds.
3	If the destination is occupied by another pawn.
4	If the field is a nullptr.
5	If the pawn is a nullptr.

See also: sista::Field::movePawn

◆ sista_printField()

void sista_printField	(	FieldHandler_t	field,
		char	border
	)

Prints the specified Field with a given border.

Parameters

field	The Field.
border	The border character to use.

This function prints the entire field to the terminal, using the specified character as the border around the field.

See also: Field; Border

◆ sista_printFieldWithBorder()

void sista_printFieldWithBorder	(	FieldHandler_t	field,
		BorderHandler_t	border
	)

Prints the field with the specified border.

Parameters

field	The Field to print.
border	The Border to print.

This function prints the entire field to the terminal, using the specified Border object to draw the border around the field.

See also: sista::Border::print; sista::Field::print

◆ sista_printSwappableField()

void sista_printSwappableField	(	SwappableFieldHandler_t	field,
		char	border
	)

Prints the specified Field with a given border.

Parameters

field	The SwappableField.
border	The border character to use.

This function prints the entire field to the terminal, using the specified character as the border around the field.

See also: Field; Border

◆ sista_printSwappableFieldWithBorder()

void sista_printSwappableFieldWithBorder	(	SwappableFieldHandler_t	field,
		BorderHandler_t	border
	)

Prints the field with the specified border.

Parameters

field	The SwappableField to print.
border	The Border to print.

This function prints the entire field to the terminal, using the specified Border object to draw the border around the field.

See also: sista::Border::print; sista::Field::print

◆ sista_resetAnsi()

void sista_resetAnsi ( )

Resets ANSI settings to default.

This function resets the terminal's ANSI settings, including colors and attributes, to their default values.

See also: sista::resetAnsi

◆ sista_resetAttribute()

void sista_resetAttribute ( enum sista_Attribute )

Resets a text attribute.

Parameters

attribute The text attribute to reset.

This function resets a text attribute, such as bold or underline, specified in the sista_Attribute enumeration. It outputs the corresponding ANSI escape code to standard output.

See also: sista_Attribute; sista::resetAttribute

◆ sista_setAttribute()

void sista_setAttribute ( enum sista_Attribute )

Sets a text attribute.

Parameters

attribute The text attribute to set.

This function sets a text attribute, such as bold or underline, specified in the sista_Attribute enumeration. It outputs the corresponding ANSI escape code to standard output.

See also: sista_Attribute; sista::setAttribute

◆ sista_setBackgroundColor()

void sista_setBackgroundColor ( enum sista_BackgroundColor )

Sets the background color using a predefined color.

Parameters

color The predefined background color to set.

This function sets the terminal's background color to one of the predefined colors specified in the sista_BackgroundColor enumeration. It outputs the corresponding ANSI escape code to standard output.

See also: sista_BackgroundColor; sista::setBackgroundColor

◆ sista_setBackgroundColorRGB()

void sista_setBackgroundColorRGB ( const struct sista_RGBColor * color )

Sets the background color using an RGB color.

Parameters

color A pointer to a sista_RGBColor struct defining the color.

This function sets the terminal's background color using the RGB components specified in the provided sista_RGBColor struct. It outputs the corresponding ANSI escape code to standard output.

Note: The function takes no effect if the pointer is nullptr.

See also: sista_RGBColor; sista::setBackgroundColor

◆ sista_setForegroundColor()

void sista_setForegroundColor ( enum sista_ForegroundColor )

Sets the foreground color using a predefined color.

Parameters

color The predefined foreground color to set.

This function sets the terminal's foreground color to one of the predefined colors specified in the sista_ForegroundColor enumeration. It outputs the corresponding ANSI escape code to standard output.

See also: sista_ForegroundColor; sista::setForegroundColor

◆ sista_setForegroundColorRGB()

void sista_setForegroundColorRGB ( const struct sista_RGBColor * color )

Sets the foreground color using an RGB color.

Parameters

color A pointer to a sista_RGBColor struct defining the color.

This function sets the terminal's foreground color using the RGB components specified in the provided sista_RGBColor struct. It outputs the corresponding ANSI escape code to standard output.

Note: The function takes no effect if the pointer is nullptr.

See also: sista_RGBColor; sista::setForegroundColor

Functions

Detailed Description

Function Documentation

◆ sista_addPawnToSwap()

◆ sista_applyANSISettings()

◆ sista_applySwaps()

◆ sista_createANSISettings()

◆ sista_createANSISettingsRGB()

◆ sista_createBorder()

◆ sista_createField()

◆ sista_createPawnInField()

◆ sista_createPawnInSwappableField()

◆ sista_createSwappableField()

◆ sista_destroyANSISettings()

◆ sista_destroyBorder()

◆ sista_destroyField()

◆ sista_destroySwappableField()

◆ sista_movePawn()

◆ sista_printField()

◆ sista_printFieldWithBorder()

◆ sista_printSwappableField()

◆ sista_printSwappableFieldWithBorder()

◆ sista_resetAnsi()

◆ sista_resetAttribute()

◆ sista_setAttribute()

◆ sista_setBackgroundColor()

◆ sista_setBackgroundColorRGB()

◆ sista_setForegroundColor()

◆ sista_setForegroundColorRGB()