tou.h File Reference

Tou header library. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include <stdbool.h>

Go to the source code of this file.

Data Structures
struct	tou_llist_t
	Linked list struct definition, typedef'd. More...
struct	tou_block_store_struct
	Struct containing buffer and count to be used in block-reading. More...

Macros
#define	TOU_GET_VERSION()   (20240819L)
	A unique tou.h version identifier.
#define	TOU_DBG   0
	Control library debug output & debug code blocks.
#define	TOU_DEBUG(...)   if (TOU_DBG) { __VA_ARGS__; } else (void)0
	Place a block of code inside that you wish to enable if debugging.
#define	TOU_DEBUG_PREFIX   "[:] "
	Debug prefix before messages used in PRINTD()
#define	TOU_PRINTD(format, ...)   if (TOU_DBG) { fprintf(stdout, TOU_DEBUG_PREFIX format, ##__VA_ARGS__); } else (void)0
	Debug print, used like printf()
#define	nullptr   ((void*)0)
	nullptr def in case i felt like using it
#define	TOU_DEFAULT_BLOCKSIZE   4096
	How many bytes to read when reading a file if unspecified.
#define	TOU_JSON_DATA_VER   "1.0"
	Data format version when exporting INI to JSON.
#define	TOU_XML_DATA_VER   "1.0"
	Data format version when exporting INI to JSON.
#define	TOU_STR(s)   #s
	Helps convert 's' into a literal.
#define	TOU_MSTR(s)   TOU_STR(s)
	Helps convert 's' into C literal.
#define	TOU_IS_BLANK(c)   ((c)==' ' || (c)=='\n' || (c)=='\r' || (c)=='\t')
	Is character a whitespace char?
#define	TOU_ARRSIZE(x)   (sizeof(x) / sizeof(x[0]))
	Size of array, should also work with const char* [].
#define	TOU_RANDINT(mx, mn)   ((int)(((float)rand()/RAND_MAX) * ((mx)-(mn)) + (mn)))
	Quick and simple random integer.
#define	tou_sisempty(elem, dat)
	Checks if length of given string element (.dat1/2) is zero after trimming it from the start.
#define	TOU_SILENCE(...)
	Shorthand for surrounding a piece of code with tou_disable_stdout and tou_enable_stdout.
#define	tou_llist_new(...)   ((TOU_DBG ? fprintf(stdout,TOU_DEBUG_PREFIX"Creating new llist :: NULL\n") : (void)0) , NULL)
	Creates/initializes new llist.
#define	tou_llist_gather   tou_llist_gather_dat1
	Convenience alias for gathering first element.
#define	tou_llist_print(llist, dat1_spec, dat2_spec, ...)
	Macro that goes through the elements from head to tail and prints their .dat1 and .dat2 fields using given format specifiers.
#define	tou_llist_print_tail(llist, dat1_spec, dat2_spec, ...)
	Macro that goes through the elements from tail to head and prints their .dat1 and .dat2 fields using given format specifiers.

Typedefs
typedef void *(*	tou_func) (void *)
	Arbitrary function pointer with 1 parameter.
typedef void *(*	tou_func2) (void *, void *)
	Arbitrary function pointer with 2 parameters.
typedef void *(*	tou_func3) (void *, void *, void *)
	Arbitrary function pointer with 3 parameters.
typedef tou_llist_t	tou_stack
	Make a stack alias for convenience.
typedef tou_llist_t	tou_queue
	Make a queue alias for convenience.
typedef struct tou_llist	tou_llist_elem
	Make an element alias for convenience.

Enumerations
enum	tou_iter_action { TOU_BREAK = 0 , TOU_CONTINUE = 1 }
	Can be used while iterating to indicate user wishing to abort or continue as normal.

Functions
size_t	tou_strlcpy (char *dst, const char *src, size_t size)
	Copies string SRC to DST, always places terminator.
size_t	tou_strlcat (char *dst, const char *src, size_t size)
	Concatenates string SRC to DST, always places terminator.
size_t	tou_strlen (const char *str)
	Same as strlen() but checks for null pointer.
