libtguy.h File Reference

#include <stddef.h>
#include <stdio.h>

Go to the source code of this file.

Classes
struct	TGStrView

Macros
#define	TGUY_VER_MAJOR   0
#define	TGUY_VER_MINOR   18
#define	TGUY_VER_PATCH   1
#define	LIBTGUY_EXPORT
#define	TGSTRV(str)   ((TGStrView){str, sizeof(str) - 1})

Typedefs
typedef struct TrashGuyState	TrashGuyState

Functions
LIBTGUY_EXPORT TrashGuyState *	tguy_from_arr_ex_2 (const TGStrView *arr, size_t len, unsigned spacing, const TGStrView *sprite_space, const TGStrView *sprite_can, const TGStrView *sprite_right, const TGStrView *sprite_left, int preserve_strings)
LIBTGUY_EXPORT TrashGuyState *	tguy_from_arr_ex (const TGStrView *arr, size_t len, unsigned spacing, const TGStrView *sprite_space, const TGStrView *sprite_can, const TGStrView *sprite_right, const TGStrView *sprite_left)
LIBTGUY_EXPORT TrashGuyState *	tguy_from_arr (const TGStrView *arr, size_t len, unsigned spacing)
LIBTGUY_EXPORT TrashGuyState *	tguy_from_utf8_ex (const char *string, size_t len, unsigned spacing, const char *sprite_space, size_t sprite_space_len, const char *sprite_can, size_t sprite_can_len, const char *sprite_right, size_t sprite_right_len, const char *sprite_left, size_t sprite_left_len)
LIBTGUY_EXPORT TrashGuyState *	tguy_from_utf8 (const char string[], size_t len, unsigned spacing)
LIBTGUY_EXPORT TrashGuyState *	tguy_from_cstr_arr_ex (const char *const arr[], size_t len, unsigned spacing, const char *sprite_space, size_t sprite_space_len, const char *sprite_can, size_t sprite_can_len, const char *sprite_right, size_t sprite_right_len, const char *sprite_left, size_t sprite_left_len)
LIBTGUY_EXPORT TrashGuyState *	tguy_from_cstr_arr (const char *const arr[], size_t len, unsigned spacing)
LIBTGUY_EXPORT void	tguy_free (TrashGuyState *st)
LIBTGUY_EXPORT unsigned	tguy_set_frame (TrashGuyState *st, unsigned frame)
LIBTGUY_EXPORT unsigned	tguy_set_pos (TrashGuyState *st, unsigned sprite_pos, unsigned facing_right, unsigned element_index)
LIBTGUY_EXPORT void	tguy_get_frame_state (const TrashGuyState *st, unsigned *frame, unsigned *sprite_pos, unsigned *facing_right, unsigned *element_index)
LIBTGUY_EXPORT unsigned	tguy_get_frames_count (const TrashGuyState *st)
LIBTGUY_EXPORT size_t	tguy_fprint (const TrashGuyState *st, FILE *fp)
LIBTGUY_EXPORT size_t	tguy_print (const TrashGuyState *st)
LIBTGUY_EXPORT size_t	tguy_sprint (const TrashGuyState *st, char buf[])
LIBTGUY_EXPORT size_t	tguy_get_bsize (TrashGuyState *st)
LIBTGUY_EXPORT const TGStrView *	tguy_get_arr (const TrashGuyState *st, size_t *len)
LIBTGUY_EXPORT const char *	tguy_get_string (TrashGuyState *restrict st, size_t *len)
LIBTGUY_EXPORT unsigned	tguy_get_first_frame_for_element (const TrashGuyState *st, unsigned element_index)
LIBTGUY_EXPORT unsigned	tguy_get_version (void)

Macro Definition Documentation

TGSTRV

#define TGSTRV

(

str

)

((TGStrView){str, sizeof(str) - 1})

Creates TGStrView from compile-time string

Parameters

str	constant string array or literal

Typedef Documentation

TrashGuyState

TrashGuyState

Anonymous struct typedef containing TrashGuy information

Function Documentation

tguy_fprint()

LIBTGUY_EXPORT size_t tguy_fprint	(	const TrashGuyState *	st,
		FILE *	fp
	)

