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

Include dependency graph for string_util.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	string_feeder

Macros
#define	str_concat(...) _str_concat_private(__VA_ARGS__, NULL)

Typedefs
typedef struct string_buffer	string_buffer_t

typedef struct string_feeder	string_feeder_t

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

char *	sprintf_alloc (const char *fmt,...) __attribute__((format(printf

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

int	str_diff_idx (const char a, const char b)

bool	str_ends_with (const char haystack, const char needle)

char *	str_expand_envs (const char *in)

int	str_indexof (const char haystack, const char needle)

int	str_last_indexof (const char haystack, const char needle)

char *	str_lstrip (char *str)

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

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

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

char *	str_rstrip (char *str)

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

void	str_split_destroy (zarray_t *s)

zarray_t *	str_split_spaces (const char *str)

bool	str_starts_with (const char haystack, const char needle)

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

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

char *	str_tolowercase (char *s)

char *	str_touppercase (char *s)

char *	str_trim (char *str)

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

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

void	string_buffer_append (string_buffer_t *sb, char c)

void	string_buffer_append_string (string_buffer_t sb, const char str)

void	string_buffer_appendf (string_buffer_t sb, const char fmt,...) __attribute__((format(printf

string_buffer_t *	string_buffer_create ()

void	string_buffer_destroy (string_buffer_t *sb)

void bool	string_buffer_ends_with (string_buffer_t sb, const char str)

char	string_buffer_pop_back (string_buffer_t *sb)

void	string_buffer_reset (string_buffer_t *sb)

size_t	string_buffer_size (string_buffer_t *sb)

char *	string_buffer_to_string (string_buffer_t *sb)

string_feeder_t *	string_feeder_create (const char *str)

void	string_feeder_destroy (string_feeder_t *sf)

int	string_feeder_get_column (string_feeder_t *sf)

int	string_feeder_get_line (string_feeder_t *sf)

bool	string_feeder_has_next (string_feeder_t *sf)

char	string_feeder_next (string_feeder_t *sf)

char *	string_feeder_next_length (string_feeder_t *sf, size_t length)

char	string_feeder_peek (string_feeder_t *sf)

char *	string_feeder_peek_length (string_feeder_t *sf, size_t length)

void	string_feeder_require (string_feeder_t sf, const char str)

bool	string_feeder_starts_with (string_feeder_t sf, const char str)

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

Macro Definition Documentation

◆ str_concat

#define str_concat ( ... ) _str_concat_private(__VA_ARGS__, NULL)

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.

Definition at line 76 of file string_util.h.

Typedef Documentation

◆ string_buffer_t

typedef struct string_buffer string_buffer_t

Definition at line 42 of file string_util.h.

◆ string_feeder_t

typedef struct string_feeder string_feeder_t

Definition at line 44 of file string_util.h.

Function Documentation

◆ _str_concat_private()

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

Definition at line 92 of file string_util.c.

◆ 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

Definition at line 215 of file string_util.h.

◆ str_diff_idx()

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

Definition at line 128 of file string_util.c.

◆ 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.

Definition at line 560 of file string_util.c.

◆ str_expand_envs()

char* str_expand_envs ( const char * in )

Definition at line 736 of file string_util.c.

◆ 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.

Definition at line 253 of file string_util.c.

◆ str_last_indexof()

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

Definition at line 272 of file string_util.c.

◆ 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

Definition at line 231 of file string_util.c.

◆ 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.

Definition at line 608 of file string_util.c.

◆ 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

Definition at line 640 of file string_util.c.

◆ str_replace_many()

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

Definition at line 668 of file string_util.c.

◆ 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

Definition at line 243 of file string_util.c.

◆ 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 responsibilty 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);

Definition at line 148 of file string_util.c.

◆ str_split_destroy()

void str_split_destroy ( zarray_t * s )

Definition at line 215 of file string_util.c.

◆ str_split_spaces()

zarray_t* str_split_spaces ( const char * str )

Definition at line 185 of file string_util.c.

◆ str_starts_with()

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

inline

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

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

Definition at line 577 of file string_util.c.

◆ 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.

Definition at line 593 of file string_util.c.

◆ str_substring()

char* str_substring	(	const char *	str,
		size_t	startidx,
		long	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

Definition at line 623 of file string_util.c.

◆ 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.

Definition at line 291 of file string_util.c.

◆ 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.

Definition at line 304 of file string_util.c.

◆ 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

Definition at line 224 of file string_util.c.

◆ strcaseeq()

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

inlinestatic

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

Definition at line 121 of file string_util.h.

◆ streq()

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

inlinestatic

Definition at line 106 of file string_util.h.

◆ 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.

Definition at line 338 of file string_util.c.

◆ 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.

Definition at line 393 of file string_util.c.

◆ 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 ( )

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.

Definition at line 317 of file string_util.c.

◆ 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.

Definition at line 326 of file string_util.c.

◆ 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.

Definition at line 410 of file string_util.c.

◆ 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

Definition at line 351 of file string_util.c.

◆ string_buffer_reset()

void string_buffer_reset ( string_buffer_t * sb )

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

Definition at line 433 of file string_util.c.

◆ 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).

Definition at line 426 of file string_util.c.

◆ 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.

Definition at line 418 of file string_util.c.

◆ 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.

Definition at line 441 of file string_util.c.

◆ 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.

Definition at line 466 of file string_util.c.

◆ 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

Definition at line 460 of file string_util.c.

◆ 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

Definition at line 454 of file string_util.c.

◆ 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.

Definition at line 476 of file string_util.c.

◆ 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.

Definition at line 483 of file string_util.c.

◆ 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.

Definition at line 499 of file string_util.c.

◆ 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.

Definition at line 514 of file string_util.c.

◆ 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.

Definition at line 522 of file string_util.c.

◆ 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.

Definition at line 545 of file string_util.c.

◆ 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.

Definition at line 536 of file string_util.c.

◆ 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.

Definition at line 60 of file string_util.c.

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()