Bounded string implementation. More...

#include "ucx.h"
#include "allocator.h"
#include <stddef.h>

Data Structures
struct	sstr_t
	The UCX string structure. More...

struct	scstr_t
	The UCX string structure for immutable (constant) strings. More...

Macros
#define	ST(s) { s, sizeof(s)-1 }
	Shortcut for a `sstr_t struct` or `scstr_t struct` literal.

#define	S(s) sstrn(s, sizeof(s)-1)
	Shortcut for the conversion of a C string to a `sstr_t`. More...

#define	SC(s) scstrn(s, sizeof(s)-1)
	Shortcut for the conversion of a C string to a `scstr_t`. More...

#define	SFMT(s) (int) (s).length, (s).ptr
	Expands a sstr_t or scstr_t to printf arguments. More...

#define	PRIsstr ".*s"
	Format specifier for a sstr_t or scstr_t. More...

#define	SCSTR(str) ucx_ss2c_s(str)
	Converts a UCX string to an immutable UCX string (scstr_t). More...

#define	sstrnlen(count, ...) scstrnlen(count, __VA_ARGS__)
	Returns the accumulated length of all specified strings. More...

#define	sstrcat(count, s1, ...) scstrcat(count, SCSTR(s1), __VA_ARGS__)
	Concatenates two or more strings. More...

#define	sstrcat_a(alloc, count, s1, ...) scstrcat_a(alloc, count, SCSTR(s1), __VA_ARGS__)
	Concatenates two or more strings using a UcxAllocator. More...

#define	sstrstr(string, match) scstrsstr(string, SCSTR(match))
	Returns a substring starting at the location of the first occurrence of the specified string. More...

#define	sstrscstr(string, match) scstrscstr(string, SCSTR(match))
	Returns an immutable substring starting at the location of the first occurrence of the specified immutable string. More...

#define	sstrsplit(string, delim, count) scstrsplit(SCSTR(string), SCSTR(delim), count)
	Splits a string into parts by using a delimiter string. More...

#define	sstrsplit_a(allocator, string, delim, count) scstrsplit_a(allocator, SCSTR(string), SCSTR(delim), count)
	Performing sstrsplit() using a UcxAllocator. More...

#define	sstrcmp(s1, s2) scstrcmp(SCSTR(s1), SCSTR(s2))
	Compares two UCX strings with standard `memcmp()`. More...

#define	sstrcasecmp(s1, s2) scstrcasecmp(SCSTR(s1), SCSTR(s2))
	Compares two UCX strings ignoring the case. More...

#define	sstrdup(string) scstrdup(SCSTR(string))
	Creates a duplicate of the specified string. More...

#define	sstrdup_a(allocator, string) scstrdup_a(allocator, SCSTR(string))
	Creates a duplicate of the specified string using a UcxAllocator. More...

#define	sstrprefix(string, prefix) scstrprefix(SCSTR(string), SCSTR(prefix))
	Checks, if a string has a specific prefix. More...

#define	sstrsuffix(string, suffix) scstrsuffix(SCSTR(string), SCSTR(suffix))
	Checks, if a string has a specific suffix. More...

#define	sstrcaseprefix(string, prefix) scstrcaseprefix(SCSTR(string), SCSTR(prefix))
	Checks, if a string has a specific prefix, ignoring the case. More...

#define	sstrcasesuffix(string, suffix) scstrcasesuffix(SCSTR(string), SCSTR(suffix))
	Checks, if a string has a specific suffix, ignoring the case. More...

#define	sstrlower(string) scstrlower(SCSTR(string))
	Returns a lower case version of a string. More...

#define	sstrlower_a(allocator, string) scstrlower_a(allocator, SCSTR(string))
	Returns a lower case version of a string. More...

#define	sstrupper(string) scstrupper(SCSTR(string))
	Returns a upper case version of a string. More...

#define	sstrupper_a(allocator, string) scstrupper_a(allocator, string)
	Returns a upper case version of a string. More...

Functions
scstr_t	ucx_sc2sc (scstr_t str)
	One of two type adjustment functions that return an scstr_t. More...

scstr_t	ucx_ss2sc (sstr_t str)
	One of two type adjustment functions that return an scstr_t. More...

scstr_t	ucx_ss2c_s ()
	Converts a UCX string to an immutable UCX string (scstr_t). More...

sstr_t	sstr (char *cstring)
	Creates a new sstr_t based on a C string. More...

sstr_t	sstrn (char *cstring, size_t length)
	Creates a new sstr_t of the specified length based on a C string. More...

