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...
 

Macros

#define ST(s)   { (char*)s, sizeof(s)-1 }
 Shortcut for a sstr_t struct literal. More...
 
#define S(s)   sstrn((char*)s, sizeof(s)-1)
 Shortcut for the conversion of a C string to a sstr_t. More...
 

Functions

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...
 
size_t sstrnlen (size_t count, sstr_t string,...)
 Returns the cumulated length of all specified strings. More...
 
sstr_t sstrcat (size_t count, sstr_t s1, sstr_t s2,...)
 Concatenates two or more strings. More...
 
sstr_t sstrcat_a (UcxAllocator *a, size_t count, sstr_t s1, sstr_t s2,...)
 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 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...
 
sstr_t sstrstr (sstr_t string, sstr_t match)
 Returns a substring starting at the location of the first occurrence of the specified string. More...
 
sstr_tsstrsplit (sstr_t string, sstr_t delim, ssize_t *count)
 Splits a string into parts by using a delimiter string. More...
 
sstr_tsstrsplit_a (UcxAllocator *allocator, sstr_t string, sstr_t delim, ssize_t *count)
 Performing sstrsplit() using a UcxAllocator. More...
 
int sstrcmp (sstr_t s1, sstr_t s2)
 Compares two UCX strings with standard memcmp(). More...
 
int sstrcasecmp (sstr_t s1, sstr_t s2)
 Compares two UCX strings ignoring the case. More...
 
sstr_t sstrdup (sstr_t string)
 Creates a duplicate of the specified string. More...
 
sstr_t sstrdup_a (UcxAllocator *allocator, sstr_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...
 
int sstrprefix (sstr_t string, sstr_t prefix)
 Checks, if a string has a specific prefix. More...
 
int sstrsuffix (sstr_t string, sstr_t suffix)
 Checks, if a string has a specific suffix. More...
 
sstr_t sstrlower (sstr_t string)
 Returns a lower case version of a string. More...
 
sstr_t sstrlower_a (UcxAllocator *allocator, sstr_t string)
 Returns a lower case version of a string. More...
 
sstr_t sstrupper (sstr_t string)
 Returns a upper case version of a string. More...
 
sstr_t sstrupper_a (UcxAllocator *allocator, sstr_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

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

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

#define ST (   s)    { (char*)s, sizeof(s)-1 }

Shortcut for a sstr_t struct literal.

Function Documentation

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 hold a reference to the C string. If you do want a copy, use sstrdup() on the return value of this function.

Parameters
cstringthe C string to wrap
Returns
a new sstr_t containing the C string
See also
sstrn()
int sstrcasecmp ( sstr_t  s1,
sstr_t  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 difference between the first two differing characters otherwise (i.e. 0 if the strings match and no characters differ)
sstr_t sstrcat ( size_t  count,
sstr_t  s1,
sstr_t  s2,
  ... 
)

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
s2second string
...all remaining strings
Returns
the concatenated string
sstr_t sstrcat_a ( UcxAllocator a,
size_t  count,
sstr_t  s1,
sstr_t  s2,
  ... 
)

Concatenates two or more strings using a UcxAllocator.

See sstrcat() for details.

Parameters
athe allocator to use
countthe total number of strings to concatenate
s1first string
s2second string
...all remaining strings
Returns
the concatenated string
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()
int sstrcmp ( sstr_t  s1,
sstr_t  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)
sstr_t sstrdup ( sstr_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.

Parameters
stringthe string to duplicate
Returns
a duplicate of the string
See also
sstrdup_a()
sstr_t sstrdup_a ( UcxAllocator allocator,
sstr_t  string 
)

Creates a duplicate of the specified string using a UcxAllocator.

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

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

Parameters
allocatora valid instance of a UcxAllocator
stringthe string to duplicate
Returns
a duplicate of the string
See also
sstrdup()
sstr_t sstrlower ( sstr_t  string)

Returns a lower case version of a string.

This function creates a duplicate of the input string, first. See the documentation of sstrdup() for the implications.

Parameters
stringthe input string
Returns
the resulting lower case string
See also
sstrdup()
sstr_t sstrlower_a ( UcxAllocator allocator,
sstr_t  string 
)

Returns a lower case version of a string.

This function creates a duplicate of the input string, first. See the documentation of sstrdup_a() for the implications.

Parameters
allocatorthe allocator used for duplicating the string
stringthe input string
Returns
the resulting lower case string
See also
sstrdup_a()
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 hold a reference to the C string. If you do want a copy, use sstrdup() on the return value of this function.

Parameters
cstringthe C string to wrap
lengththe length of the string
Returns
a new sstr_t containing the C string
See also
sstr()
S()
size_t sstrnlen ( size_t  count,
sstr_t  string,
  ... 
)

Returns the cumulated length of all specified strings.

At least one string must be specified.

Attention: if the count argument does not match the count of the specified strings, the behavior is undefined.

Parameters
countthe total number of specified strings (so at least 1)
stringthe first string
...all other strings
Returns
the cumulated length of all strings
int sstrprefix ( sstr_t  string,
sstr_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
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()
sstr_t* sstrsplit ( sstr_t  string,
sstr_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 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()
sstr_t* sstrsplit_a ( UcxAllocator allocator,
sstr_t  string,
sstr_t  delim,
ssize_t *  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.

Note: the allocator is not used for memory that is freed within the same call of this function (locally scoped variables).

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()
sstr_t sstrstr ( sstr_t  string,
sstr_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
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 will NOT 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()
sstr_t sstrsubsl ( sstr_t  string,
size_t  start,
size_t  length 
)

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

Attention: the new string references the same memory area as the input string and will NOT 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()
int sstrsuffix ( sstr_t  string,
sstr_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
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
sstr_t sstrupper ( sstr_t  string)

Returns a upper case version of a string.

This function creates a duplicate of the input string, first. See the documentation of sstrdup() for the implications.

Parameters
stringthe input string
Returns
the resulting upper case string
See also
sstrdup()
sstr_t sstrupper_a ( UcxAllocator allocator,
sstr_t  string 
)

Returns a upper case version of a string.

This function creates a duplicate of the input string, first. See the documentation of sstrdup_a() for the implications.

Parameters
allocatorthe allocator used for duplicating the string
stringthe input string
Returns
the resulting upper case string
See also
sstrdup_a()