Strings

Functions
void	str_append (char *dst, const char *src, int dst_size)
template<int N>
void	str_append (char(&dst)[N], const char *src)
int	str_copy (char *dst, const char *src, int dst_size)
template<int N>
void	str_copy (char(&dst)[N], const char *src)
void	str_utf8_truncate (char *dst, int dst_size, const char *src, int truncation_len)
void	str_truncate (char *dst, int dst_size, const char *src, int truncation_len)
int	str_length (const char *str)
int	str_format_v (char *buffer, int buffer_size, const char *format, va_list args)
int	str_format (char *buffer, int buffer_size, const char *format,...)
const char *	str_trim_words (const char *str, int words)
bool	str_has_cc (const char *str)
void	str_sanitize_cc (char *str)
void	str_sanitize (char *str)
void	str_clean_whitespaces (char *str)
char *	str_skip_to_whitespace (char *str)
const char *	str_skip_to_whitespace_const (const char *str)
char *	str_skip_whitespaces (char *str)
const char *	str_skip_whitespaces_const (const char *str)
int	str_comp_nocase (const char *a, const char *b)
int	str_comp_nocase_num (const char *a, const char *b, int num)
int	str_comp (const char *a, const char *b)
int	str_comp_num (const char *a, const char *b, int num)
int	str_comp_filenames (const char *a, const char *b)
const char *	str_startswith (const char *str, const char *prefix)
int	str_utf8_dist_buffer (const char *a, const char *b, int *buf, int buf_len)
bool	str_delimiters_around_offset (const char *haystay, const char *delim, int offset, int *start, int *end)
const char *	str_rchr (const char *haystack, char needle)
int	str_countchr (const char *haystack, char needle)
int	str_isspace (char c)

Detailed Description

String related functions.

Function Documentation

str_append() [1/2]

void str_append	(	char *	dst,
		const char *	src,
		int	dst_size
	)

Appends a string to another.

Parameters

dst	Pointer to a buffer that contains a string.
src	String to append.
dst_size	Size of the buffer of the dst string.

Remarks

The strings are treated as zero-terminated strings.

Guarantees that dst string will contain zero-termination.

str_append() [2/2]

template<int N>

void str_append	(	char(&)	dst[N],
		const char *	src
	)

Appends a string to a fixed-size array of chars.

Parameters

dst	Array that shall receive the string.
src	String to append.

Remarks

The strings are treated as zero-terminated strings.

Guarantees that dst string will contain zero-termination.

str_clean_whitespaces()

void str_clean_whitespaces

(

char *

str

)

Removes leading and trailing spaces and limits the use of multiple spaces.

Parameters

str	String to clean up

Remarks

The strings are treated as zero-terminated strings.

str_comp()

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

Compares two strings case sensitive.

Parameters

a	String to compare.
b	String to compare.

Returns

< 0 - String a is less than string b

0 - String a is equal to string b

> 0 - String a is greater than string b

Remarks

The strings are treated as zero-terminated strings.

str_comp_filenames()

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

Compares two strings case insensitive, digit chars will be compared as numbers.

Parameters

a	String to compare.
b	String to compare.

Returns

< 0 - String a is less than string b

0 - String a is equal to string b

> 0 - String a is greater than string b

Remarks

The strings are treated as zero-terminated strings.

str_comp_nocase()

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

Compares to strings case insensitively.

Parameters

a	String to compare.
b	String to compare.

Returns

< 0 - String a is less than string b

0 - String a is equal to string b

> 0 - String a is greater than string b

Remarks

Only guaranteed to work with a-z/A-Z.

The strings are treated as zero-terminated strings.

str_comp_nocase_num()

int str_comp_nocase_num	(	const char *	a,
		const char *	b,
		int	num
	)

Compares up to num characters of two strings case insensitively.

Parameters

a	String to compare.
b	String to compare.
num	Maximum characters to compare

Returns

< 0 - String a is less than string b

0 - String a is equal to string b