scstr_t	scstr (const char *cstring)
	Creates a new scstr_t based on a constant C string. More...

scstr_t	scstrn (const char *cstring, size_t length)
	Creates a new scstr_t of the specified length based on a constant C string. More...

size_t	scstrnlen (size_t count,...)
	Returns the accumulated length of all specified strings. More...

sstr_t	scstrcat (size_t count, scstr_t s1,...)
	Concatenates two or more strings. More...

sstr_t	scstrcat_a (UcxAllocator *alloc, size_t count, scstr_t s1,...)
	Concatenates two or more strings using a UcxAllocator. More...

sstr_t	sstrsubs (sstr_t string, size_t start)
	Returns a substring starting at the specified location. More...

sstr_t	sstrsubsl (sstr_t string, size_t start, size_t length)
	Returns a substring with the given length starting at the specified location. More...

scstr_t	scstrsubs (scstr_t string, size_t start)
	Returns a substring of an immutable string starting at the specified location. More...

scstr_t	scstrsubsl (scstr_t string, size_t start, size_t length)
	Returns a substring of an immutable string with a maximum length starting at the specified location. More...

sstr_t	sstrchr (sstr_t string, int chr)
	Returns a substring starting at the location of the first occurrence of the specified character. More...

sstr_t	sstrrchr (sstr_t string, int chr)
	Returns a substring starting at the location of the last occurrence of the specified character. More...

scstr_t	scstrchr (scstr_t string, int chr)
	Returns an immutable substring starting at the location of the first occurrence of the specified character. More...

scstr_t	scstrrchr (scstr_t string, int chr)
	Returns an immutable substring starting at the location of the last occurrence of the specified character. More...

sstr_t	scstrsstr (sstr_t string, scstr_t match)
	Returns a substring starting at the location of the first occurrence of the specified string. More...

scstr_t	scstrscstr (scstr_t string, scstr_t match)
	Returns an immutable substring starting at the location of the first occurrence of the specified immutable string. More...

sstr_t *	scstrsplit (scstr_t string, scstr_t delim, ssize_t *count)
	Splits a string into parts by using a delimiter string. More...

sstr_t *	scstrsplit_a (UcxAllocator allocator, scstr_t string, scstr_t delim, ssize_t count)
	Performing scstrsplit() using a UcxAllocator. More...

int	scstrcmp (scstr_t s1, scstr_t s2)
	Compares two UCX strings with standard `memcmp()`. More...

int	scstrcasecmp (scstr_t s1, scstr_t s2)
	Compares two UCX strings ignoring the case. More...

sstr_t	scstrdup (scstr_t string)
	Creates a duplicate of the specified string. More...

sstr_t	scstrdup_a (UcxAllocator *allocator, scstr_t string)
	Creates a duplicate of the specified string using a UcxAllocator. More...

sstr_t	sstrtrim (sstr_t string)
	Omits leading and trailing spaces. More...

scstr_t	scstrtrim (scstr_t string)
	Omits leading and trailing spaces. More...

int	scstrprefix (scstr_t string, scstr_t prefix)
	Checks, if a string has a specific prefix. More...

int	scstrsuffix (scstr_t string, scstr_t suffix)
	Checks, if a string has a specific suffix. More...

int	scstrcaseprefix (scstr_t string, scstr_t prefix)
	Checks, if a string has a specific prefix, ignoring the case. More...

int	scstrcasesuffix (scstr_t string, scstr_t suffix)
	Checks, if a string has a specific suffix, ignoring the case. More...

sstr_t	scstrlower (scstr_t string)
	Returns a lower case version of a string. More...

sstr_t	scstrlower_a (UcxAllocator *allocator, scstr_t string)
	Returns a lower case version of a string. More...

sstr_t	scstrupper (scstr_t string)
	Returns a upper case version of a string. More...

sstr_t	scstrupper_a (UcxAllocator *allocator, scstr_t string)
	Returns a upper case version of a string. More...

Detailed Description

Bounded string implementation.

The UCX strings (sstr_t) provide an alternative to C strings. The main difference to C strings is, that sstr_t does not need to be NULL-terminated. Instead the length is stored within the structure.

When using sstr_t, developers must be full aware of what type of string (NULL-terminated) or not) they are using, when accessing the char* ptr directly.

The UCX string module provides some common string functions, known from standard libc, working with sstr_t.

Author: Mike Becker; Olaf Wintermann

Macro Definition Documentation

◆ PRIsstr

#define PRIsstr ".*s"

