String operations

Macros
#define	tou_sisempty(elem, dat)
	Checks if length of given string element (.dat1/2) is zero after trimming it from the start.

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.

Detailed Description

Macro Definition Documentation

tou_sisempty

#define tou_sisempty	(		elem,
			dat )

Value:

    ((elem) == NULL /* wanted to do without this one but i can already see segfaults happening without it */ || \
     (elem)->dat == NULL || \
     tou_strlen(tou_trim_front_pure((elem)->dat)) == 0)

Checks if length of given string element (.dat1/2) is zero after trimming it from the start.

Parameters

[in]	elem	llist element to check
[in]	dat	One of: dat1, dat2

Returns

Positive if dat1/2 is empty, 0 otherwise

Function Documentation

tou_replace_ch()

char * tou_replace_ch	(	char *	ss,
		char	oldch,
		char	newch )

Replaces all occurences of oldch with newch

Be careful not to pass pointer like this:

char* ss = "aeiouoiea/1/2/3";

as it will segfault (it is read-only). Instead pass string which looks like this:

char ss[] = "aeiouoiea/1/2/3";

Parameters

[in]	ss	String in which to replace occurences
[in]	oldch	Character to replace
[in]	newch	Character with which to replace oldch

Returns

Original ss pointer

tou_sappend()

char * tou_sappend	(	char *	dst,
		char *	src )

(Re)allocates enough memory for src and appends it to dst

Does not know the size of the original destination and will not consider it!

Parameters

[in]	dst	String which will be expanded and copied into
[in]	src	String to copy

Returns

Realloc'd pointer with combined strings

tou_sfind()

char * tou_sfind	(	const char *	str,
		const char *	kwd )

Finds start of substring(keyword) in the given char*.

Parameters

[in]	str	Source string
[in]	kwd	Which keyword to search for

Returns

Pointer to the beginning of the keyword in the text or NULL

tou_sfind_iter_multiple()

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.

The callback receives the following args:

• found [in] Pointer to the keyword found in str
• kwd [in] Pointer to that keyword in kwds
• userdata [in,out] User data passed at the beginning

Parameters

[in]	src	String to search in
[in]	kwds	Array of char* keywords to search for
[in]	n_kwds	Count of keywords to search for in kwds
[in]	cb	User callback called for each found token
[in]	userdata	User data passed to callback

tou_sfind_iter_multiple_n()

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.

The callback receives the following args:

• found [in] Pointer to the keyword found in str
• kwd [in] Pointer to that keyword in kwds
• userdata [in,out] User data passed at the beginning

Parameters

[in]	src	String to search in
[in]	kwds	Array of char* keywords to search for
[in]	n_kwds	Count of keywords to search for in kwds
[in]	cb	User callback called for each found token
[in]	userdata	User data passed to callback
[in]	maxlen	Max characters from str to consider

tou_sfind_multiple()

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.

found_idx may be NULL if you don't need to know which keyword was found.

Parameters

[in]	str	String to search in
[in]	kwds	Array of char* keywords to search for
[in]	n_kwds	Count of keywords to search for in kwds
[out]	found_idx	Which of the strings in kwds was found

Returns

Pointer to the first found string

tou_sfind_multiple_n()

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.

found_idx may be NULL if you don't need to know which keyword was found.

Parameters

[in]	str	String to search in
[in]	kwds	Array of char* keywords to search for
[in]	n_kwds	Count of keywords to search for in kwds
[out]	found_idx	Which of the strings in kwds was found
[in]	maxlen	Max characters from str to consider

Returns

Pointer to the first found string

tou_sfind_n()

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.

Parameters

[in]	str	Source string
[in]	kwd	Which keyword to search for
[in]	maxlen	Looks only at the first maxlen characters

Returns

Pointer to the beginning of the keyword in the text or NULL

tou_slower()

char * tou_slower

(

char *

str

)

Converts all characters in str to lowercase in-place.

Parameters

[in,out]

str

String to convert

Returns

Pointer to the same string

tou_split()

tou_llist_t * tou_split	(	char *	str,
		const char *	delim )

Splits string using a delimiter that may be longer than one character.

Parameters

[in]	str	String to be split
[in]	delim	Delimiter string

Returns

Linked list containing tokens

tou_sprepend()

char * tou_sprepend	(	char *	dst,
		char *	src )

(Re)allocates enough memory for src and prepends it to dst

Does not know the size of the original destination and will not consider it!

Parameters

[in]	dst	String which will be expanded and copied into
[in]	src	String to copy

Returns

Realloc'd pointer with combined strings

tou_sreplace()

char * tou_sreplace	(	char *	str,
		char *	repl_str,
		char *	with_str )

Helper for tou_sreplace that takes the whole string into consideration.

Parameters

[in,out]	str	String to be searched for tokens
[in]	repl_str	String to replace
[in]	with_str	String to replace with

Returns

Pointer to the newly allocated replaced string

tou_sreplace_n()

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.

