#include <stdio.h>
#include <stdarg.h>
#include <stdbool.h>
#include <ctype.h>
#include "zarray.h"

Classes
struct	string_feeder

Macros
#define	str_concat(...)
	Concatenates 1 or more strings together and returns the result, which will be a newly allocated string which it is the caller's responsibility to free.

Typedefs
typedef struct string_buffer	string_buffer_t

typedef struct string_feeder	string_feeder_t

Functions
char *	sprintf_alloc (const char *fmt,...) __attribute__((format(printf
	Similar to sprintf(), except that it will malloc() enough space for the formatted string which it returns.

char char *	vsprintf_alloc (const char *fmt, va_list args)
	Similar to vsprintf(), except that it will malloc() enough space for the formatted string which it returns.

char *	_str_concat_private (const char *first,...)

int	str_diff_idx (const char a, const char b)

zarray_t *	str_split (const char str, const char delim)
	Splits the supplied string into an array of strings by subdividing it at each occurrence of the supplied delimiter string.

zarray_t *	str_split_spaces (const char *str)

void	str_split_destroy (zarray_t *s)

static bool	streq (const char str1, const char str2)

static bool	strcaseeq (const char str1, const char str2)
	Determines if str1 exactly matches str2, ignoring case (more efficient than strcasecmp(...) == 0)

char *	str_trim (char *str)
	Trims whitespace characters (i.e.

char *	str_lstrip (char *str)
	Trims whitespace characters (i.e.

char *	str_rstrip (char *str)
	Trims whitespace characters (i.e.

bool	str_ends_with (const char haystack, const char needle)
	Returns true if the end of string 'haystack' matches 'needle', else false.

bool	str_starts_with (const char haystack, const char needle)
	Returns true if the start of string 'haystack' matches 'needle', else false.

bool	str_starts_with_any (const char haystack, const char *needles, int num_needles)
	Returns true if the start of string 'haystack' matches any needle, else false.

bool	str_matches_any (const char haystack, const char *needles, int num_needles)
	Returns true if the string 'haystack' matches any needle, else false.

char *	str_substring (const char *str, size_t startidx, size_t endidx)
	Retrieves a (newly-allocated) substring of the given string, 'str', starting from character index 'startidx' through index 'endidx' - 1 (inclusive).

int	str_indexof (const char haystack, const char needle)
	Retrieves the zero-based index of the beginning of the supplied substring (needle) within the search string (haystack) if it exists.

static int	str_contains (const char haystack, const char needle)

int	str_last_indexof (const char haystack, const char needle)

char *	str_tolowercase (char *s)
	Replaces all upper-case characters within the supplied string with their lower-case counterparts, modifying the original string's contents.

char *	str_touppercase (char *s)
	Replaces all lower-case characters within the supplied string with their upper-case counterparts, modifying the original string's contents.

char *	str_replace (const char haystack, const char needle, const char *replacement)
	Replaces all occurrences of 'needle' in the string 'haystack', substituting for them the value of 'replacement', and returns the result as a newly-allocated string.

char *	str_replace_many (const char *_haystack,...)

string_buffer_t *	string_buffer_create (void)
	Creates and initializes a string buffer object which can be used with any of the string_buffer_*() functions.

void	string_buffer_destroy (string_buffer_t *sb)
	Frees the resources associated with a string buffer object, including space allocated for any appended characters / strings.

void	string_buffer_append (string_buffer_t *sb, char c)
	Appends a single character to the end of the supplied string buffer.

char	string_buffer_pop_back (string_buffer_t *sb)
	Removes a single character from the end of the string and returns it.

void	string_buffer_append_string (string_buffer_t sb, const char str)
	Appends the supplied string to the end of the supplied string buffer.

void	string_buffer_appendf (string_buffer_t sb, const char fmt,...) __attribute__((format(printf
	Formats the supplied string and arguments in a manner akin to printf(), and appends the resulting string to the end of the supplied string buffer.

void bool	string_buffer_ends_with (string_buffer_t sb, const char str)
	Determines whether the character contents held by the supplied string buffer ends with the supplied string.

size_t	string_buffer_size (string_buffer_t *sb)
	Returns the string-length of the contents of the string buffer (not counting \0).

char *	string_buffer_to_string (string_buffer_t *sb)
	Returns the contents of the string buffer in a newly-allocated string, which it is the caller's responsibility to free once it is no longer needed.

void	string_buffer_reset (string_buffer_t *sb)
	Clears the contents of the string buffer, setting its length to zero.

string_feeder_t *	string_feeder_create (const char *str)
	Creates a string feeder object which can be used to traverse the supplied string using the string_feeder_*() functions.

void	string_feeder_destroy (string_feeder_t *sf)
	Frees resources associated with the supplied string feeder object, after which it will no longer be valid for use.

bool	string_feeder_has_next (string_feeder_t *sf)
	Determines whether any characters remain to be retrieved from the string feeder's string (not including the terminating '\0').

char	string_feeder_next (string_feeder_t *sf)
	Retrieves the next available character from the supplied string feeder (which may be the terminating '\0' character) and advances the feeder's position to the next character in the string.

char *	string_feeder_next_length (string_feeder_t *sf, size_t length)
	Retrieves a series of characters from the supplied string feeder.

char	string_feeder_peek (string_feeder_t *sf)
	Retrieves the next available character from the supplied string feeder (which may be the terminating '\0' character), but does not advance the feeder's position so that subsequent calls to _next() or _peek() will retrieve the same character.

char *	string_feeder_peek_length (string_feeder_t *sf, size_t length)
	Retrieves a series of characters from the supplied string feeder.

int	string_feeder_get_line (string_feeder_t *sf)
	Retrieves the line number of the current position in the supplied string feeder, which will be incremented whenever a newline is consumed.

int	string_feeder_get_column (string_feeder_t *sf)
	Retrieves the column index in the current line for the current position in the supplied string feeder, which will be incremented with each non-newline character consumed, and reset to 0 whenever a newline ( ) is consumed.

bool	string_feeder_starts_with (string_feeder_t sf, const char str)
	Determines whether the supplied string feeder's remaining contents starts with the given string.

void	string_feeder_require (string_feeder_t sf, const char str)
	Consumes from the string feeder the number of characters contained in the given string (not including the terminating '\0').

char *	str_expand_envs (const char *in)

Macro Definition Documentation

◆ str_concat

#define str_concat ( ... )

Value:

_str_concat_private(__VA_ARGS__, NULL)

_str_concat_private

char * _str_concat_private(const char *first,...)

Concatenates 1 or more strings together and returns the result, which will be a newly allocated string which it is the caller's responsibility to free.

Typedef Documentation

◆ string_buffer_t

typedef struct string_buffer string_buffer_t

◆ string_feeder_t

typedef struct string_feeder string_feeder_t

Function Documentation

◆ _str_concat_private()

char * _str_concat_private	(	const char *	first,
			... )

◆ sprintf_alloc()

char * sprintf_alloc	(	const char *	fmt,
			... )

Similar to sprintf(), except that it will malloc() enough space for the formatted string which it returns.

It is the caller's responsibility to call free() on the returned string when it is no longer needed.

◆ str_contains()

static int str_contains	(	const char *	haystack,
		const char *	needle )

inlinestatic

◆ str_diff_idx()

int str_diff_idx	(	const char *	a,
		const char *	b )

◆ str_ends_with()

bool str_ends_with	(	const char *	haystack,
		const char *	needle )

Returns true if the end of string 'haystack' matches 'needle', else false.

Note: An empty needle ("") will match any source.

◆ str_expand_envs()

char * str_expand_envs ( const char * in )

◆ str_indexof()

int str_indexof	(	const char *	haystack,
		const char *	needle )

Retrieves the zero-based index of the beginning of the supplied substring (needle) within the search string (haystack) if it exists.

Returns -1 if the supplied needle is not found within the haystack.

◆ str_last_indexof()

int str_last_indexof	(	const char *	haystack,
		const char *	needle )

◆ str_lstrip()

char * str_lstrip ( char * str )

Trims whitespace characters (i.e.

matching isspace()) from the beginning of the supplied string. This change affects the supplied string in-place. The supplied/edited string is returned to enable chained reference.

Note: do not pass a string literal to this function

◆ str_matches_any()

bool str_matches_any	(	const char *	haystack,
		const char **	needles,
		int	num_needles )

Returns true if the string 'haystack' matches any needle, else false.

◆ str_replace()

char * str_replace	(	const char *	haystack,
		const char *	needle,
		const char *	replacement )

Replaces all occurrences of 'needle' in the string 'haystack', substituting for them the value of 'replacement', and returns the result as a newly-allocated string.

The original strings remain unchanged.

It is the caller's responsibility to free the returned string.

Examples: str_replace("string", "ri", "u") = "stung" str_replace("singing", "ing", "") = "s" str_replace("string", "foo", "bar") = "string"

Note: An empty needle will match only an empty haystack

◆ str_replace_many()

char * str_replace_many	(	const char *	_haystack,
			... )

◆ str_rstrip()

char * str_rstrip ( char * str )

Trims whitespace characters (i.e.

matching isspace()) from the end of the supplied string. This change affects the supplied string in-place. The supplied/edited string is returned to enable chained reference.

Note: do not pass a string literal to this function

◆ str_split()

zarray_t * str_split	(	const char *	str,
		const char *	delim )

Splits the supplied string into an array of strings by subdividing it at each occurrence of the supplied delimiter string.

The split strings will not contain the delimiter. The original string will remain unchanged. If str is composed of all delimiters, an empty array will be returned.

It is the caller's responsibility to free the returned zarray, as well as the strings contained within it, e.g.:

zarray_t *za = str_split("this is a haystack", " "); => ["this", "is", "a", "haystack"] zarray_vmap(za, free); zarray_destroy(za);

◆ str_split_destroy()

void str_split_destroy ( zarray_t * s )

◆ str_split_spaces()

zarray_t * str_split_spaces ( const char * str )

◆ str_starts_with()

bool str_starts_with	(	const char *	haystack,
		const char *	needle )

Returns true if the start of string 'haystack' matches 'needle', else false.

Note: An empty needle ("") will match any source.

◆ str_starts_with_any()

bool str_starts_with_any	(	const char *	haystack,
		const char **	needles,
		int	num_needles )

Returns true if the start of string 'haystack' matches any needle, else false.

Note: An empty needle ("") will match any source.

◆ str_substring()

char * str_substring	(	const char *	str,
		size_t	startidx,
		size_t	endidx )

Retrieves a (newly-allocated) substring of the given string, 'str', starting from character index 'startidx' through index 'endidx' - 1 (inclusive).

An 'endidx' value -1 is equivalent to strlen(str).

It is the caller's responsibility to free the returned string.

Examples: str_substring("string", 1, 3) = "tr" str_substring("string", 2, -1) = "ring" str_substring("string", 3, 3) = ""

Note: startidx must be >= endidx

◆ str_tolowercase()

char * str_tolowercase ( char * s )

Replaces all upper-case characters within the supplied string with their lower-case counterparts, modifying the original string's contents.

Returns the supplied / modified string.

◆ str_touppercase()

char * str_touppercase ( char * s )

Replaces all lower-case characters within the supplied string with their upper-case counterparts, modifying the original string's contents.

Returns the supplied / modified string.

◆ str_trim()

char * str_trim ( char * str )

Trims whitespace characters (i.e.

matching isspace()) from the beginning and/or end of the supplied string. This change affects the supplied string in-place. The supplied/edited string is returned to enable chained reference.

Note: do not pass a string literal to this function

◆ strcaseeq()

static bool strcaseeq	(	const char *	str1,
		const char *	str2 )

inlinestatic

Determines if str1 exactly matches str2, ignoring case (more efficient than strcasecmp(...) == 0)

◆ streq()

static bool streq	(	const char *	str1,
		const char *	str2 )

inlinestatic

◆ string_buffer_append()

void string_buffer_append	(	string_buffer_t *	sb,
		char	c )

Appends a single character to the end of the supplied string buffer.

◆ string_buffer_append_string()

void string_buffer_append_string	(	string_buffer_t *	sb,
		const char *	str )

Appends the supplied string to the end of the supplied string buffer.

◆ string_buffer_appendf()

void string_buffer_appendf	(	string_buffer_t *	sb,
		const char *	fmt,
			... )

Formats the supplied string and arguments in a manner akin to printf(), and appends the resulting string to the end of the supplied string buffer.

◆ string_buffer_create()

string_buffer_t * string_buffer_create ( void )

Creates and initializes a string buffer object which can be used with any of the string_buffer_*() functions.

It is the caller's responsibility to free the string buffer resources with a call to string_buffer_destroy() when it is no longer needed.

◆ string_buffer_destroy()

void string_buffer_destroy ( string_buffer_t * sb )

Frees the resources associated with a string buffer object, including space allocated for any appended characters / strings.

◆ string_buffer_ends_with()

void bool string_buffer_ends_with	(	string_buffer_t *	sb,
		const char *	str )

Determines whether the character contents held by the supplied string buffer ends with the supplied string.

Returns true if the string buffer's contents ends with 'str', else false.

◆ string_buffer_pop_back()

char string_buffer_pop_back ( string_buffer_t * sb )

Removes a single character from the end of the string and returns it.

Does nothing if string is empty and returns NULL

◆ string_buffer_reset()

void string_buffer_reset ( string_buffer_t * sb )

Clears the contents of the string buffer, setting its length to zero.

◆ string_buffer_size()

size_t string_buffer_size ( string_buffer_t * sb )

Returns the string-length of the contents of the string buffer (not counting \0).

Equivalent to calling strlen() on the string returned by string_buffer_to_string(sb).

◆ string_buffer_to_string()

char * string_buffer_to_string ( string_buffer_t * sb )

Returns the contents of the string buffer in a newly-allocated string, which it is the caller's responsibility to free once it is no longer needed.

◆ string_feeder_create()

string_feeder_t * string_feeder_create ( const char * str )

Creates a string feeder object which can be used to traverse the supplied string using the string_feeder_*() functions.

A local copy of the string's contents will be stored so that future changes to 'str' will not be reflected by the string feeder object.

It is the caller's responsibility to call string_feeder_destroy() on the returned object when it is no longer needed.

◆ string_feeder_destroy()

void string_feeder_destroy ( string_feeder_t * sf )

Frees resources associated with the supplied string feeder object, after which it will no longer be valid for use.

◆ string_feeder_get_column()

int string_feeder_get_column ( string_feeder_t * sf )

Retrieves the column index in the current line for the current position in the supplied string feeder, which will be incremented with each non-newline character consumed, and reset to 0 whenever a newline (
) is consumed.

Examples: prior to reading 1st character: line = 1, column = 0 after reading 1st non-newline character: line = 1, column = 1 after reading 2nd non-newline character: line = 1, column = 2 after reading 1st newline character: line = 2, column = 0 after reading 1st character after 1st newline: line = 2, column = 1 after reading 2nd newline character: line = 3, column = 0

◆ string_feeder_get_line()

int string_feeder_get_line ( string_feeder_t * sf )

Retrieves the line number of the current position in the supplied string feeder, which will be incremented whenever a newline is consumed.

Examples: prior to reading 1st character: line = 1, column = 0 after reading 1st non-newline character: line = 1, column = 1 after reading 2nd non-newline character: line = 1, column = 2 after reading 1st newline character: line = 2, column = 0 after reading 1st character after 1st newline: line = 2, column = 1 after reading 2nd newline character: line = 3, column = 0

◆ string_feeder_has_next()

bool string_feeder_has_next ( string_feeder_t * sf )

Determines whether any characters remain to be retrieved from the string feeder's string (not including the terminating '\0').

Returns true if at least one more character can be retrieved with calls to string_feeder_next(), string_feeder_peek(), string_feeder_peek(), or string_feeder_consume(), else false.

◆ string_feeder_next()

char string_feeder_next ( string_feeder_t * sf )

Retrieves the next available character from the supplied string feeder (which may be the terminating '\0' character) and advances the feeder's position to the next character in the string.

Note: Attempts to read past the end of the string will throw an assertion.

◆ string_feeder_next_length()

char * string_feeder_next_length	(	string_feeder_t *	sf,
		size_t	length )

Retrieves a series of characters from the supplied string feeder.

The number of characters returned will be 'length' or the number of characters remaining in the string, whichever is shorter. The string feeder's position will be advanced by the number of characters returned.

It is the caller's responsibility to free the returned string when it is no longer needed.

Note: Calling once the end of the string has already been read will throw an assertion.

◆ string_feeder_peek()

char string_feeder_peek ( string_feeder_t * sf )

Retrieves the next available character from the supplied string feeder (which may be the terminating '\0' character), but does not advance the feeder's position so that subsequent calls to _next() or _peek() will retrieve the same character.

Note: Attempts to peek past the end of the string will throw an assertion.

◆ string_feeder_peek_length()

char * string_feeder_peek_length	(	string_feeder_t *	sf,
		size_t	length )

Retrieves a series of characters from the supplied string feeder.

The number of characters returned will be 'length' or the number of characters remaining in the string, whichever is shorter. The string feeder's position will not be advanced.

It is the caller's responsibility to free the returned string when it is no longer needed.

Note: Calling once the end of the string has already been read will throw an assertion.

◆ string_feeder_require()

void string_feeder_require	(	string_feeder_t *	sf,
		const char *	str )

Consumes from the string feeder the number of characters contained in the given string (not including the terminating '\0').

Throws an assertion if the consumed characters do not exactly match the contents of the supplied string.

◆ string_feeder_starts_with()

bool string_feeder_starts_with	(	string_feeder_t *	sf,
		const char *	str )

Determines whether the supplied string feeder's remaining contents starts with the given string.

Returns true if the beginning of the string feeder's remaining contents matches the supplied string exactly, else false.

◆ vsprintf_alloc()

char char * vsprintf_alloc	(	const char *	fmt,
		va_list	args )

Similar to vsprintf(), except that it will malloc() enough space for the formatted string which it returns.

It is the caller's responsibility to call free() on the returned string when it is no longer needed.

Classes

Macros

Typedefs

Functions

Macro Definition Documentation

◆ str_concat

Typedef Documentation

◆ string_buffer_t

◆ string_feeder_t

Function Documentation

◆ _str_concat_private()

◆ sprintf_alloc()

◆ str_contains()

◆ str_diff_idx()

◆ str_ends_with()

◆ str_expand_envs()

◆ str_indexof()

◆ str_last_indexof()

◆ str_lstrip()

◆ str_matches_any()

◆ str_replace()

◆ str_replace_many()

◆ str_rstrip()

◆ str_split()

◆ str_split_destroy()

◆ str_split_spaces()

◆ str_starts_with()

◆ str_starts_with_any()

◆ str_substring()

◆ str_tolowercase()

◆ str_touppercase()

◆ str_trim()

◆ strcaseeq()

◆ streq()

◆ string_buffer_append()

◆ string_buffer_append_string()

◆ string_buffer_appendf()

◆ string_buffer_create()

◆ string_buffer_destroy()

◆ string_buffer_ends_with()

◆ string_buffer_pop_back()

◆ string_buffer_reset()

◆ string_buffer_size()

◆ string_buffer_to_string()

◆ string_feeder_create()

◆ string_feeder_destroy()

◆ string_feeder_get_column()

◆ string_feeder_get_line()

◆ string_feeder_has_next()

◆ string_feeder_next()

◆ string_feeder_next_length()

◆ string_feeder_peek()

◆ string_feeder_peek_length()

◆ string_feeder_require()

◆ string_feeder_starts_with()

◆ vsprintf_alloc()