Format specifier for a sstr_t or scstr_t.

◆ S

#define S ( s ) sstrn(s, sizeof(s)-1)

Shortcut for the conversion of a C string to a sstr_t.

◆ SC

#define SC ( s ) scstrn(s, sizeof(s)-1)

Shortcut for the conversion of a C string to a scstr_t.

◆ SCSTR

#define SCSTR ( str ) ucx_ss2c_s(str)

Converts a UCX string to an immutable UCX string (scstr_t).

Parameters

str	some UCX string

Returns: the an immutable version of the provided string

◆ SFMT

#define SFMT ( s ) (int) (s).length, (s).ptr

Expands a sstr_t or scstr_t to printf arguments.

◆ sstrcasecmp

#define sstrcasecmp	(	s1,
		s2
	)	scstrcasecmp(SCSTR(s1), SCSTR(s2))

Compares two UCX strings ignoring the case.

At first it compares the sstr_t.length attribute of the two strings. If and only if the lengths match, both strings are compared char by char ignoring the case.

Parameters

s1	the first string
s2	the second string

Returns: -1, if the length of s1 is less than the length of s2 or 1, if the length of s1 is greater than the length of s2 or the result of the platform specific string comparison function ignoring the case.

◆ sstrcaseprefix

#define sstrcaseprefix	(	string,
		prefix
	)	scstrcaseprefix(SCSTR(string), SCSTR(prefix))

Checks, if a string has a specific prefix, ignoring the case.

Parameters

string	the string to check
prefix	the prefix the string should have

Returns: 1, if and only if the string has the specified prefix, 0 otherwise

◆ sstrcasesuffix

#define sstrcasesuffix	(	string,
		suffix
	)	scstrcasesuffix(SCSTR(string), SCSTR(suffix))

Checks, if a string has a specific suffix, ignoring the case.

Parameters

string	the string to check
suffix	the suffix the string should have

Returns: 1, if and only if the string has the specified suffix, 0 otherwise

◆ sstrcat

#define sstrcat	(	count,
		s1,
		...
	)	scstrcat(count, SCSTR(s1), __VA_ARGS__)

Concatenates two or more strings.

The resulting string will be allocated by standard malloc(). So developers MUST pass the sstr_t.ptr to free().

The sstr_t.ptr of the return value will always be NULL- terminated.

Parameters

count	the total number of strings to concatenate
s1	first string
...	all remaining strings

Returns: the concatenated string

◆ sstrcat_a

#define sstrcat_a	(	alloc,
		count,
		s1,
		...
	)	scstrcat_a(alloc, count, SCSTR(s1), __VA_ARGS__)

Concatenates two or more strings using a UcxAllocator.

The resulting string must be freed by the allocators free() implementation.

The sstr_t.ptr of the return value will always be NULL- terminated.

Parameters

alloc	the allocator to use
count	the total number of strings to concatenate
s1	first string
...	all remaining strings

Returns: the concatenated string

See also: sstrcat()

◆ sstrcmp

#define sstrcmp	(	s1,
		s2
	)	scstrcmp(SCSTR(s1), SCSTR(s2))

Compares two UCX strings with standard memcmp().

At first it compares the sstr_t.length attribute of the two strings. The memcmp() function is called, if and only if the lengths match.

Parameters

s1	the first string
s2	the second string

Returns: -1, if the length of s1 is less than the length of s2 or 1, if the length of s1 is greater than the length of s2 or the result of memcmp() otherwise (i.e. 0 if the strings match)

◆ sstrdup

#define sstrdup ( string ) scstrdup(SCSTR(string))

Creates a duplicate of the specified string.

The new sstr_t will contain a copy allocated by standard malloc(). So developers MUST pass the sstr_t.ptr to free().

The sstr_t.ptr of the return value will always be NULL- terminated, regardless of the argument.

Parameters

string the string to duplicate

Returns: a duplicate of the string

See also: sstrdup_a()

◆ sstrdup_a

#define sstrdup_a	(	allocator,
		string
	)	scstrdup_a(allocator, SCSTR(string))

Creates a duplicate of the specified string using a UcxAllocator.

The new sstr_t will contain a copy allocated by the allocators UcxAllocator.malloc() function. So it is implementation depended, whether the returned sstr_t.ptr pointer must be passed to the allocators UcxAllocator.free() function manually.

The sstr_t.ptr of the return value will always be NULL- terminated, regardless of the argument.

Parameters

allocator	a valid instance of a UcxAllocator
string	the string to duplicate

Returns: a duplicate of the string