char *	tou_strdup (const char *src)
	Strdup implementation; returns a malloc'd copy of the string.
char *	tou_strndup (const char *src, size_t size)
	Returns a newly allocated copy of a string, capped at 'size' length (not including '\0'), or NULL if unable to allocate.
char *	tou_strchr (const char *src, int ch)
	Finds the first occurence of ch in the string and returns pointer to it, or NULL if not found.
char *	tou_strrchr (const char *src, int ch)
	Finds the last occurence of ch in the string and returns pointer to it, or NULL if not found.
char *	tou_trim_string (char **str)
	Trims whitespaces from front and back of the string.
char *	tou_trim_front (char **str)
	Trims whitespaces only from the front of the string.
char *	tou_trim_back (char **str)
	Trims whitespaces only from the back of the string.
void	tou_trim_string_pure (char *str, char **start, char **end)
	Returns pointers to the first and last character that are not whitespaces.
char *	tou_trim_front_pure (char *str)
	Returns pointer to the first character from the front that isn't a whitespace.
char *	tou_trim_back_pure (char *str)
	Returns pointer to the first byte AFTER the contents of the string, or the NUL byte.
char *	tou_slower (char *str)
	Converts all characters in str to lowercase in-place.
char *	tou_supper (char *str)
	Converts all characters in str to uppercase in-place.
char *	tou_replace_ch (char *ss, char oldch, char newch)
	Replaces all occurences of oldch with newch
char *	tou_sfind (const char *str, const char *kwd)
	Finds start of substring(keyword) in the given char*.
char *	tou_sfind_n (const char *str, const char *kwd, size_t maxlen)
	Finds start of substring(keyword) in the given char*, looking at a max of maxlen characters.
char *	tou_sfind_multiple (const char *str, const char **kwds, int n_kwds, int *found_idx)
	Like tou_sfind but searches for more than one string at a time.
char *	tou_sfind_multiple_n (const char *str, const char **kwds, int n_kwds, int *found_idx, size_t maxlen)
	Like tou_sfind_n but searches for more than one string at a time.
void	tou_sfind_iter_multiple (const char *src, const char *kwds[], int n_kwds, tou_func3 cb, void *userdata)
	Iteratively finds occurences of strings in kwds and calls user function for each one.
void	tou_sfind_iter_multiple_n (const char *src, const char *kwds[], int n_kwds, tou_func3 cb, void *userdata, size_t maxlen)
	Iteratively finds occurences of strings in kwds and calls user function for each one, up to maxlen characters in src.
tou_llist_t *	tou_split (char *str, const char *delim)
	Splits string using a delimiter that may be longer than one character.
char *	tou_sappend (char *dst, char *src)
	(Re)allocates enough memory for src and appends it to dst
char *	tou_sprepend (char *dst, char *src)
	(Re)allocates enough memory for src and prepends it to dst
char *	tou_sreplace (char *str, char *repl_str, char *with_str)
	Helper for tou_sreplace that takes the whole string into consideration.
char *	tou_sreplace_n (char *str, char *repl_str, char *with_str, size_t *len_ptr)
	Replaces string repl_str with with_str in the str, testing str up to the character *len_ptr.
size_t	tou_read_fp_in_blocks (FILE *fp, size_t blocksize, tou_func3 cb, void *userdata)
	Reads file in blocks, calling user-provided function for each block.
void *	tou_block_store_cb (void *blockdata, void *len, void *userdata)
	Appends the given block to the buffer in tou_block_store_struct through realloc().
char *	tou_read_file (const char *filename, size_t *read_len)
	Reads file from filename.
char *	tou_read_fp (FILE *fp, size_t *read_len)
	Reads from fp.
int	tou_disable_stdout ()
	Redirects STDOUT to /dev/null (or NUL: on Windows)
void	tou_enable_stdout (int saved_fd)
	Re-enables STDOUT that had been disabled using the saved file descriptor from previous function.
tou_llist_t *	tou_llist_append (tou_llist_t **elem, void *dat1, void *dat2, char dat1_is_dynalloc, char dat2_is_dynalloc)
	Appends a brand new element to the list/given element and updates it in place.
