String Parsing and Joining

Functions
char *	M_str_split_on_char (char *s, char c)
char **	M_str_explode (unsigned char delim, const char *s, size_t s_len, size_t *num, size_t **len_array) M_WARN_UNUSED_RESULT M_MALLOC
char **	M_str_explode_quoted (unsigned char delim, const char *s, size_t s_len, unsigned char quote_char, unsigned char escape_char, size_t max_sects, size_t *num, size_t **len_array) M_WARN_UNUSED_RESULT M_MALLOC
char **	M_str_explode_str (unsigned char delim, const char *s, size_t *num) M_WARN_UNUSED_RESULT M_MALLOC
char **	M_str_explode_lines (size_t max_lines, size_t max_chars, const char *src_str, M_bool truncate, size_t *num) M_WARN_UNUSED_RESULT M_MALLOC
char **	M_str_explode_str_quoted (unsigned char delim, const char *s, unsigned char quote_char, unsigned char escape_char, size_t max_sects, size_t *num) M_WARN_UNUSED_RESULT M_MALLOC
int *	M_str_explode_int (unsigned char delim, const char *s, size_t *num) M_WARN_UNUSED_RESULT M_MALLOC
void	M_str_explode_free (char **strs, size_t num) M_FREE(1)
char *	M_str_implode (unsigned char delim, unsigned char enclose_char, unsigned char escape_char, char **strs, size_t num_strs, M_bool always_enclose) M_WARN_UNUSED_RESULT M_MALLOC
char *	M_str_implode_int (unsigned char delim, const int *ints, size_t num_ints) M_WARN_UNUSED_RESULT M_MALLOC

Detailed Description

String Parsing and Joining Functions

Function Documentation

M_str_split_on_char()

char * M_str_split_on_char	(	char *	s,
		char	c
	)

Clobber the first occurrence of character c in string s with NULL and return a pointer to the successive character.

Parameters

[in]	s	String to break into segments.
[in]	c	Character at which to break into segments.

Returns

NULL if s is NULL. Pointer to trailing NULL if c not found in s. Otherwise pointer to the character following the first occurrence of c in s.

M_str_explode()

char ** M_str_explode	(	unsigned char	delim,
		const char *	s,
		size_t	s_len,
		size_t *	num,
		size_t **	len_array
	)

Find each substring of s delimited by delim and additionally record each substring's length.

The string can contain the character '\0' and will be processed up to s_len. All parts will be NULL terminated.

Empty list elements (consecutive delimiters) will produce empty strings in the output array.

The last length of len_array will include any trailing '\0'.

Parameters

[in]	delim	Delimiter.
[in]	s	String to search.
[in]	s_len	Length of string.
[out]	num	The size of len_array and the returned array.
[out]	len_array	An array of size num containing the lengths of the substrings.

Returns

an array of length num containing all substrings.

M_str_explode_quoted()

char ** M_str_explode_quoted	(	unsigned char	delim,
		const char *	s,
		size_t	s_len,
		unsigned char	quote_char,
		unsigned char	escape_char,
		size_t	max_sects,
		size_t *	num,
		size_t **	len_array
	)

Find each substring of s taking into account quoting.

The string can contain the character '\0' and will be processed up to s_len. All parts are guaranteed to be NULL terminated. This takes into account if the delimiter is within a quote. Also allows the quote character to be escaped and not treated as a quote character.

An example of this would be CSV parsing. ',' is a delimiter but if it's in '"' it is not. " within a " is escaped with " to denote that isn't the end of the quote.

Empty list elements (consecutive delimiters) will produce empty strings in the output array.

Parameters

[in]	delim	Delimiter.
[in]	s	String to search.
[in]	s_len	Length of string.
[in]	quote_char	Character to use to denote quoted segments. Use 0 if not needed.
[in]	escape_char	Character to use for escaping the quote character. Can be the same as the quote character. use 0 if not needed.
[in]	max_sects	Maximum number of parts to return. The last part will have remaining data after last allowed split. Use 0 to disable and return all parts.
[out]	num	the size of len_array and the returned array.
[out]	len_array	An array of size num containing the lengths of the substrings.

Returns

an array of num string containing all substrings.

M_str_explode_str()

char ** M_str_explode_str	(	unsigned char	delim,
		const char *	s,
		size_t *	num
	)

Find each substring of s (a NULL terminated string).

s will only be read until the first NULL. All parts are guaranteed to be NULL terminated.

