String Manipulation (in-place)

Functions
char *	M_str_lower (char *s)
char *	M_str_lower_max (char *s, size_t max)
char *	M_str_upper (char *s)
char *	M_str_upper_max (char *s, size_t max)
char *	M_str_title (char *s)
char *	M_str_title_max (char *s, size_t max)
char *	M_str_trim (char *s)
char *	M_str_trim_max (char *s, size_t max)
char *	M_str_remove_bracketed (const char *src, char open, char close) M_WARN_UNUSED_RESULT M_MALLOC
char *	M_str_remove_bracketed_quoted (const char *src, char open, char close, char quote, char escape) M_WARN_UNUSED_RESULT M_MALLOC
char *	M_str_keep_bracketed (const char *src, char open, char close) M_WARN_UNUSED_RESULT M_MALLOC
char *	M_str_keep_bracketed_quoted (const char *src, char open, char close, char quote, char escape) M_WARN_UNUSED_RESULT M_MALLOC
char *	M_str_remove_quoted (const char *src, char quote_char, char escape_char) M_WARN_UNUSED_RESULT M_MALLOC
char *	M_str_keep_quoted (const char *src, char quote_char, char escape_char) M_WARN_UNUSED_RESULT M_MALLOC
char *	M_str_unquote (char *s, unsigned char quote, unsigned char escape)
char *	M_str_unquote_max (char *s, unsigned char quote, unsigned char escape, size_t max)
char *	M_str_quote (const char *s, unsigned char quote, unsigned char escape) M_WARN_UNUSED_RESULT M_MALLOC
char *	M_str_quote_max (const char *s, unsigned char quote, unsigned char escape, size_t max) M_WARN_UNUSED_RESULT M_MALLOC
M_bool	M_str_quote_if_necessary (char **out, const char *s, unsigned char quote, unsigned char escape, unsigned char delim)
char *	M_str_delete_spaces (char *s)
char *	M_str_delete_newlines (char *s)
char *	M_str_replace_chr (char *s, char b, char a)
size_t	M_str_justify (char *dest, size_t destlen, const char *src, M_str_justify_type_t justtype, unsigned char justchar, size_t justlen)
size_t	M_str_justify_max (char *dest, size_t destlen, const char *src, size_t srclen, M_str_justify_type_t justtype, unsigned char justchar, size_t justlen)
M_bool	M_str_cpy (char *dest, size_t dest_len, const char *src)
M_bool	M_str_cpy_max (char *dest, size_t dest_len, const char *src, size_t src_len)
M_bool	M_str_cat (char *dest, size_t dest_len, const char *src)

Detailed Description

String Manipulation (in-place)) Functions

Function Documentation

M_str_lower()

char * M_str_lower

(

char *

s

)

Convert all characters in place to lower case.

Parameters

[in,out]

s

NULL-terminated string.

Returns

pointer to string on success. Otherwise NULL.

M_str_lower_max()

char * M_str_lower_max	(	char *	s,
		size_t	max
	)

Convert all characters in place to lower case up to a maximum length.

Parameters

[in,out]	s	NULL-terminated string.
[in]	max	Max length to convert.

Returns

pointer to string on success. Otherwise NULL.

M_str_upper()

char * M_str_upper

(

char *

s

)

Convert all characters in place to upper case.

Parameters

[in,out]

s

NULL-terminated string.

Returns

Pointer to string on success. Otherwise NULL.

M_str_upper_max()

char * M_str_upper_max	(	char *	s,
		size_t	max
	)

Convert all characters in place to upper case up to a maximum length.

Parameters

[in,out]	s	NULL-terminated string.
[in]	max	max Max length to convert.

Returns

Pointer to string on success. Otherwise NULL.

M_str_title()

char * M_str_title

(

char *

s

)

Convert all characters to title case, in-place.

Title case is where the first letter of each word is converted to uppercase, and all other letters are converted to lowercase.

Ex: "This Sentence Is In Title Case"

See also

M_str_title_max