Writes currently set TrashGuy frame to fp without newline

Parameters

st	Valid TrashGuyState with frame set
fp	Valid FILE

Returns

Number of bytes written

tguy_free()

LIBTGUY_EXPORT void tguy_free

(

TrashGuyState *

st

)

Deallocates memory used by a TrashGuyState, does nothing if pointer is NULL

Parameters

st	Valid TrashGuyState * or NULL

tguy_from_arr()

LIBTGUY_EXPORT TrashGuyState * tguy_from_arr	(	const TGStrView *	arr,
		size_t	len,
		unsigned	spacing
	)

Creates new TrashGuysState from array of TGStrView using default sprites

Parameters

arr	Array of string containers, each one is a separate element for TrashGuy to dump to the bin
len	Number of string containers
spacing	Number of space sprites to be placed between the TrashGuy sprite and fist element initially

Returns

TrashGuyState * or NULL on allocation failure, must be freed with tguy_free() after use

tguy_from_arr_ex()

LIBTGUY_EXPORT TrashGuyState * tguy_from_arr_ex	(	const TGStrView *	arr,
		size_t	len,
		unsigned	spacing,
		const TGStrView *	sprite_space,
		const TGStrView *	sprite_can,
		const TGStrView *	sprite_right,
		const TGStrView *	sprite_left
	)

Creates new TrashGuysState from array of TGStrView. If pointer to sprite is NULL then function will use default one

Parameters

arr	Array of string containers, each one is a separate element for TrashGuy to dump to the bin
len	Number of string containers
spacing	Number of space sprites to be placed between the TrashGuy sprite and fist element initially
sprite_space	Sprite to be used as empty space
sprite_can	Sprite to be used as trash can
sprite_right	Sprite to be used when TrashGuy moves right
sprite_left	Sprite to be used when TrashGuy moves left

Returns

TrashGuyState * or NULL on allocation failure, must be freed with tguy_free() after use

tguy_from_arr_ex_2()

LIBTGUY_EXPORT TrashGuyState * tguy_from_arr_ex_2	(	const TGStrView *	arr,
		size_t	len,
		unsigned	spacing,
		const TGStrView *	sprite_space,
		const TGStrView *	sprite_can,
		const TGStrView *	sprite_right,
		const TGStrView *	sprite_left,
		int	preserve_strings
	)

Creates new TrashGuysState from array of TGStrView. If pointer to sprite is NULL then function will use default one

Parameters

arr	Array of string containers, each one is a separate element for TrashGuy to dump to the bin
len	Number of string containers
spacing	Number of space sprites to be placed between the TrashGuy sprite and fist element initially
sprite_space	Sprite to be used as empty space
sprite_can	Sprite to be used as trash can
sprite_right	Sprite to be used when TrashGuy moves right
sprite_left	Sprite to be used when TrashGuy moves left
preserve_strings	If set to false function won't make a copy of all strings in passed TGStrView and will instead rely on caller to preserve those strings until tguy_free is called

Returns

TrashGuyState * or NULL on allocation failure, must be freed with tguy_free() after use

tguy_from_cstr_arr()

LIBTGUY_EXPORT TrashGuyState * tguy_from_cstr_arr	(	const char *const	arr[],
		size_t	len,
		unsigned	spacing
	)

Parameters

arr	Array of nul-terminated C strings, in case of NULL, acts like empty array and len is set as 0
len	Number of elements in array
spacing	Number of space sprites to be placed between the TrashGuy sprite and fist element initially

Returns

tguy_from_cstr_arr_ex()

LIBTGUY_EXPORT TrashGuyState * tguy_from_cstr_arr_ex	(	const char *const	arr[],
		size_t	len,
		unsigned	spacing,
		const char *	sprite_space,
		size_t	sprite_space_len,
		const char *	sprite_can,
		size_t	sprite_can_len,
		const char *	sprite_right,
		size_t	sprite_right_len,
		const char *	sprite_left,
		size_t	sprite_left_len
	)

Parameters