See also: scstrdup()

◆ sstrlower

#define sstrlower ( string ) scstrlower(SCSTR(string))

Returns a lower case version of a string.

This function creates a duplicate of the input string, first (see sstrdup()).

Parameters

string the input string

Returns: the resulting lower case string

◆ sstrlower_a

#define sstrlower_a	(	allocator,
		string
	)	scstrlower_a(allocator, SCSTR(string))

Returns a lower case version of a string.

This function creates a duplicate of the input string, first (see sstrdup_a()).

Parameters

allocator	the allocator used for duplicating the string
string	the input string

Returns: the resulting lower case string

◆ sstrnlen

#define sstrnlen	(	count,
		...
	)	scstrnlen(count, __VA_ARGS__)

Returns the accumulated length of all specified strings.

Attention: if the count argument is larger than the count of the specified strings, the behavior is undefined.

Parameters

count	the total number of specified strings
...	all strings

Returns: the cumulated length of all strings

◆ sstrprefix

#define sstrprefix	(	string,
		prefix
	)	scstrprefix(SCSTR(string), SCSTR(prefix))

Checks, if a string has a specific prefix.

Parameters

string	the string to check
prefix	the prefix the string should have

Returns: 1, if and only if the string has the specified prefix, 0 otherwise

◆ sstrscstr

#define sstrscstr	(	string,
		match
	)	scstrscstr(string, SCSTR(match))

Returns an immutable substring starting at the location of the first occurrence of the specified immutable string.

If the string does not contain the other string, an empty string is returned.

If match is an empty string, the complete string is returned.

Parameters

string	the string to be scanned
match	string containing the sequence of characters to match

Returns: a substring starting at the first occurrence of match, or an empty string, if the sequence is not present in string

◆ sstrsplit

#define sstrsplit	(	string,
		delim,
		count
	)	scstrsplit(SCSTR(string), SCSTR(delim), count)

Splits a string into parts by using a delimiter string.

This function will return NULL, if one of the following happens:

the string length is zero
the delimeter length is zero
the string equals the delimeter
memory allocation fails

The integer referenced by count is used as input and determines the maximum size of the resulting array, i.e. the maximum count of splits to perform + 1.

The integer referenced by count is also used as output and is set to

-2, on memory allocation errors
-1, if either the string or the delimiter is an empty string
0, if the string equals the delimiter
1, if the string does not contain the delimiter
the count of array items, otherwise

If the string starts with the delimiter, the first item of the resulting array will be an empty string.

If the string ends with the delimiter and the maximum list size is not exceeded, the last array item will be an empty string. In case the list size would be exceeded, the last array item will be the remaining string after the last split, including the terminating delimiter.

Attention: The array pointer AND all sstr_t.ptr of the array items must be manually passed to free(). Use sstrsplit_a() with an allocator to managed memory, to avoid this.

Parameters

string	the string to split
delim	the delimiter string
count	IN: the maximum size of the resulting array (0 = no limit), OUT: the actual size of the array

Returns: a sstr_t array containing the split strings or NULL on error

See also: sstrsplit_a()

◆ sstrsplit_a

#define sstrsplit_a	(	allocator,
		string,
		delim,
		count
	)	scstrsplit_a(allocator, SCSTR(string), SCSTR(delim), count)

Performing sstrsplit() using a UcxAllocator.

Read the description of sstrsplit() for details.

The memory for the sstr_t.ptr pointers of the array items and the memory for the sstr_t array itself are allocated by using the UcxAllocator.malloc() function.

Parameters

allocator	the UcxAllocator used for allocating memory
string	the string to split
delim	the delimiter string
count	IN: the maximum size of the resulting array (0 = no limit), OUT: the actual size of the array

Returns: a sstr_t array containing the split strings or NULL on error

See also: sstrsplit()

◆ sstrstr

#define sstrstr	(	string,
		match
	)	scstrsstr(string, SCSTR(match))

Returns a substring starting at the location of the first occurrence of the specified string.

If the string does not contain the other string, an empty string is returned.

If match is an empty string, the complete string is returned.

Parameters

string	the string to be scanned
match	string containing the sequence of characters to match

Returns: a substring starting at the first occurrence of match, or an empty string, if the sequence is not present in string

◆ sstrsuffix

#define sstrsuffix	(	string,
		suffix
	)	scstrsuffix(SCSTR(string), SCSTR(suffix))

Checks, if a string has a specific suffix.

Parameters

string	the string to check
suffix	the suffix the string should have

Returns: 1, if and only if the string has the specified suffix, 0 otherwise