tou_llist_t *	tou_llist_appendone (tou_llist_t **elem, void *dat1, char dat1_is_dynalloc)
	Appends a brand new element to the list/given element which contains only dat1 and if the pointer was the head, updates it in place.
tou_llist_t *	tou_llist_prepend (tou_llist_t **elem, void *dat1, void *dat2, char dat1_is_dynalloc, char dat2_is_dynalloc)
	Prepends a brand new element to the list/given element.
tou_llist_t *	tou_llist_prependone (tou_llist_t **elem, void *dat1, char dat1_is_dynalloc)
	Prepends a brand new element to the list/given element which only contains dat1.
void	tou_llist_destroy (tou_llist_t *list)
	Traverses elements using .next or .prev and frees each one including copied category string.
tou_llist_t *	tou_llist_remove (tou_llist_t *elem)
	Removes an element from llist and deallocates it.
tou_llist_t *	tou_llist_pop (tou_llist_t *elem)
	Disconnects an element from llist but does not deallocate it.
void	tou_llist_free_element (tou_llist_t *elem)
	Frees an element and its contents.
tou_llist_t *	tou_llist_get_head (tou_llist_t *list)
	Traverses the whole list using .next and returns the last element that was added into list (where .next is NULL)
tou_llist_t *	tou_llist_get_tail (tou_llist_t *list)
	Traverses the whole list using .prev and returns the first element that was added to list (where .prev is NULL)
tou_llist_t *	tou_llist_get_newest (tou_llist_t *list)
	Returns the element that was added to the list last.
tou_llist_t *	tou_llist_get_oldest (tou_llist_t *list)
	Returns the element that was added to the list first.
tou_llist_t *	tou_llist_get_newer (tou_llist_t *elem)
	Returns the element added after elem.
tou_llist_t *	tou_llist_get_older (tou_llist_t *elem)
	Returns the element added before elem.
tou_llist_t *	tou_llist_next_newer (tou_llist_t **elem)
	Updates elem to point to the element added after itself.
tou_llist_t *	tou_llist_next_older (tou_llist_t **elem)
	Updates elem to point to the element added before itself.
char	tou_llist_is_head (tou_llist_t *elem)
	Checks if element is head of the list (.next should be NULL)
char	tou_llist_is_tail (tou_llist_t *elem)
	Checks if element is tail of the list (.prev should be NULL)
void	tou_llist_iter (tou_llist_t *list, tou_func cb)
	Iterate through and call the specified function for each element Automatically checks whether given element is head or tail and iterates accordingly.
tou_llist_t *	tou_llist_find_exact (tou_llist_t *list, void *dat1, void *dat2)
	Traverses the list starting from the passed element and tries to find the first matching element by simple equals-comparison using both parameters at the same time.
tou_llist_t *	tou_llist_find_exactone (tou_llist_t *list, void *dat1)
	Traverses the list starting from the passed element and tries to find the first matching element by simple equals-comparison of param.
tou_llist_t *	tou_llist_find_key (tou_llist_t *list, void *dat1)
	Traverses the list starting from the passed element and tries to find the first matching element on the basis: if dat1 is not null, tries to match it as a nul-terminated string.
tou_llist_t *	tou_llist_find_func (tou_llist_t *list, tou_func2 cb, void *userdata)
	Traverses the list starting from the passed element and tries to find the first matching element by checking the return value of the given callback comparison function.
size_t	tou_llist_len (tou_llist_t *list)
	Goes through the list and returns amount of elements.
void **	tou_llist_gather_dat1 (tou_llist_t *list, size_t *len)
	Constructs a dynamically allocated ARRAY containing only .dat1 properties (stored as void*).
void **	tou_llist_gather_dat2 (tou_llist_t *list, size_t *len)
	Constructs a dynamically allocated ARRAY containing only .dat2 properties (stored as void*).
tou_llist_t *	tou_stack_new ()
	Creates a new stack object.
void	tou_stack_destroy (tou_llist_t *stack)
	Destroys existing stack object.
size_t	tou_stack_len (tou_llist_t *stack)
	Returns the length of the stack.