> 0 - String a is greater than string b

Remarks

Only guaranteed to work with a-z/A-Z. (use str_utf8_comp_nocase_num for unicode support)

The strings are treated as zero-terminated strings.

str_comp_num()

int str_comp_num	(	const char *	a,
		const char *	b,
		int	num
	)

Compares up to num characters of two strings case sensitive.

Parameters

a	String to compare.
b	String to compare.
num	Maximum characters to compare

Returns

< 0 - String a is less than string b

0 - String a is equal to string b

> 0 - String a is greater than string b

Remarks

The strings are treated as zero-terminated strings.

str_copy() [1/2]

int str_copy	(	char *	dst,
		const char *	src,
		int	dst_size
	)

Copies a string to another.

Parameters

dst	Pointer to a buffer that shall receive the string.
src	String to be copied.
dst_size	Size of the buffer dst.

Returns

Length of written string, even if it has been truncated

Remarks

The strings are treated as zero-terminated strings.

Guarantees that dst string will contain zero-termination.

str_copy() [2/2]

template<int N>

void str_copy	(	char(&)	dst[N],
		const char *	src
	)

Copies a string to a fixed-size array of chars.

Parameters

dst	Array that shall receive the string.
src	String to be copied.

Remarks

The strings are treated as zero-terminated strings.

Guarantees that dst string will contain zero-termination.

str_countchr()

int str_countchr	(	const char *	haystack,
		char	needle
	)

Counts the number of occurrences of a character in a string.

Parameters

haystack	String to count in
needle	Character to count

Returns

The number of characters in the haystack string matching the needle character.

Remarks

The strings are treated as zero-terminated strings.

The number of zero-terminator characters cannot be counted.

str_delimiters_around_offset()

bool str_delimiters_around_offset	(	const char *	haystay,
		const char *	delim,
		int	offset,
		int *	start,
		int *	end
	)

Parameters

haystack	String to search in
delim	String to search for
offset	Number of characters into the haystack
start	Will be set to the first delimiter on the left side of the offset (or haystack start)
end	Will be set to the first delimiter on the right side of the offset (or haystack end)

Returns

true if both delimiters were found

'false' if a delimiter is missing (it uses haystack start and end as fallback)

Remarks

The strings are treated as zero-terminated strings.

str_format()

int str_format	(	char *	buffer,
		int	buffer_size,
		const char *	format,
			...
	)

Performs printf formatting into a buffer.

Parameters

buffer	Pointer to the buffer to receive the formatted string.
buffer_size	Size of the buffer.
format	printf formatting string.
...	Parameters for the formatting.

Returns

Length of written string, even if it has been truncated.

Remarks

See the C manual for syntax for the printf formatting string.

The strings are treated as zero-terminated strings.

Guarantees that buffer string will contain zero-termination.

str_format_v()

int str_format_v	(	char *	buffer,
		int	buffer_size,
		const char *	format,
		va_list	args
	)

Performs printf formatting into a buffer.

Parameters

buffer	Pointer to the buffer to receive the formatted string.
buffer_size	Size of the buffer.
format	printf formatting string.
args	The variable argument list.

Returns

Length of written string, even if it has been truncated.

Remarks

See the C manual for syntax for the printf formatting string.

The strings are treated as zero-terminated strings.

Guarantees that buffer string will contain zero-termination.

str_has_cc()

bool str_has_cc

(

const char *

str

)

Check whether string has ASCII control characters.

Parameters

str	String to check.

Returns

Whether the string has ASCII control characters.

Remarks

The strings are treated as zero-terminated strings.

str_isspace()

int str_isspace

(

char

c

)

Determines whether a character is whitespace.

Parameters

c	the character to check

Returns

1 if the character is whitespace, 0 otherwise.

Remarks

The following characters are considered whitespace: ' ', '
', '\r', '\t'

str_length()

int str_length

(

const char *

str

)

Returns the length of a zero terminated string.

Parameters

str	Pointer to the string.

Returns