M_strdup_title

Parameters

[in,out]

s

null-terminated string to convert.

Returns

s on success, NULL on failure.

M_str_title_max()

char * M_str_title_max	(	char *	s,
		size_t	max
	)

Convert given number of characters to title case, in-place.

Title case is where the first letter of each word is converted to uppercase, and all other letters are converted to lowercase.

Ex: "This Sentence Is In Title Case!"

See also

M_str_title

M_strdup_title_max

Parameters

s	string to convert (doesn't have to be null-terminated, but must be at least max long)
max	max number of characters to touch in s, may be less if s contains a null character

Returns

s on success, NULL on failure.

M_str_trim()

char * M_str_trim

(

char *

s

)

Remove whitespace from the beginning and end of the string in place.

Parameters

[in,out]

s

NULL-terminated string.

Returns

Start of the string without whitespace.

See also

M_chr_isspace

M_str_trim_max()

char * M_str_trim_max	(	char *	s,
		size_t	max
	)

Remove whitespace from the beginning and end of the string in place up to a maximum length.

Parameters

[in,out]	s	NULL-terminated string.
[in]	max	Max length to trim.

Returns

the start of the string without whitespace.

See also

M_chr_isspace

M_str_remove_bracketed()

char * M_str_remove_bracketed	(	const char *	src,
		char	open,
		char	close
	)

Return a copy of the given string with bracketed expressions removed.

You must use different characters for open and close. If you pass the same character for both, this function will return NULL.

For example, the string "abc (asd(e))?" becomes "abc ?" after calling this function with '(' as the open bracket and ')' as the close bracket.

See also

M_str_remove_bracketed_quoted

M_str_keep_bracketed

M_str_remove_quoted

Parameters

[in]	src	string to copy
[in]	open	character that represents the start of a bracketed expression
[in]	close	character that represents the end of a bracketed expression

Returns

copy of input string, with bracketed expressions removed

M_str_remove_bracketed_quoted()

char * M_str_remove_bracketed_quoted	(	const char *	src,
		char	open,
		char	close,
		char	quote,
		char	escape
	)

Return a copy of the given string with bracketed expressions removed.

Brackets inside quoted expressions are ignored.

You must use different characters for open and close. If you pass the same character for both, this function will return NULL.

For example, the string "abc (asd(e))?" becomes "abc ?" after calling this function with '(' as the open bracket and ')' as the close bracket.

See also

M_str_remove_bracketed_quoted

M_str_keep_bracketed

M_str_remove_quoted

Parameters

[in]	src	string to copy
[in]	open	character that represents the start of a bracketed expression
[in]	close	character that represents the end of a bracketed expression
[in]	quote	character that represents open/close of quoted string
[in]	escape	character that can be used to escape a quote char

Returns

copy of input string, with bracketed expressions removed

M_str_keep_bracketed()

char * M_str_keep_bracketed	(	const char *	src,
		char	open,
		char	close
	)

Return a copy of the given string with everything outside bracketed expressions removed.

You must use different characters for open and close. If you pass the same character for both, this function will return NULL.

For example, the string "abc (asd(e))?" becomes "asd(e)" after calling this function with '(' as the open bracket and ')' as the close bracket.

See also

M_str_keep_bracketed_quoted

M_str_remove_bracketed

M_str_keep_quoted

Parameters

[in]	src	string to copy
[in]	open	character that represents the start of a bracketed expression
[in]	close	character that represents the end of a bracketed expression

Returns

copy of input string, containing only the contents of bracketed expressions

M_str_keep_bracketed_quoted()

char * M_str_keep_bracketed_quoted	(	const char *	src,
		char	open,
		char	close,
		char	quote,
		char	escape
	)

Return a copy of the given string with everything outside bracketed expressions removed (quote aware).

Brackets inside quoted expressions are ignored.

You must use different characters for open and close. If you pass the same character for both, this function will return NULL.

For example, the string "abc (asd(e))?" becomes "asd(e)" after calling this function with '(' as the open bracket and ')' as the close bracket.

See also

M_str_keep_bracketed

M_str_remove_bracketed

M_str_keep_quoted

Parameters

[in]	src	string to copy
[in]	open	character that represents the start of a bracketed expression
[in]	close	character that represents the end of a bracketed expression
[in]	quote	character that represents open/close of quoted string
[in]	escape	character that can be used to escape a quote char

Returns

copy of input string, containing only the contents of bracketed expressions

M_str_remove_quoted()

char * M_str_remove_quoted	(	const char *	src,
		char	quote_char,
		char	escape_char
	)

Return a copy of the given string with quoted expressions removed.

Quote characters that are preceded by the escape character are not processed as quotes. If you don't wish to specify an escape character, pass '\0' for that argument.

Parameters

[in]	src	string to copy
[in]	quote_char	character that represents begin/end of a quoted section
[in]	escape_char	character that can be used to escape a quote char

Returns

copy of input string, with quoted expressions removed

M_str_keep_quoted()

char * M_str_keep_quoted	(	const char *	src,
		char	quote_char,
		char	escape_char
	)

Return a copy of the given string with everything outside quoted expressions removed.

Quote characters that are preceded by the escape character are not processed as quotes. If you don't wish to specify an escape character, pass '\0' for that argument.

Any escape character sequences ([escape][escape] or [escape][quote]) inside the quoted content are replaced by the characters they represent ([escape] or [quote], respectively).

Parameters

[in]	src	string to copy
[in]	quote_char	character that represents begin/end of a quoted section
[in]	escape_char	character that can be added

Returns

copy of input string, containing only the contents of quoted expressions

M_str_unquote()

char * M_str_unquote	(	char *	s,
		unsigned char	quote,
		unsigned char	escape
	)

Remove quotes from a string and unescape escaped quotes in place.

Parameters

[in,out]	s	NULL-terminated string.
[in]	quote	Quote character.
[in]	escape	Escape character. Removed from other escape characters and quotes.

Returns

Start of unquoted string.

M_str_unquote_max()

char * M_str_unquote_max	(	char *	s,
		unsigned char	quote,
		unsigned char	escape,
		size_t	max
	)

Remove quotes from a string and unescape escaped quotes in place up to a maximum length.

Parameters

[in,out]	s	NULL-terminated string.
[in]	quote	Quote character.
[in]	escape	Escape character. Removed from other escape characters and quotes.
[in]	max	Max length.

Returns

Start of unquoted string.

M_str_quote()

char * M_str_quote	(	const char *	s,
		unsigned char	quote,
		unsigned char	escape
	)

Quote a string

Parameters

[in]	s	NULL-terminated string.
[in]	quote	Quote character.
[in]	escape	Escape character.

Returns

Start of quoted string

M_str_quote_max()

char * M_str_quote_max	(	const char *	s,
		unsigned char	quote,
		unsigned char	escape,
		size_t	max
	)

Quote a string up to a maximum length.

Parameters

[in]	s	NULL-terminated string.
[in]	quote	Quote character.
[in]	escape	Escape character.
[in]	max	Max length.

Returns

Start of quoted string.

M_str_quote_if_necessary()

M_bool M_str_quote_if_necessary	(	char **	out,
		const char *	s,
		unsigned char	quote,
		unsigned char	escape,
		unsigned char	delim
	)

Quote a string only if necessary.

Quotes if the string starts or ends with a space. Or if the delimiter is found in the string.

Parameters

[out]	out	Quoted string.
[in]	s	NULL-terminated string.
[in]	quote	Quote character.
[in]	escape	Escape character.
[in]	delim	Delimiter.

Returns

M_TRUE if the string was quoted and out was set. Otherwise M_FALSE.

M_str_delete_spaces()

char * M_str_delete_spaces

(

char *

s

)

Delete all whitespace characters from the string.

Parameters

[in,out]

s

NULL-terminated string.

Returns

Start of string with whitespace removed.

See also

M_chr_isspace

M_str_delete_newlines()

char * M_str_delete_newlines

(

char *

s

)

Delete all newline characters (\r and \n) from the string.

Parameters

[in,out]

s

NULL-terminated string.

Returns

Start of string with newlines removed.

M_str_replace_chr()

char * M_str_replace_chr	(	char *	s,
		char	b,
		char	a
	)

Replace a character within a string with another character in place.

Parameters

[in]	s	NULL-terminated string.
[in]	b	Character to replace.
[in]	a	Character to replace with. b is replaced with a.

Returns

start of string with character replaced. Does not make a duplicate.

See also

M_strdup_replace_charset

M_strdup_replace_str

M_str_justify()

size_t M_str_justify	(	char *	dest,
		size_t	destlen,
		const char *	src,
		M_str_justify_type_t	justtype,
		unsigned char	justchar,
		size_t	justlen
	)

Justifies the input source as specified by the parameters and writes it to the destination buffer. Source and Destination buffers may overlap.

Parameters

[out]	dest	Destination buffer where the output is placed.
[in]	destlen	Length of destination buffer.
[in]	src	Input buffer to be justified.
[in]	justtype	Type of justification to be performed.
[in]	justchar	Character to use as padding/filler for justification (ignored if M_JUSTIFY_TRUNC_RIGHT or M_JUSTIFY_TRUNC_LEFT)
[in]	justlen	Length requested for justification (or truncation).

Returns

0 on error (such as if it would truncate when requested not to, or invalid use). Length of justified output on success (typically same as justlen, unless using M_JUSTIFY_TRUNC_RIGHT or M_JUSTIFY_TRUNC_LEFT).

M_str_justify_max()

size_t M_str_justify_max	(	char *	dest,
		size_t	destlen,
		const char *	src,
		size_t	srclen,
		M_str_justify_type_t	justtype,
		unsigned char	justchar,
		size_t	justlen
	)

Justifies the input source as specified by the parameters and writes it to the destination buffer. Source and destination buffers may overlap.

Parameters

[out]	dest	Destination buffer where the output is placed.
[in]	destlen	Length of destination buffer.
[in]	src	Input buffer to be justified.
[in]	srclen	Length of input source.
[in]	justtype	Type of justification to be performed.
[in]	justchar	Character to use as padding/filler for justification. (ignored if M_JUSTIFY_TRUNC_RIGHT or M_JUSTIFY_TRUNC_LEFT)
[in]	justlen	Length requested for justification (or truncation).

Returns

0 on error (such as if it would truncate when requested not to, or invalid use). Length of justified output on success (typically same as justlen, unless using M_JUSTIFY_TRUNC_RIGHT or M_JUSTIFY_TRUNC_LEFT).

M_str_cpy()

M_bool M_str_cpy	(	char *	dest,
		size_t	dest_len,
		const char *	src
	)

Copy a string from one location to another.

This guarantees NULL termination of dest.

Parameters

[out]	dest	Destination buffer where the output is placed.
[in]	dest_len	Length of destination buffer.
[in]	src	Input buffer.

Returns

M_TRUE on success otherwise M_FALSE.

M_str_cpy_max()

M_bool M_str_cpy_max	(	char *	dest,
		size_t	dest_len,
		const char *	src,
		size_t	src_len
	)

Copy a given length of a string from one location to another.

This guarantees NULL termination of dest.

Parameters

[out]	dest	Destination buffer where the output is placed.
[in]	dest_len	Length of destination buffer.
[in]	src	Input buffer.
[in]	src_len	Length of input buffer.

Returns

M_TRUE on success otherwise M_FALSE.

M_str_cat()

M_bool M_str_cat	(	char *	dest,
		size_t	dest_len,
		const char *	src
	)

Append a string on to another.

Parameters

[in,out]	dest	String to be appended to.
[in]	dest_len	The length of dest.
[in]	src	String to be appended.

Returns

M_TRUE if src was appended to dest. Otherwise M_FALSE.