void	tou_stack_push (tou_llist_t **stack, void *elem)
	Pushes a new element to the top of the stack.
void *	tou_stack_pop (tou_llist_t **stack)
	Pops an element from the top of the stack.
tou_llist_t *	tou_queue_new ()
	Creates a new queue object.
void	tou_queue_destroy (tou_llist_t *queue)
	Destroys existing queue object.
size_t	tou_queue_len (tou_llist_t *queue)
	Returns the length of the queue.
void	tou_queue_push (tou_llist_t **queue, void *elem)
	Pushes a new element to the top of the Queue.
void *	tou_queue_pop (tou_llist_t **queue)
	Pops an element from the top of the Queue.
tou_llist_t *	tou_ini_parse_fp (FILE *fp)
	Parses given FILE* as .INI file and constructs structured data.
tou_llist_t *	tou_ini_parse_buffer (char *buf)
	Parses given buffer as .INI file and constructs structured data.
int	tou_ini_parse_line (tou_llist_t **inicontents, char *line)
	Parses a single line as .INI section/property and adds it to structure.
void	tou_ini_destroy (tou_llist_t *inicontents)
	Destroys contents of .INI structure including deallocation of inner structures; assumes head was passed.
void	tou_ini_print (tou_llist_t *inicontents)
	Prints the contents of the parsed .INI structure to stdout in a structured graphical format.
tou_llist_t *	tou_ini_get_section (tou_llist_t *inicontents, const char *section_name)
	Returns pointer to the section element matching given 'section_name'.
tou_llist_t *	tou_ini_get_property (tou_llist_t *inicontents, const char *section_name, const char *key)
	Returns pointer to the property element matching given 'section_name' and 'key'.
void *	tou_ini_get (tou_llist_t *inicontents, const char *section_name, const char *key)
	Returns the contents of 'key' under the given 'section_name'.
void *	tou_ini_set (tou_llist_t **inicontents, const char *section_name, const char *key, char *new_value)
	Sets the contents of 'key' under the given 'section_name' to the specified value, reallocating memory if necessary.
tou_llist_t *	tou_ini_section (tou_llist_t *inicontents, const char *section_name)
	Return a pointer to the llist entry of the matching section, or NULL.
void *	tou_ini_property (tou_llist_t *section, const char *property_name)
	Return the value of the matching property in the given section, or NULL.
int	tou_ini_save_fp (tou_llist_t *inicontents, FILE *fp)
	Writes .INI structure data to file stream.
int	tou_ini_save_fp_json (tou_llist_t *inicontents, FILE *fp)
	Exports .INI structure data as JSON to the file stream.
int	tou_ini_save_fp_xml (tou_llist_t *inicontents, FILE *fp)
	Exports .INI structure data as XML to the file stream.
tou_llist_t *	tou_paramparse (char *str, const char *param_sep, const char *keyval_sep)
	Parses "parameter string" and returns a llist of key-value pairs, looking at the whole string (strlen will be used)
tou_llist_t *	tou_paramparse_n (char *str, const char *param_sep, const char *keyval_sep, size_t maxlen)
	Parses "parameter string" and returns a llist of key-value pairs.
void	tou_paramprint (tou_llist_t *params)
	Attempts to print "params" parsed by tou_paramparse or tou_paramparse_n.

Variables
int	_tou_g_saved_stdout
	Filedescriptor handle local to this compilation unit used with TOU_SILENCE.

Detailed Description

Tou header library.

Author

m30ws

Version

1.5 (20240819)

Git repo: https://github.com/m30ws/tou/

Details

Required always but only once! :

• #define TOU_IMPLEMENTATION

Other various defines:

• #define TOU_LLIST_SINGLE_ELEM

Things:

• full linked list impl (todo: improve/cleanup error checking)
• reading file in blocks (filename or FILE*)
• string splitter, trimmer etc. different operations
• .INI file parser / exporter(+JSON,XML)
• safer string functions
• disabling And restoring stdout
• xml parser (todo)
• statically allocated linked list (todo)
• asset embedding (todo)
• A ton of helper definitions