◆ sstrupper

#define sstrupper ( string ) scstrupper(SCSTR(string))

Returns a upper case version of a string.

This function creates a duplicate of the input string, first (see sstrdup()).

Parameters

string the input string

Returns: the resulting upper case string

◆ sstrupper_a

#define sstrupper_a	(	allocator,
		string
	)	scstrupper_a(allocator, string)

Returns a upper case version of a string.

This function creates a duplicate of the input string, first (see sstrdup_a()).

Parameters

allocator	the allocator used for duplicating the string
string	the input string

Returns: the resulting upper case string

Function Documentation

◆ scstr()

scstr_t scstr ( const char * cstring )

Creates a new scstr_t based on a constant C string.

The length is implicitly inferred by using a call to strlen().

Note: the scstr_t will share the specified pointer to the C string. If you do want a copy, use scstrdup() on the return value of this function.

Parameters

cstring the C string to wrap

Returns: a new scstr_t containing the C string

See also: scstrn()

◆ scstrcasecmp()

int scstrcasecmp	(	scstr_t	s1,
		scstr_t	s2
	)

Compares two UCX strings ignoring the case.

At first it compares the scstr_t.length attribute of the two strings. If and only if the lengths match, both strings are compared char by char ignoring the case.

Parameters

s1	the first string
s2	the second string

Returns: -1, if the length of s1 is less than the length of s2 or 1, if the length of s1 is greater than the length of s2 or the result of the platform specific string comparison function ignoring the case.

◆ scstrcaseprefix()

int scstrcaseprefix	(	scstr_t	string,
		scstr_t	prefix
	)

Checks, if a string has a specific prefix, ignoring the case.

Parameters

string	the string to check
prefix	the prefix the string should have

Returns: 1, if and only if the string has the specified prefix, 0 otherwise

◆ scstrcasesuffix()

int scstrcasesuffix	(	scstr_t	string,
		scstr_t	suffix
	)

Checks, if a string has a specific suffix, ignoring the case.

Parameters

string	the string to check
suffix	the suffix the string should have

Returns: 1, if and only if the string has the specified suffix, 0 otherwise

◆ scstrcat()

sstr_t scstrcat	(	size_t	count,
		scstr_t	s1,
			...
	)

Concatenates two or more strings.

The resulting string will be allocated by standard malloc(). So developers MUST pass the sstr_t.ptr to free().

The sstr_t.ptr of the return value will always be NULL- terminated.

Parameters

count	the total number of strings to concatenate
s1	first string
...	all remaining strings

Returns: the concatenated string

◆ scstrcat_a()

sstr_t scstrcat_a	(	UcxAllocator *	alloc,
		size_t	count,
		scstr_t	s1,
			...
	)

Concatenates two or more strings using a UcxAllocator.

The resulting string must be freed by the allocators free() implementation.

The sstr_t.ptr of the return value will always be NULL- terminated.

Parameters

alloc	the allocator to use
count	the total number of strings to concatenate
s1	first string
...	all remaining strings

Returns: the concatenated string

See also: scstrcat()

◆ scstrchr()

scstr_t scstrchr	(	scstr_t	string,
		int	chr
	)

Returns an immutable substring starting at the location of the first occurrence of the specified character.

If the string does not contain the character, an empty string is returned.

Parameters

string	the string where to locate the character
chr	the character to locate

Returns: a substring starting at the first location of chr

See also: scstrsubs()

◆ scstrcmp()

int scstrcmp	(	scstr_t	s1,
		scstr_t	s2
	)

Compares two UCX strings with standard memcmp().

At first it compares the scstr_t.length attribute of the two strings. The memcmp() function is called, if and only if the lengths match.

Parameters

s1	the first string
s2	the second string

Returns: -1, if the length of s1 is less than the length of s2 or 1, if the length of s1 is greater than the length of s2 or the result of memcmp() otherwise (i.e. 0 if the strings match)

◆ scstrdup()

sstr_t scstrdup ( scstr_t string )

Creates a duplicate of the specified string.

The new sstr_t will contain a copy allocated by standard malloc(). So developers MUST pass the sstr_t.ptr to free().

The sstr_t.ptr of the return value will always be NULL- terminated and mutable, regardless of the argument.

Parameters

string the string to duplicate

Returns: a duplicate of the string

See also: scstrdup_a()

◆ scstrdup_a()

sstr_t scstrdup_a	(	UcxAllocator *	allocator,
		scstr_t	string
	)

Creates a duplicate of the specified string using a UcxAllocator.