When all tokens that can be found are replaces, the remainder of the str (until '\0' is found) is copied to the end of the buffer. If parameter len_ptr is passed as NULL or set to 0, the whole string will be taken into consideration using strlen. If given, it will also be set to new length after replacing. Cutting off at length is performed by temporarily modifying original string and placing '\0' at that position, which is removed right after no more tokens to be replaced can be found.

[!] If you use this function in a loop and keep reassigning new pointers to it don't forget the original pointer will be invalid at the end! (either reassign the new pointer to it or don't use it after anymore.)

Parameters

[in,out]	str	String to be searched for tokens
[in]	repl_str	String to replace
[in]	with_str	String to replace with
[in,out]	len_ptr	Pointer to the length variable

Returns

Pointer to the newly allocated replaced string

tou_strchr()

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.

Character ch is converted and compared as char.

Parameters

[in]	src	String to look in
[in]	ch	Character to search for

Returns

Pointer to the character found, or NULL

tou_strdup()

char * tou_strdup

(

const char *

src

)

Strdup implementation; returns a malloc'd copy of the string.

Parameters

[in]

src

String to be duplicated

Returns

Pointer to the newly allocated copy of the string

tou_strlcat()

size_t tou_strlcat	(	char *	dst,
		const char *	src,
		size_t	size )

Concatenates string SRC to DST, always places terminator.

The concatenated string is limited to SIZE - 1 characters. A null terminator is always written to DST, unless SIZE is 0. Returns the length that the concatenated string would have assuming that there was sufficient space, not including a null terminator.

strlcat() is not in the standard C library, but it is an increasingly popular extension. See http://www.courtesan.com/todd/papers/strlcpy.html https://www.millert.dev/papers/strlcpy for information on strlcpy().

Parameters

[out]	dst	Destination buffer
[in]	src	Source string
[in]	size	Max size after concatenation including null terminator

Returns

Length of the string after concatenation

tou_strlcpy()

size_t tou_strlcpy	(	char *	dst,
		const char *	src,
		size_t	size )

Copies string SRC to DST, always places terminator.

If SRC is longer than SIZE - 1 characters, only SIZE - 1 characters are copied. A null terminator is always written to DST, unless SIZE is 0. Returns the length of SRC, not including the null terminator.

strlcpy() is not in the standard C library, but it is an increasingly popular extension. See http://www.courtesan.com/todd/papers/strlcpy.html https://www.millert.dev/papers/strlcpy for information on strlcpy().

Parameters

[out]	dst	Destination buffer
[in]	src	Source string
[in]	size	Max size to be copied including null terminator

Returns

Length of the copied string

tou_strlen()

size_t tou_strlen

(

const char *

str

)

Same as strlen() but checks for null pointer.

Parameters

[in]

str

String, may be NULL

Returns

Length of the string

tou_strndup()

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.

Appends NUL at the end.

Parameters

[in]	src	String to copy from
[in]	size	Max copied bytes from string

Returns

Pointer to a newly allocated string

tou_strrchr()

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.

Character ch is converted and compared as char.

Parameters

[in]	src	String to look in
[in]	ch	Character to search for

Returns

Pointer to the character found, or NULL

tou_supper()

char * tou_supper

(

char *

str

)

Converts all characters in str to uppercase in-place.

Parameters

[in,out]

str

String to convert

Returns

Pointer to the same string

tou_trim_back()

char * tou_trim_back

(

char **

str

)

Trims whitespaces only from the back of the string.

!! This is a destructive operation !!

Parameters

[in]

str

Pointer to the string to be trimmed

Returns

Pointer to the character-after-last ('\0')

tou_trim_back_pure()

char * tou_trim_back_pure

(

char *

str

)

Returns pointer to the first byte AFTER the contents of the string, or the NUL byte.

Parameters

[in]

str

Pointer to the string to be trimmed

Returns

Pointer to the first trimmed byte (or NUL)

tou_trim_front()

char * tou_trim_front

(

char **

str

)

Trims whitespaces only from the front of the string.

Parameters

[in]

str

Pointer to the string to be trimmed

Returns

Pointer to the new start in string

tou_trim_front_pure()

char * tou_trim_front_pure

(

char *

str

)

Returns pointer to the first character from the front that isn't a whitespace.

Parameters

[in]

str

Pointer to the string to be trimmed

Returns

Pointer to first non-whitespace char

tou_trim_string()

char * tou_trim_string

(

char **

str

)

Trims whitespaces from front and back of the string.

!! This is a destructive operation since trim_back is destructive. !!

Parameters

[in]

str

Pointer to the string to be trimmed

Returns

Pointer to the new start in string

tou_trim_string_pure()

void tou_trim_string_pure	(	char *	str,
		char **	start,
		char **	end )

Returns pointers to the first and last character that are not whitespaces.

Parameters

[in]	str	Pointer to the string to be trimmed
[out]	start	Pointer to the start of contents
[out]	end	Pointer to the byte after the contents (or NUL)