Length of string in bytes excluding the zero termination.

str_rchr()

const char * str_rchr	(	const char *	haystack,
		char	needle
	)

Finds the last occurrence of a character

Parameters

haystack	String to search in
needle	Character to search for

Returns

A pointer into haystack where the needle was found. Returns NULL if needle could not be found.

Remarks

The strings are treated as zero-terminated strings.

The zero-terminator character can also be found with this function.

str_sanitize()

void str_sanitize

(

char *

str

)

Replaces all characters below 32 with whitespace with exception to \t,
and \r.

Parameters

str	String to sanitize.

Remarks

The strings are treated as zero-terminated strings.

str_sanitize_cc()

void str_sanitize_cc

(

char *

str

)

Replaces all characters below 32 with whitespace.

Parameters

str	String to sanitize.

Remarks

The strings are treated as zero-terminated strings.

str_skip_to_whitespace()

char * str_skip_to_whitespace

(

char *

str

)

Skips leading non-whitespace characters.

Parameters

str	Pointer to the string.

Returns

Pointer to the first whitespace character found within the string.

Remarks

The strings are treated as zero-terminated strings.

Whitespace is defined according to str_isspace.

str_skip_to_whitespace_const()

const char * str_skip_to_whitespace_const

(

const char *

str

)

See also

str_skip_to_whitespace

str_skip_whitespaces()

char * str_skip_whitespaces

(

char *

str

)

Skips leading whitespace characters.

Parameters

str	Pointer to the string.

Pointer to the first non-whitespace character found within the string.

Remarks

The strings are treated as zero-terminated strings.

Whitespace is defined according to str_isspace.

str_skip_whitespaces_const()

const char * str_skip_whitespaces_const

(

const char *

str

)

See also

str_skip_whitespaces

str_startswith()

const char * str_startswith	(	const char *	str,
		const char *	prefix
	)

Checks case sensitive whether the string begins with a certain prefix.

Parameters

str	String to check.
prefix	Prefix to look for.

Returns

A pointer to the string str after the string prefix, or 0 if the string prefix isn't a prefix of the string str.

Remarks

The strings are treated as zero-terminated strings.

str_trim_words()

const char * str_trim_words	(	const char *	str,
		int	words
	)

Trims specific number of words at the start of a string.

Parameters

str	String to trim the words from.
words	Count of words to trim.

Returns

Trimmed string

Remarks

The strings are treated as zero-terminated strings.

Leading whitespace is always trimmed.

str_truncate()

void str_truncate	(	char *	dst,
		int	dst_size,
		const char *	src,
		int	truncation_len
	)

Truncates a string to a given length.

Parameters

dst	Pointer to a buffer that shall receive the string.
dst_size	Size of the buffer dst.
src	String to be truncated.
truncation_len	Maximum length of the returned string (not counting the zero termination).

Remarks

The strings are treated as zero-terminated strings.

Guarantees that dst string will contain zero-termination.

str_utf8_dist_buffer()

int str_utf8_dist_buffer	(	const char *	a,
		const char *	b,
		int *	buf,
		int	buf_len
	)

Computes the edit distance between two strings, allows buffers to be passed in.

Parameters

a	- First string for the edit distance.
b	- Second string for the edit distance.
buf	- Buffer for the function.
buf_len	Length of the buffer, must be at least as long as twice the length of both strings combined plus two.

Returns

The edit distance between the both strings.

Remarks

The strings are treated as zero-terminated strings.

str_utf8_truncate()

void str_utf8_truncate	(	char *	dst,
		int	dst_size,
		const char *	src,
		int	truncation_len
	)

Truncates a utf8 encoded string to a given length.

Parameters

dst	Pointer to a buffer that shall receive the string.
dst_size	Size of the buffer dst.
str	String to be truncated.
truncation_len	Maximum codepoints in the returned string.

Remarks

The strings are treated as utf8-encoded zero-terminated strings.

Guarantees that dst string will contain zero-termination.