arr	Array of nul-terminated C strings, in case of NULL, acts like empty array and len is set as 0
len	Number of elements in array
spacing	Number of space sprites to be placed between the TrashGuy sprite and fist element initially
sprite_space	Sprite to be used as empty space
sprite_space_len	Number of bytes for sprite_space
sprite_can	Sprite to be used as trash can
sprite_can_len	Number of bytes for sprite_can
sprite_right	Sprite to be used when TrashGuy moves right
sprite_right_len	Number of bytes for sprite_right
sprite_left	Sprite to be used when TrashGuy moves left
sprite_left_len	Number of bytes for sprite_left

Returns

tguy_from_utf8()

LIBTGUY_EXPORT TrashGuyState * tguy_from_utf8	(	const char	string[],
		size_t	len,
		unsigned	spacing
	)

Creates new TrashGuysState from valid utf-8 string, where each grapheme cluster is made into an element to dump

Parameters

string	Valid utf-8 string, in case of NULL, acts like empty string and len is set as 0
len	Number of bytes string has, if -1, then strlen will be used
spacing	Number of space sprites to be placed between the TrashGuy sprite and fist element initially

Returns

TrashGuyState * or NULL on allocation failure, must be freed with tguy_free() after use

tguy_from_utf8_ex()

LIBTGUY_EXPORT TrashGuyState * tguy_from_utf8_ex	(	const char *	string,
		size_t	len,
		unsigned	spacing,
		const char *	sprite_space,
		size_t	sprite_space_len,
		const char *	sprite_can,
		size_t	sprite_can_len,
		const char *	sprite_right,
		size_t	sprite_right_len,
		const char *	sprite_left,
		size_t	sprite_left_len
	)

Creates new TrashGuysState from a utf-8 string, where each grapheme cluster is made into an element to dump

Parameters

string	Valid utf-8 string, in case of NULL, acts like empty string and len is set as 0
len	Number of bytes string has, if -1, then strlen will be used
spacing	Number of space sprites to be placed between the TrashGuy sprite and fist element initially
sprite_space	Sprite to be used as empty space
sprite_space_len	Number of bytes for sprite_space
sprite_can	Sprite to be used as trash can
sprite_can_len	Number of bytes for sprite_can
sprite_right	Sprite to be used when TrashGuy moves right
sprite_right_len	Number of bytes for sprite_right
sprite_left	Sprite to be used when TrashGuy moves left
sprite_left_len	Number of bytes for sprite_left

Returns

TrashGuyState * or NULL on allocation failure, must be freed with tguy_free() after use

tguy_get_arr()

LIBTGUY_EXPORT const TGStrView * tguy_get_arr	(	const TrashGuyState *	st,
		size_t *	len
	)

Returns read-only array view of current TrashGuy frame: TGStrView[]{ {"t",1}, {"e",1}, {"ї",2}, {"s",1}, {"t",1}, {NULL,0} }

Parameters

st	Valid TrashGuyState with frame set
[out,optional]	len Length of the returned array, excluding NULL terminator

Returns

Array of const TGStrView, terminated with TGStrView.str == NULL

tguy_get_bsize()

LIBTGUY_EXPORT size_t tguy_get_bsize

(

TrashGuyState *

st

)

Get buffer size large enough to hold one frame including nul terminator

Parameters

st	Valid TrashGuyState

Returns

Needed buffer size in bytes, including nul terminator

If bsize is not set, then iterate over possible arena layout and compute buf size big enough to keep any frame plus nul terminator

tguy_get_first_frame_for_element()

LIBTGUY_EXPORT unsigned tguy_get_first_frame_for_element	(	const TrashGuyState *	st,
		unsigned	element_index
	)

Returns first frame for when certain element is being processed. You can get a range of frames [first,last] for when certain element is processed by calling first = tguy_get_first_frame_for_element(element_index) last = tguy_get_first_frame_for_element(element_index + 1) - 1

Parameters

st	Valid TrashGuyState
element_index	Element index, in tguy_from_utf8("teїst",-1,4), 't' would be index 0, 'ї' would be index 2, etc.

Returns

tguy_get_frame_state()