The new sstr_t will contain a copy allocated by the allocators UcxAllocator.malloc() function. So it is implementation depended, whether the returned sstr_t.ptr pointer must be passed to the allocators UcxAllocator.free() function manually.

The sstr_t.ptr of the return value will always be NULL- terminated and mutable, regardless of the argument.

Parameters

allocator	a valid instance of a UcxAllocator
string	the string to duplicate

Returns: a duplicate of the string

See also: scstrdup()

◆ scstrlower()

sstr_t scstrlower ( scstr_t string )

Returns a lower case version of a string.

This function creates a duplicate of the input string, first (see scstrdup()).

Parameters

string the input string

Returns: the resulting lower case string

See also: scstrdup()

◆ scstrlower_a()

sstr_t scstrlower_a	(	UcxAllocator *	allocator,
		scstr_t	string
	)

Returns a lower case version of a string.

This function creates a duplicate of the input string, first (see scstrdup_a()).

Parameters

allocator	the allocator used for duplicating the string
string	the input string

Returns: the resulting lower case string

See also: scstrdup_a()

◆ scstrn()

scstr_t scstrn	(	const char *	cstring,
		size_t	length
	)

Creates a new scstr_t of the specified length based on a constant C string.

Note: the scstr_t will share the specified pointer to the C string. If you do want a copy, use scstrdup() on the return value of this function. *

Parameters

cstring	the C string to wrap
length	the length of the string

Returns: a new scstr_t containing the C string

See also: scstr()

◆ scstrnlen()

size_t scstrnlen	(	size_t	count,
			...
	)

Returns the accumulated length of all specified strings.

Attention: if the count argument is larger than the count of the specified strings, the behavior is undefined.

Parameters

count	the total number of specified strings
...	all strings

Returns: the accumulated length of all strings

◆ scstrprefix()

int scstrprefix	(	scstr_t	string,
		scstr_t	prefix
	)

Checks, if a string has a specific prefix.

Parameters

string	the string to check
prefix	the prefix the string should have

Returns: 1, if and only if the string has the specified prefix, 0 otherwise

◆ scstrrchr()

scstr_t scstrrchr	(	scstr_t	string,
		int	chr
	)

Returns an immutable substring starting at the location of the last occurrence of the specified character.

If the string does not contain the character, an empty string is returned.

Parameters

string	the string where to locate the character
chr	the character to locate

Returns: a substring starting at the last location of chr

See also: scstrsubs()

◆ scstrscstr()

scstr_t scstrscstr	(	scstr_t	string,
		scstr_t	match
	)

Returns an immutable substring starting at the location of the first occurrence of the specified immutable string.

If the string does not contain the other string, an empty string is returned.

If match is an empty string, the complete string is returned.

Parameters

string	the string to be scanned
match	string containing the sequence of characters to match

Returns: a substring starting at the first occurrence of match, or an empty string, if the sequence is not present in string

◆ scstrsplit()

sstr_t* scstrsplit	(	scstr_t	string,
		scstr_t	delim,
		ssize_t *	count
	)

Splits a string into parts by using a delimiter string.

This function will return NULL, if one of the following happens:

the string length is zero
the delimeter length is zero
the string equals the delimeter
memory allocation fails

The integer referenced by count is used as input and determines the maximum size of the resulting array, i.e. the maximum count of splits to perform + 1.

The integer referenced by count is also used as output and is set to

-2, on memory allocation errors
-1, if either the string or the delimiter is an empty string
0, if the string equals the delimiter
1, if the string does not contain the delimiter
the count of array items, otherwise

If the string starts with the delimiter, the first item of the resulting array will be an empty string.

If the string ends with the delimiter and the maximum list size is not exceeded, the last array item will be an empty string. In case the list size would be exceeded, the last array item will be the remaining string after the last split, including the terminating delimiter.

Attention: The array pointer AND all sstr_t.ptr of the array items must be manually passed to free(). Use scstrsplit_a() with an allocator to managed memory, to avoid this.

Parameters

string	the string to split
delim	the delimiter string
count	IN: the maximum size of the resulting array (0 = no limit), OUT: the actual size of the array

Returns: a sstr_t array containing the split strings or NULL on error

See also: scstrsplit_a()

◆ scstrsplit_a()

sstr_t* scstrsplit_a	(	UcxAllocator *	allocator,
		scstr_t	string,
		scstr_t	delim,
		ssize_t *	count
	)

Performing scstrsplit() using a UcxAllocator.

Read the description of scstrsplit() for details.

