String manipulation and processing

String manipulation and processing. More...

Collaboration diagram for String manipulation and processing:

Macros
#define	STR_WHITESPACE   " \t\r\v\n\f"
	all whitespace charaters More...

Functions
CT_STD_API size_t	str_vsprintf (STA_WRITES(len) char *str, size_t len, const char *fmt, va_list args)
	format a string with printf-like syntax More...
CT_STD_API size_t	str_sprintf (STA_WRITES(len) char *str, size_t len, STA_FORMAT_STRING const char *fmt,...)
	format a string with printf-like syntax More...
CT_NODISCARD	STA_PRINTF (2, 3) CT_STD_API text_t text_format(arena_t *arena
	format a string More...
CT_NODISCARD STA_FORMAT_STRING const char CT_NODISCARD CT_STD_API text_t	text_vformat (arena_t *arena, const char *fmt, va_list args)
	format a string More...
CT_NODISCARD STA_FORMAT_STRING const char CT_NODISCARD CT_STD_API char *	str_vformat (arena_t *arena, const char *fmt, va_list args)
	format a string More...
CT_NODISCARD CT_PUREFN CT_STD_API bool	str_startswith (const char *str, const char *prefix)
	see if a string starts with a prefix More...
CT_NODISCARD CT_PUREFN CT_STD_API bool	str_endswith (const char *str, const char *suffix)
	check if a string ends with a substring More...
CT_NODISCARD CT_PUREFN CT_STD_API bool	str_endswithn (STA_READS(len) const char *str, size_t len, const char *suffix)
	check if a string ends with a substring More...
CT_NODISCARD CT_STD_API char *	str_join (const char *sep, const vector_t *parts, arena_t *arena)
	join strings More...
CT_NODISCARD CT_STD_API char *	str_repeat (const char *str, size_t times, arena_t *arena)
	repeat a string More...
CT_NODISCARD CT_STD_API char *	str_normalize (const char *str, arena_t *arena)
	turn a string into a C string literal More...
CT_NODISCARD CT_STD_API char *	str_normalizen (text_view_t text, arena_t *arena)
	turn a string with length into a C string literal More...
CT_STD_API size_t	str_normalize_into (STA_WRITES(len) char *dst, size_t dstlen, STA_READS(srclen) const char *src, size_t srclen)
	normalize a string into a buffer More...
CT_NODISCARD CT_STD_API vector_t *	str_split (const char *str, const char *sep, arena_t *arena)
	split a string into a vector by a separator More...
CT_NODISCARD CT_STD_API const char *	str_common_prefix (const vector_t *args, arena_t *arena)
	find the longest common prefix of a vector of paths More...
CT_PUREFN CT_STD_API size_t	str_rfind (const char *str, const char *sub)
	find the last instance of a substring in a string More...
CT_PUREFN CT_STD_API size_t	str_find (const char *str, const char *sub)
	find the first instance of a substring in a string More...
CT_PUREFN CT_STD_API size_t	str_rfind_any (const char *str, const char *letters)
	find the first instance of a set of characters in a string More...
CT_NODISCARD CT_PUREFN CT_STD_API bool	char_is_any_of (char c, const char *chars)
	check if a character is any of a set of characters More...
CT_NODISCARD CT_PUREFN CT_STD_API bool	str_contains (const char *str, const char *search)
	check if a string contains a substring More...
CT_NODISCARD CT_STD_API char *	str_replace (const char *str, const char *search, const char *repl, arena_t *arena)
	replace all instances of a substring in a string More...
CT_STD_API void	str_replace_inplace (INOUT_NOTNULL text_t *text, const char *search, const char *repl)
	replace all instances of a substring in a string in place More...
CT_STD_API void	str_trim_back_inplace (INOUT_NOTNULL text_t *text, const char *chars)
	trim chars from the back of a string in place More...
CT_STD_API void	str_sort_inplace (STA_UPDATES(len) char *str, size_t len)
	sort a strings contents in place More...
CT_NODISCARD CT_STD_API char *	str_replace_many (const char *str, const map_t *repl, arena_t *arena)
	replace all instances of a each substring in a string with provided replacement More...
CT_NODISCARD CT_NOALIAS CT_STD_API char *	str_erase (STA_READS(len) char *str, size_t len, const char *letters)
	remove all instances of letters from str More...
CT_NODISCARD CT_STD_API char *	str_basename (const char *path, arena_t *arena)
	get the filename from a path More...
CT_NODISCARD CT_STD_API char *	str_filename (const char *path, arena_t *arena)
	get the filename from a path More...
CT_NODISCARD CT_STD_API char *	str_noext (const char *path, arena_t *arena)
	remove the last file extension from a path More...
CT_NODISCARD CT_STD_API char *	str_ext (const char *path, arena_t *arena)
	get the last file extension from a path More...
CT_NODISCARD CT_STD_API char *	str_directory (const char *path, arena_t *arena)
	get the directory segment of a path More...
CT_NODISCARD CT_STD_API char *	str_upper (const char *str, arena_t *arena)
	uppercase an ascii string More...
CT_NODISCARD CT_STD_API char *	str_lower (const char *str, arena_t *arena)
	lowercase an ascii string this allocates a new string in the provided arena More...
CT_NODISCARD CT_CONSTFN CT_STD_API char	str_tolower (char c)
	get the lowercase version of a character More...
CT_NODISCARD CT_CONSTFN CT_STD_API char	str_toupper (char c)
	get the uppercase version of a character More...
CT_NODISCARD CT_STD_API bool	text_view_equal (text_view_t lhs, text_view_t rhs)
	check if two strings are equal More...

Variables
CT_NODISCARD STA_FORMAT_STRING const char *	fmt

Detailed Description

String manipulation and processing.

Macro Definition Documentation

STR_WHITESPACE

#define STR_WHITESPACE   " \t\r\v\n\f"

all whitespace charaters

Definition at line 411 of file str.h.

Function Documentation

char_is_any_of()

CT_NODISCARD CT_PUREFN CT_STD_API bool char_is_any_of	(	char	c,
		const char *	chars
	)

check if a character is any of a set of characters

Parameters

c	the character to check
chars	the characters to check against

Return values

true	c is any of chars
false	c is not any of chars

Definition at line 121 of file str.c.

STA_PRINTF()

CT_NODISCARD STA_PRINTF	(	2	,
		3
	)

format a string

format a string with printf-like syntax into a text buffer. useful when you need the length of the formatted string.

Parameters

arena	the arena to allocate the formatted string in
fmt	the format string
...	the arguments to format

Returns

the formatted string

format a string with printf-like syntax

Parameters

arena	the arena to allocate the formatted string in
fmt	the format string
...	the arguments to format

Returns

the formatted string

str_basename()

CT_NODISCARD CT_STD_API char* str_basename	(	const char *	path,
		arena_t *	arena
	)

get the filename from a path

Parameters

path	the path to get the filename from
arena	the arena to allocate the filename in

Returns

the filename extracted from path

Definition at line 203 of file str.c.

str_common_prefix()

CT_NODISCARD CT_STD_API const char* str_common_prefix	(	const vector_t *	args,
		arena_t *	arena
	)

find the longest common prefix of a vector of paths

Note

if no common prefix is found, the empty string is returned.

Parameters

args	the vector of paths to find the common prefix of
arena	the arena to allocate the common prefix in

Returns

the common prefix

modified version of https://rosettacode.org/wiki/Longest_common_prefix#C

expects a list of file paths

Definition at line 790 of file str.c.

str_contains()

CT_NODISCARD CT_PUREFN CT_STD_API bool str_contains	(	const char *	str,
		const char *	search
	)

check if a string contains a substring

Parameters

str	the string to search
search	the substring to search for

Returns

if sub is found in str

Definition at line 607 of file str.c.

str_directory()

CT_NODISCARD CT_STD_API char* str_directory	(	const char *	path,
		arena_t *	arena
	)

get the directory segment of a path

Parameters

path	the path to get the directory from
arena	the arena to allocate the directory in

Returns

the directory extracted from path

Definition at line 188 of file str.c.

str_endswith()

CT_NODISCARD CT_PUREFN CT_STD_API bool str_endswith	(	const char *	str,
		const char *	suffix
	)

check if a string ends with a substring

Parameters

str	the string to search
suffix	the suffix to check for

Returns

if str ends with suffix

Definition at line 242 of file str.c.

str_endswithn()

CT_NODISCARD CT_PUREFN CT_STD_API bool str_endswithn	(	STA_READS(len) const char *	str,
		size_t	len,
		const char *	suffix
	)

check if a string ends with a substring

equivalent to str_endswith but with a length parameter

Parameters

str	the string to search
len	the length of the string
suffix	the suffix to check for

Returns

if str ends with suffix

str_erase()

CT_NODISCARD CT_NOALIAS CT_STD_API char* str_erase	(	STA_READS(len) char *	str,
		size_t	len,
		const char *	letters
	)

remove all instances of letters from str

Parameters

str	the string to erase letters from
len	the length of str
letters	the letters to erase

Returns

str with all instances of letters removed

str_ext()

CT_NODISCARD CT_STD_API char* str_ext	(	const char *	path,
		arena_t *	arena
	)

get the last file extension from a path

Parameters

path	the path to get the extension from
arena	the arena to allocate the extension in

Returns

the last extension in path

Definition at line 173 of file str.c.

str_filename()

CT_NODISCARD CT_STD_API char* str_filename	(	const char *	path,
		arena_t *	arena
	)

get the filename from a path

Parameters

path	the path to get the filename from
arena	the arena to allocate the filename in

Returns

the filename extracted from path

Definition at line 218 of file str.c.

str_find()

CT_PUREFN CT_STD_API size_t str_find	(	const char *	str,
		const char *	sub
	)

find the first instance of a substring in a string

Parameters

str	the string to search
sub	the substring to search for

Returns

the index of the first instance of sub in str, or SIZE_MAX if sub is not found

Definition at line 896 of file str.c.

str_join()

CT_NODISCARD CT_STD_API char* str_join	(	const char *	sep,
		const vector_t *	parts,
		arena_t *	arena
	)

join strings

join a vector of strings together with a separator

Parameters

sep	the separator to use
parts	a vector of strings to join
arena	the arena to allocate the joined string in

Returns

the joined string

Definition at line 274 of file str.c.

str_lower()

CT_NODISCARD CT_STD_API char* str_lower	(	const char *	str,
		arena_t *	arena
	)

lowercase an ascii string this allocates a new string in the provided arena

Parameters

str	the string
arena	the arena to allocate the lowercase string in

Returns

str with all uppercase charaters replaced with lowercase

Definition at line 952 of file str.c.

str_noext()

CT_NODISCARD CT_STD_API char* str_noext	(	const char *	path,
		arena_t *	arena
	)

remove the last file extension from a path

Parameters

path	the path to remove the extension from
arena	the arena to allocate the path in

Returns

the path with the last extension removed

Definition at line 156 of file str.c.

str_normalize()

CT_NODISCARD CT_STD_API char* str_normalize	(	const char *	str,
		arena_t *	arena
	)

turn a string into a C string literal

normalize a string into a valid C string literal

Parameters

str	the string to normalize
arena	the arena to allocate the normalized string in

Returns

the normalized string

Definition at line 485 of file str.c.

str_normalize_into()

CT_STD_API size_t str_normalize_into	(	STA_WRITES(len) char *	dst,
		size_t	dstlen,
		STA_READS(srclen) const char *	src,
		size_t	srclen
	)

normalize a string into a buffer

normalize a string into a buffer. if dst is NULL, the length of the normalized string is returned.

Parameters

dst	the buffer to write the normalized string into
dstlen	the length of the buffer
src	the string to normalize
srclen	the length of the string

Returns

the number of characters written

str_normalizen()

CT_NODISCARD CT_STD_API char* str_normalizen	(	text_view_t	text,
		arena_t *	arena
	)

turn a string with length into a C string literal

normalize a string with length into a valid C string literal

Parameters

text	the text to normalize
arena	the arena to allocate the normalized string in

Returns

the normalized string

Definition at line 524 of file str.c.

str_repeat()

CT_NODISCARD CT_STD_API char* str_repeat	(	const char *	str,
		size_t	times,
		arena_t *	arena
	)

repeat a string

repeat a string n times

Parameters

str	the string to repeat
times	the number of times to repeat
arena	the arena to allocate the repeated string in

Returns

the repeated string

Definition at line 336 of file str.c.

str_replace()

CT_NODISCARD CT_STD_API char* str_replace	(	const char *	str,
		const char *	search,
		const char *	repl,
		arena_t *	arena
	)

replace all instances of a substring in a string

Parameters

str	the string to replace elements in
search	the substring to replace
repl	the replacement substring
arena	the arena to allocate the new string in

Returns

a copy of str with all instances of search replaced with repl

Definition at line 616 of file str.c.

str_replace_inplace()

CT_STD_API void str_replace_inplace	(	INOUT_NOTNULL text_t *	text,
		const char *	search,
		const char *	repl
	)

replace all instances of a substring in a string in place

Parameters

text	the text to replace elements in
search	the substring to replace
repl	the replacement substring

str_replace_many()

CT_NODISCARD CT_STD_API char* str_replace_many	(	const char *	str,
		const map_t *	repl,
		arena_t *	arena
	)

replace all instances of a each substring in a string with provided replacement

Parameters

str	the string to replace elements in
repl	a map of substrings to replace and their replacements
arena	the arena to allocate the new string in

Returns

a copy of str with all instances of substrings in repl replaced

Definition at line 736 of file str.c.

str_rfind()

CT_PUREFN CT_STD_API size_t str_rfind	(	const char *	str,
		const char *	sub
	)

find the last instance of a substring in a string

Parameters

str	the string to search
sub	the substring to search for

Returns

the index of the last instance of sub in str, or SIZE_MAX if sub is not found

Definition at line 884 of file str.c.

str_rfind_any()

CT_PUREFN CT_STD_API size_t str_rfind_any	(	const char *	str,
		const char *	letters
	)

find the first instance of a set of characters in a string

Parameters

str	the string to search
letters	the characters to search for

Returns

the index of the first instance of any character in letters in str, or SIZE_MAX if no character is found

Definition at line 137 of file str.c.

str_sort_inplace()

CT_STD_API void str_sort_inplace	(	STA_UPDATES(len) char *	str,
		size_t	len
	)

sort a strings contents in place

Parameters

str	the string to sort
len	the length of the string

str_split()

CT_NODISCARD CT_STD_API vector_t* str_split	(	const char *	str,
		const char *	sep,
		arena_t *	arena
	)

split a string into a vector by a separator

Note

the seperator is not included in the resulting substrings.

if no separator is found, the entire string is returned in the vectors first element.

Parameters

str	the string to split
sep	the separator to split by
arena	the arena to allocate the substrings in

Returns

the substrings

Definition at line 557 of file str.c.

str_sprintf()

CT_STD_API size_t str_sprintf	(	STA_WRITES(len) char *	str,
		size_t	len,
		STA_FORMAT_STRING const char *	fmt,
			...
	)

format a string with printf-like syntax

format a string with printf-like syntax into a text buffer.

Precondition

str is a pointer to a buffer of at least len bytes

fmt is a valid format string

Parameters

str	the buffer to format into
len	the length of the buffer
fmt	the format string
...	the arguments to format

Returns

the number of characters written

str_startswith()

CT_NODISCARD CT_PUREFN CT_STD_API bool str_startswith	(	const char *	str,
		const char *	prefix
	)

see if a string starts with a prefix

Parameters

str	the string to search
prefix	the prefix to check for

Returns

if str starts with prefix

Definition at line 233 of file str.c.

str_tolower()

CT_NODISCARD CT_CONSTFN CT_STD_API char str_tolower

(

char

c

)

get the lowercase version of a character

Parameters

c	the character

Returns

the lowercase version of c, or the character itself

Definition at line 970 of file str.c.

str_toupper()

CT_NODISCARD CT_CONSTFN CT_STD_API char str_toupper

(

char

c

)

get the uppercase version of a character

Parameters

c	the character

Returns

the uppercase version of c or the character itself

Definition at line 981 of file str.c.

str_trim_back_inplace()

CT_STD_API void str_trim_back_inplace	(	INOUT_NOTNULL text_t *	text,
		const char *	chars
	)

trim chars from the back of a string in place

Parameters

text	the text to trim
chars	the characters to trim

str_upper()

CT_NODISCARD CT_STD_API char* str_upper	(	const char *	str,
		arena_t *	arena
	)

uppercase an ascii string

Parameters

str	the string
arena	the arena to allocate the uppercase string in

Returns

str with all lowercase charaters replaced with uppercase

Definition at line 934 of file str.c.

str_vformat()

CT_NODISCARD STA_FORMAT_STRING const char CT_NODISCARD CT_STD_API char* str_vformat	(	arena_t *	arena,
		const char *	fmt,
		va_list	args
	)

format a string

format a string with a va_list and printf-like syntax

Parameters

arena	the arena to allocate the formatted string in
fmt	the format string
args	the arguments to format

Returns

the formatted string

Definition at line 110 of file str.c.

str_vsprintf()

CT_STD_API size_t str_vsprintf	(	STA_WRITES(len) char *	str,
		size_t	len,
		const char *	fmt,
		va_list	args
	)

format a string with printf-like syntax

format a string with a va_list and printf-like syntax into a text buffer.

Precondition

str is a pointer to a buffer of at least len bytes

fmt is a valid format string

Parameters

str	the buffer to format into
len	the length of the buffer
fmt	the format string
args	the arguments to format

Returns

the number of characters written

text_vformat()

CT_NODISCARD STA_FORMAT_STRING const char CT_NODISCARD CT_STD_API text_t text_vformat	(	arena_t *	arena,
		const char *	fmt,
		va_list	args
	)

format a string

format a string with a va_list and printf-like syntax into a text buffer. useful when you need the length of the formatted string.

Parameters

arena	the arena to allocate the formatted string in
fmt	the format string
args	the arguments to format

Returns

the formatted string

Definition at line 56 of file str.c.

text_view_equal()

CT_NODISCARD CT_STD_API bool text_view_equal	(	text_view_t	lhs,
		text_view_t	rhs
	)

check if two strings are equal

Parameters

lhs	the left hand side of the comparison
rhs	the right hand side of the comparison

Returns

if the strings are equal

Definition at line 992 of file str.c.

Variable Documentation

fmt

CT_NODISCARD STA_FORMAT_STRING const char * fmt

Definition at line 68 of file str.h.