LIBTGUY_EXPORT void tguy_get_frame_state	(	const TrashGuyState *	st,
		unsigned *	frame,
		unsigned *	sprite_pos,
		unsigned *	facing_right,
		unsigned *	element_index
	)

Parameters

st	Valid TrashGuyState *
[out,optional]	frame Current frame, 0 <= frame < tguy_get_frames_count()
[out,optional]	sprite_pos Position within the arena, 0 < sprite_pos < tguy_get_arr().len
[out,optional]	facing_right Whether sprite is facing right
[out,optional]	element_index Index of the element that's currently being processed, see tguy_get_first_frame_for_element()

tguy_get_frames_count()

LIBTGUY_EXPORT unsigned tguy_get_frames_count

(

const TrashGuyState *

st

)

Returns number of frames particular TrashGuyState has

Parameters

st	Valid TrashGuyState

Returns

Number of frames, >= 1

tguy_get_string()

LIBTGUY_EXPORT const char * tguy_get_string	(	TrashGuyState *restrict	st,
		size_t *	len
	)

Return read-only pointer to utf-8 encoded null terminated string containing current set frame. Does NOT need to be freed manually, is freed by tguy_free() later. Roughly equivalent to buf = malloc(tguy_get_bsize(st)) + tguy_sprint(st, buf)

Parameters

st	Valid TrashGuyState with frame set
[out,optional]	len Length of the returned string in bytes

Returns

tguy_get_version()

LIBTGUY_EXPORT unsigned tguy_get_version

(

void

)

Get version as integer in format MMMmmmppp. 020107002 -> 20.107.2

Returns

Version number

tguy_print()

LIBTGUY_EXPORT size_t tguy_print

(

const TrashGuyState *

st

)

Writes currently set TrashGuy frame to stdout without newline

Parameters

st	Valid TrashGuyState with frame set

Returns

Number of bytes written

tguy_set_frame()

LIBTGUY_EXPORT unsigned tguy_set_frame	(	TrashGuyState *	st,
		unsigned	frame
	)

Sets the current frame for TrashGuyState

Parameters

st	Valid TrashGuyState *
frame	0 <= frame < tguy_get_frames_count()

Returns

frame on success, -1 (UINT_MAX) on failure

tguy_set_pos()

LIBTGUY_EXPORT unsigned tguy_set_pos	(	TrashGuyState *	st,
		unsigned	sprite_pos,
		unsigned	facing_right,
		unsigned	element_index
	)

Sets the current frame for TrashGuyState from state components Position is index into arena received via tguy_get_arr().
Example:

spacing = 1
text = "test"
tguy_get_frames_count() = 29
 
sprite_pos = 1, facing_right = 1, element_index = 0
[ 0] "U(> ^_^)> test"
sprite_pos = 2, facing_right = 1, element_index = 0
[ 1] "U (> ^_^)>test"
sprite_pos = 3, facing_right = 1, element_index = 0
[-1] INVALID, can't overlap with element with index 0
sprite_pos = 2, facing_right = 0, element_index = 0
[ 2] "Ut<(^_^ <) est"
sprite_pos = 1, facing_right = 0, element_index = 0
[ 3] "U<(^_^ <)  est"
sprite_pos = 1, facing_right = 1, element_index = 1
[ 4] "U(> ^_^)>  est"
There's no element with index 4, but this special case is allowed to face right with all elements cleared
sprite_pos = 1, facing_right = 1, element_index = 4
[28] "U(> ^_^)>     "

Parameters

st	Valid TrashGuyState *
sprite_pos	Position within the arena, 0 < sprite_pos < tguy_get_arr().len
facing_right	Whether sprite should be facing right, otherwise left carrying the element
element_index	Index of the element that's currently being processed, see tguy_get_first_frame_for_element()

Returns

frame on success, -1 (UINT_MAX) on failure

tguy_sprint()

LIBTGUY_EXPORT size_t tguy_sprint	(	const TrashGuyState *	st,
		char	buf[]
	)

Writes currently set TrashGuy frame to buffer and appends nul terminator

Parameters

st	Valid TrashGuyState with frame set
buf	Buffer at least tguy_get_bsize() bytes large

Returns

Number of bytes written, excluding the nul terminator