The memory for the sstr_t.ptr pointers of the array items and the memory for the sstr_t array itself are allocated by using the UcxAllocator.malloc() function.

Parameters

allocator	the UcxAllocator used for allocating memory
string	the string to split
delim	the delimiter string
count	IN: the maximum size of the resulting array (0 = no limit), OUT: the actual size of the array

Returns: a sstr_t array containing the split strings or NULL on error

See also: scstrsplit()

◆ scstrsstr()

sstr_t scstrsstr	(	sstr_t	string,
		scstr_t	match
	)

Returns a substring starting at the location of the first occurrence of the specified string.

If the string does not contain the other string, an empty string is returned.

If match is an empty string, the complete string is returned.

Parameters

string	the string to be scanned
match	string containing the sequence of characters to match

Returns: a substring starting at the first occurrence of match, or an empty string, if the sequence is not present in string

◆ scstrsubs()

scstr_t scstrsubs	(	scstr_t	string,
		size_t	start
	)

Returns a substring of an immutable string starting at the specified location.

Attention: the new string references the same memory area as the input string and is NOT required to be NULL-terminated. Use scstrdup() to get a copy.

Parameters

string	input string
start	start location of the substring

Returns: a substring of string starting at start

See also: scstrsubsl(); scstrchr()

◆ scstrsubsl()

scstr_t scstrsubsl	(	scstr_t	string,
		size_t	start,
		size_t	length
	)

Returns a substring of an immutable string with a maximum length starting at the specified location.

Attention: the new string references the same memory area as the input string and is NOT required to be NULL-terminated. Use scstrdup() to get a copy.

Parameters

string	input string
start	start location of the substring
length	the maximum length of the substring

Returns: a substring of string starting at start with a maximum length of length

See also: scstrsubs(); scstrchr()

◆ scstrsuffix()

int scstrsuffix	(	scstr_t	string,
		scstr_t	suffix
	)

Checks, if a string has a specific suffix.

Parameters

string	the string to check
suffix	the suffix the string should have

Returns: 1, if and only if the string has the specified suffix, 0 otherwise

◆ scstrtrim()

scstr_t scstrtrim ( scstr_t string )

Omits leading and trailing spaces.

This function returns a new scstr_t containing a trimmed version of the specified string.

Note: the new scstr_t references the same memory, thus you MUST NOT pass the scstr_t.ptr of the return value to free(). It is also highly recommended to avoid assignments like mystr = scstrtrim(mystr); as you lose the reference to the source string. Assignments of this type are only permitted, if the scstr_t.ptr of the source string does not need to be freed or if another reference to the source string exists.

Parameters

string the string that shall be trimmed

Returns: a new scstr_t containing the trimmed string

◆ scstrupper()

sstr_t scstrupper ( scstr_t string )

Returns a upper case version of a string.

This function creates a duplicate of the input string, first (see scstrdup()).

Parameters

string the input string

Returns: the resulting upper case string

See also: scstrdup()

◆ scstrupper_a()

sstr_t scstrupper_a	(	UcxAllocator *	allocator,
		scstr_t	string
	)

Returns a upper case version of a string.

This function creates a duplicate of the input string, first (see scstrdup_a()).

Parameters

allocator	the allocator used for duplicating the string
string	the input string

Returns: the resulting upper case string

See also: scstrdup_a()

◆ sstr()

sstr_t sstr ( char * cstring )

Creates a new sstr_t based on a C string.

The length is implicitly inferred by using a call to strlen().

Note: the sstr_t will share the specified pointer to the C string. If you do want a copy, use sstrdup() on the return value of this function.

If you need to wrap a constant string, use scstr().

Parameters

cstring the C string to wrap

Returns: a new sstr_t containing the C string

See also: sstrn()

◆ sstrchr()

sstr_t sstrchr	(	sstr_t	string,
		int	chr
	)

Returns a substring starting at the location of the first occurrence of the specified character.

If the string does not contain the character, an empty string is returned.

Parameters

string	the string where to locate the character
chr	the character to locate

Returns: a substring starting at the first location of chr

See also: sstrsubs()

◆ sstrn()

sstr_t sstrn	(	char *	cstring,
		size_t	length
	)

Creates a new sstr_t of the specified length based on a C string.

Note: the sstr_t will share the specified pointer to the C string. If you do want a copy, use sstrdup() on the return value of this function.

If you need to wrap a constant string, use scstrn().

Parameters

cstring	the C string to wrap
length	the length of the string

Returns: a new sstr_t containing the C string

