ucx
UAP Common Extensions
Data Structures | Macros | Functions
string.h File Reference

Bounded string implementation. More...

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

Go to the source code of this file.

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...
 
#define sstrreplacen_a(allocator, str, pattern, replacement, replmax)
 Replaces a pattern in a string with another string. More...
 
#define sstrreplacen(str, pattern, replacement, replmax)   scstrreplacen(SCSTR(str), SCSTR(pattern), SCSTR(replacement), replmax)
 Replaces a pattern in a string with another string. More...
 
#define sstrreplace_a(allocator, str, pattern, replacement)
 Replaces a pattern in a string with another string. More...
 
#define sstrreplace(str, pattern, replacement)   scstrreplacen(SCSTR(str), SCSTR(pattern), SCSTR(replacement), SIZE_MAX)
 Replaces a pattern in a string with another 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_tscstrsplit (scstr_t string, scstr_t delim, ssize_t *count)
 Splits a string into parts by using a delimiter string. More...
 
sstr_tscstrsplit_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...
 
sstr_t scstrreplacen_a (UcxAllocator *allocator, scstr_t str, scstr_t pattern, scstr_t replacement, size_t replmax)
 Replaces a pattern in a string with another string. More...
 
sstr_t scstrreplacen (scstr_t str, scstr_t pattern, scstr_t replacement, size_t replmax)
 Replaces a pattern in a string with another 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
strsome 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
s1the first string
s2the 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
stringthe string to check
prefixthe 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
stringthe string to check
suffixthe 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
countthe total number of strings to concatenate
s1first 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
allocthe allocator to use
countthe total number of strings to concatenate
s1first 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
s1the first string
s2the 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
stringthe 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
allocatora valid instance of a UcxAllocator
stringthe 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
stringthe 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
allocatorthe allocator used for duplicating the string
stringthe 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
countthe 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
stringthe string to check
prefixthe prefix the string should have
Returns
1, if and only if the string has the specified prefix, 0 otherwise

◆ sstrreplace

#define sstrreplace (   str,
  pattern,
  replacement 
)    scstrreplacen(SCSTR(str), SCSTR(pattern), SCSTR(replacement), SIZE_MAX)

Replaces a pattern in a string with another string.

The pattern is taken literally and is no regular expression. Replaces at most replmax occurrences.

The sstr_t.ptr of the resulting string must be freed manually.

If allocation fails, the sstr_t.ptr of the return value is NULL.

Parameters
strthe string where replacements should be applied
patternthe pattern to search for
replacementthe replacement string
Returns
the resulting string after applying the replacements

◆ sstrreplace_a

#define sstrreplace_a (   allocator,
  str,
  pattern,
  replacement 
)
Value:
scstrreplacen_a(allocator, SCSTR(str), SCSTR(pattern), \
SCSTR(replacement), SIZE_MAX)
#define SCSTR(str)
Converts a UCX string to an immutable UCX string (scstr_t).
Definition: string.h:233
sstr_t scstrreplacen_a(UcxAllocator *allocator, scstr_t str, scstr_t pattern, scstr_t replacement, size_t replmax)
Replaces a pattern in a string with another string.
Definition: string.c:682

Replaces a pattern in a string with another string.

The pattern is taken literally and is no regular expression. Replaces at most replmax occurrences.

The resulting string is allocated by the specified allocator. I.e. it depends on the used allocator, whether the sstr_t.ptr must be freed manually.

If allocation fails, the sstr_t.ptr of the return value is NULL.

Parameters
allocatorthe allocator to use
strthe string where replacements should be applied
patternthe pattern to search for
replacementthe replacement string
Returns
the resulting string after applying the replacements

◆ sstrreplacen

#define sstrreplacen (   str,
  pattern,
  replacement,
  replmax 
)    scstrreplacen(SCSTR(str), SCSTR(pattern), SCSTR(replacement), replmax)

Replaces a pattern in a string with another string.

The pattern is taken literally and is no regular expression. Replaces at most replmax occurrences.

The sstr_t.ptr of the resulting string must be freed manually.

If allocation fails, the sstr_t.ptr of the return value is NULL.

Parameters
strthe string where replacements should be applied
patternthe pattern to search for
replacementthe replacement string
replmaxmaximum number of replacements
Returns
the resulting string after applying the replacements

◆ sstrreplacen_a