Empty list elements (consecutive delimiters) will produce empty strings in the output array.

Parameters

[in]	delim	Delimiter.
[in]	s	String to search.
[out]	num	Number of substrings in returned array.

Returns

an array of num string containing all substrings.

M_str_explode_lines()

char ** M_str_explode_lines	(	size_t	max_lines,
		size_t	max_chars,
		const char *	src_str,
		M_bool	truncate,
		size_t *	num
	)

Split a string among the given number of lines, while keeping words intact.

After you're done with the returned array, you must free it with M_str_explode_free().

Words in this context are defined as contiguous blocks of non-whitespace characters. For each line, leading and trailing whitespace will be trimmed, but internal whitespace will be left alone.

An example use case is breaking up strings for display on small LCD screens.

See also

M_str_explode_free

M_buf_add_str_lines

Parameters

[in]	max_lines	Maximum number of lines to output.
[in]	max_chars	Maximum characters per line.
[in]	src_str	Source string.
[in]	truncate	If true, truncation is allowed. If false, NULL will be returned if the string won't fit.
[out]	num	Number of lines displayed. Will be zero, if no output text was produced.

Returns

Array of strings where each is a line, or NULL if no output text was produced.

M_str_explode_str_quoted()

char ** M_str_explode_str_quoted	(	unsigned char	delim,
		const char *	s,
		unsigned char	quote_char,
		unsigned char	escape_char,
		size_t	max_sects,
		size_t *	num
	)

Find each substring of s (a NULL terminated string) taking into account quoting.

s will only be read until the first NULL. All parts are guaranteed to be NULL terminated. This takes into account if the delimiter is within a quote. Also allows the quote character to be escaped and not treated as a quote character.

An example of this would be CSV parsing. ',' is a delimiter but if it's in '"' it is not. " within a " is escaped with " to denote that isn't the end of the quote.

Parameters

[in]	delim	Delimiter.
[in]	s	String to search.
[in]	quote_char	Character to use to denote quoted segments. Use 0 if not needed.
[in]	escape_char	Character to use for escaping the quote character. Can be the same as the quote character. use 0 if not needed.
[in]	max_sects	Maximum number of parts to return. The last part will have remaining data after last allowed split. Use 0 to disable and return all parts.
[out]	num	the size of len_array and the returned array.

Returns

an array of num string containing all substrings.

M_str_explode_int()

int * M_str_explode_int	(	unsigned char	delim,
		const char *	s,
		size_t *	num
	)

Given a string containing an list of integers delimited by delim, return an array containing the integer values.

For example, after calling: ints = M_str_explode_int(',', "-10,11,13,,,,-15", &num) then the returns values will be: num=4 ints[0] = -10 ints[1] = 11 ints[2] = 13 ints[3] = -15

Parameters

[in]	delim	Delimiter.
[in]	s	String containing the integer list.
[out]	num	The number of integers in the returned array.

Returns

an array containing num integers.

M_str_explode_free()

void M_str_explode_free	(	char **	strs,
		size_t	num
	)

Free the substrings found by M_str_explode*.

Parameters

[in]	strs	An array of strings returned by M_str_explode*.
[in]	num	The number of strings in strs.

See also

M_str_explode

M_str_implode()

char * M_str_implode	(	unsigned char	delim,
		unsigned char	enclose_char,
		unsigned char	escape_char,
		char **	strs,
		size_t	num_strs,
		M_bool	always_enclose
	)

Join an array of string separated by a delimiter and quoted if the delimiter is present in a string.

Parameters

[in]	delim	Delimiter.
[in]	enclose_char	Character to use for quoting.
[in]	escape_char	Character used for escaping the quote character if it's found in a string.
[in]	strs	array of string to join.
[in]	num_strs	Number of string in the array of strings.
[in]	always_enclose	M_TRUE if all string should be quoted. M_FALSE if strings are only quoted when necessary.

Returns

Joined string.

M_str_implode_int()

char * M_str_implode_int	(	unsigned char	delim,
		const int *	ints,
		size_t	num_ints
	)

Convert an array of signed integers into a string representation where each integer is delimited by a given character.

For example: M_str_implode_int('|', {1,-22,333}, 3) => "1|-22|333"

Parameters

[in]	delim	Delimiter.
[in]	ints	String containing the integer list.
[in]	num_ints	The number of integers in the returned array.

Returns

String representation of integer list.