See also: sstr(); S()

◆ sstrrchr()

sstr_t sstrrchr	(	sstr_t	string,
		int	chr
	)

Returns a substring starting at the location of the last occurrence of the specified character.

If the string does not contain the character, an empty string is returned.

Parameters

string	the string where to locate the character
chr	the character to locate

Returns: a substring starting at the last location of chr

See also: sstrsubs()

◆ sstrsubs()

sstr_t sstrsubs	(	sstr_t	string,
		size_t	start
	)

Returns a substring starting at the specified location.

Attention: the new string references the same memory area as the input string and is NOT required to be NULL-terminated. Use sstrdup() to get a copy.

Parameters

string	input string
start	start location of the substring

Returns: a substring of string starting at start

See also: sstrsubsl(); sstrchr()

◆ sstrsubsl()

sstr_t sstrsubsl	(	sstr_t	string,
		size_t	start,
		size_t	length
	)

Returns a substring with the given length starting at the specified location.

Attention: the new string references the same memory area as the input string and is NOT required to be NULL-terminated. Use sstrdup() to get a copy.

Parameters

string	input string
start	start location of the substring
length	the maximum length of the substring

Returns: a substring of string starting at start with a maximum length of length

See also: sstrsubs(); sstrchr()

◆ sstrtrim()

sstr_t sstrtrim ( sstr_t string )

Omits leading and trailing spaces.

This function returns a new sstr_t containing a trimmed version of the specified string.

Note: the new sstr_t references the same memory, thus you MUST NOT pass the sstr_t.ptr of the return value to free(). It is also highly recommended to avoid assignments like mystr = sstrtrim(mystr); as you lose the reference to the source string. Assignments of this type are only permitted, if the sstr_t.ptr of the source string does not need to be freed or if another reference to the source string exists.

Parameters

string the string that shall be trimmed

Returns: a new sstr_t containing the trimmed string

◆ ucx_sc2sc()

scstr_t ucx_sc2sc ( scstr_t str )

One of two type adjustment functions that return an scstr_t.

Used internally to convert a UCX string to an immutable UCX string. This variant is used, when the string is already immutable and no operation needs to be performed.

Do not use this function manually.

Parameters

str	some scstr_t

Returns: the argument itself

◆ ucx_ss2c_s()

scstr_t ucx_ss2c_s ( )

Converts a UCX string to an immutable UCX string (scstr_t).

This internal function (ab)uses the C standard an expects one single argument which is then implicitly converted to scstr_t without a warning.

Do not use this function manually.

Returns: the an immutable version of the provided string

◆ ucx_ss2sc()

scstr_t ucx_ss2sc ( sstr_t str )

One of two type adjustment functions that return an scstr_t.

Used internally to convert a UCX string to an immutable UCX string.

Do not use this function manually.

Parameters

str	some sstr_t

Returns: an immutable (scstr_t) version of the provided string.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ PRIsstr

◆ S

◆ SC

◆ SCSTR

◆ SFMT

◆ sstrcasecmp

◆ sstrcaseprefix

◆ sstrcasesuffix

◆ sstrcat

◆ sstrcat_a

◆ sstrcmp

◆ sstrdup

◆ sstrdup_a

◆ sstrlower

◆ sstrlower_a

◆ sstrnlen

◆ sstrprefix

◆ sstrscstr

◆ sstrsplit

◆ sstrsplit_a

◆ sstrstr

◆ sstrsuffix

◆ sstrupper

◆ sstrupper_a

Function Documentation

◆ scstr()

◆ scstrcasecmp()

◆ scstrcaseprefix()

◆ scstrcasesuffix()

◆ scstrcat()

◆ scstrcat_a()

◆ scstrchr()

◆ scstrcmp()

◆ scstrdup()

◆ scstrdup_a()

◆ scstrlower()

◆ scstrlower_a()

◆ scstrn()

◆ scstrnlen()

◆ scstrprefix()

◆ scstrrchr()

◆ scstrscstr()

◆ scstrsplit()

◆ scstrsplit_a()

◆ scstrsstr()

◆ scstrsubs()

◆ scstrsubsl()

◆ scstrsuffix()

◆ scstrtrim()

◆ scstrupper()

◆ scstrupper_a()

◆ sstr()

◆ sstrchr()

◆ sstrn()

◆ sstrrchr()

◆ sstrsubs()

◆ sstrsubsl()

◆ sstrtrim()

◆ ucx_sc2sc()

◆ ucx_ss2c_s()

◆ ucx_ss2sc()