#define sstrreplacen_a (   allocator,
  str,
  pattern,
  replacement,
  replmax 
)
Value:
scstrreplacen_a(allocator, SCSTR(str), SCSTR(pattern), \
SCSTR(replacement), replmax)
#define SCSTR(str)
Converts a UCX string to an immutable UCX string (scstr_t).
Definition: string.h:233
sstr_t scstrreplacen_a(UcxAllocator *allocator, scstr_t str, scstr_t pattern, scstr_t replacement, size_t replmax)
Replaces a pattern in a string with another string.
Definition: string.c:682

Replaces a pattern in a string with another string.

The pattern is taken literally and is no regular expression. Replaces at most replmax occurrences.

The resulting string is allocated by the specified allocator. I.e. it depends on the used allocator, whether the sstr_t.ptr must be freed manually.

Parameters
allocatorthe allocator to use
strthe string where replacements should be applied
patternthe pattern to search for
replacementthe replacement string
replmaxmaximum number of replacements
Returns
the resulting string after applying the replacements

◆ 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
stringthe string to be scanned
matchstring 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
stringthe string to split
delimthe delimiter string
countIN: 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
allocatorthe UcxAllocator used for allocating memory
stringthe string to split
delimthe delimiter string
countIN: 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
stringthe string to be scanned
matchstring 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
stringthe string to check
suffixthe 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
stringthe 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
allocatorthe allocator used for duplicating the string
stringthe 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
cstringthe 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
s1the first string
s2the 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
stringthe string to check
prefixthe 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
stringthe string to check
suffixthe 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
countthe total number of strings to concatenate
s1first 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
allocthe allocator to use
countthe total number of strings to concatenate
s1first 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
stringthe string where to locate the character
chrthe 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
s1the first string
s2the 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
stringthe 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
allocatora valid instance of a UcxAllocator
stringthe 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
stringthe 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
allocatorthe allocator used for duplicating the string
stringthe 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
cstringthe C string to wrap
lengththe 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
countthe 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
stringthe string to check
prefixthe 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
stringthe string where to locate the character
chrthe character to locate
Returns
a substring starting at the last location of chr
See also
scstrsubs()

◆ scstrreplacen()

sstr_t scstrreplacen ( scstr_t  str,
scstr_t  pattern,
scstr_t  replacement,
size_t  replmax 
)

Replaces a pattern in a string with another string.

The pattern is taken literally and is no regular expression. Replaces at most replmax occurrences.

The sstr_t.ptr of the resulting string must be freed manually.

If allocation fails, the sstr_t.ptr of the return value is NULL.

Parameters
strthe string where replacements should be applied
patternthe pattern to search for
replacementthe replacement string
replmaxmaximum number of replacements
Returns
the resulting string after applying the replacements

◆ scstrreplacen_a()

sstr_t scstrreplacen_a ( UcxAllocator allocator,
scstr_t  str,
scstr_t  pattern,
scstr_t  replacement,
size_t  replmax 
)

Replaces a pattern in a string with another string.

The pattern is taken literally and is no regular expression. Replaces at most replmax occurrences.

The resulting string is allocated by the specified allocator. I.e. it depends on the used allocator, whether the sstr_t.ptr must be freed manually.

If allocation fails, the sstr_t.ptr of the return value is NULL.

Parameters
allocatorthe allocator to use
strthe string where replacements should be applied
patternthe pattern to search for
replacementthe replacement string
replmaxmaximum number of replacements
Returns
the resulting string after applying the replacements

◆ 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
stringthe string to be scanned
matchstring 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
stringthe string to split
delimthe delimiter string
countIN: 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
allocatorthe UcxAllocator used for allocating memory
stringthe string to split
delimthe delimiter string
countIN: 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
stringthe string to be scanned
matchstring 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
stringinput string
startstart 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
stringinput string
startstart location of the substring
lengththe 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
stringthe string to check
suffixthe 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
stringthe 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
stringthe 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
allocatorthe allocator used for duplicating the string
stringthe 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
cstringthe 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
stringthe string where to locate the character
chrthe 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
cstringthe C string to wrap
lengththe 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
stringthe string where to locate the character
chrthe 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
stringinput string
startstart 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
stringinput string
startstart location of the substring
lengththe 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
stringthe 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
strsome 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
strsome sstr_t
Returns
an immutable (scstr_t) version of the provided string.