Safe Strings Library Reference Manual

Safe Strings library, version 2.0.1

API Reference

I. Basic information Top

If you want to use SStrings then you have to create a new ss_string-object and initalize it with ss_string_new.

If the argument of a function is char* then the function will always expect a 0-terminated string, otherwise the behaviour of the function is undefined.

If you don't use the garbage collector then you have to free the ss_string-objects by yourself with ss_string_free.

II. API Reference Top

SString Function List

Object generating functions

SString function
ss_string* ss_string_new(const char* init);
Description Creates a new ss_string object initialized with an initial text

init The initial text to copy into the string. This argument cannot be NULL

Returns A newly created ss_string object. NULL by failure

Error model SS_NULL if init is NULL.
SS_NOMEM if there is no memory available (memory cannot be allocated)

Object destroy functions & Garbage Collector

SString Funktion
char *ss_string_free(ss_string *string, int free_cstring);
Description frees the allocates memory for the ss_string-Object and its string

string The ss_string-Object to be freed

free_cstring Non-0 then the string is freed. If free_cstring is 0 then the string is returned

Returns The pointer to the string if free_cstring is 0. NULL otherwise

SString Funktion
void ss_string_gc_free(const char *str);
Description Description: When you set free_cstring to 0 when you use ss_string_free() you get the pointer to the C-String. This C-String must be freed with ss_string_gc_free()

str The pointer to the C-String to be freed

SString Funktion
int ss_string_enable_gc(void);
Description Enables the usage of the simple garbage collector. This function should be called before any other ss_string functions

Returns 1 on success, 0 on failure

Help routines

SString Function
void ss_string_perror(const char *msg);
Description This function works like perror(). ss_string_perror() uses the ss_errno variabe instead of errno

msg The string pointed to by msg that should be printed before the error message

SString Function
char* strrstr(const char *haystack, const char *needle);
Description Searches for the last occurrence of a substring in a string

haystack The C-String in which must be searched

needle The substring

Returns A pointer to the last occurrence of needle in haystack. NULL if needle is not found.

SString Function
int ss_string_strcmp(const ss_string *s1, const ss_string *s2);
Description Compares two strings to content equality

s1 a valid ss_string-Object

s2 a valid ss_string-Object

Returns 0 if both strings are equal, 1 if not, -1 on error an ss_errno is set

Error model SS_NULL if s1 or s2 are NULL
SS_EINVAL if s1 or s2 are invalid ss_string_Objects

Insert functions

SString Funktion
int ss_string_append(ss_string *string, const ss_string *src); int ss_string_append_c_string(ss_string *string, const char *src); int ss_string_append_c_string_l(ss_string *string, const char *src, size_t src_len);
Description This function family append a string into a ss_string-Object.

string A valid ss_string-Object

src ss_string_append(): another valid ss_string-Object to be appended
ss_string_append_c_string(), ss_string_append_c_string_l(): The string pointed to by src

src_len If you know the right length of the C-String then you can use ss_string_append_c_string_l(). Note that ss_string_append_c_string_l() does not check whether src_len is the right length.

Returns 1 on success, 0 on failure

Error model SS_NULL if string or src are NULL
SS_NOMEM if there is no memory available (memory cannot be allocated)
SS_EINVAL if string is not a valid ss_string-Object

SString Function
int ss_string_insert(ss_string *string, const ss_string *insert, size_t pos); int ss_string_insert_c_string(ss_string *string, const char *insert, size_t pos); int ss_string_insert_c_string_l(ss_string *string, const char *insert, size_t ins_len, size_t pos);
Description Inserts a substring into a string

string a valid ss_string-Object

insert ss_string_insert(): a valid ss_string-Object containing the substring to be inserted
ss_string_insert_c_string*(): the substring (to be inserted) pointed to by insert

pos The position at which insert must be inserted

ins_len The length of insert. Note that ss_string_insert_c_string_l() does not check whether ins_len is the right length.

Returns 1 on success, 0 on failure

Error model SS_NULL if string or insert are NULL
SS_NOMEM if there is no memory available (memory cannot be allocated)
SS_EINVAL if string or insert are invalid ss_string-Objects

Replace functions

SString Function
int ss_string_replace(ss_string *string, const ss_string *pattern, const ss_string *replace); int ss_string_replace_c_string(ss_string *string, const char *pattern, const char *replace); int ss_string_replace_c_string_l(ss_string *string, const char *pattern, size_t patt_len, const char *replace, size_t repl_len);
Description Replaces the first occurrence of a substring given by its pattern with another substring

string a valid ss_string-Object

pattern ss_string_replace(): a valid ss_string-Object containing the pattern to be replaced
ss_string_replace_c_string*(): the pattern (to be replaced) pointed to by pattern

replace ss_string_replace(): a valid ss_string-Object containing the substitute substring
ss_string_replace_c_string*(): the substitute substring pointed to by replace

patt_len The pattern length. Note that ss_string_replace_c_string_l() does not check whether patt_len is the right length.

repl_len The substitute substring length. Note that ss_string_replace_c_string_l() does not check whether repl_len is the right length.

Returns 1 on success, 0 on failure, -1 when pattern is not found in string

Error model SS_NULL if string or pattern or replace are NULL
SS_NOMEM if there is no memory available (memory cannot be allocated)
SS_EINVAL if string or pattern or replace are invalid ss_string-Objects

SString Function
int ss_string_rreplace(ss_string *string, const ss_string *pattern, const ss_string *rreplace); int ss_string_rreplace_c_string(ss_string *string, const char *pattern, const char *rreplace); int ss_string_rreplace_c_string_l(ss_string *string, const char *pattern, size_t patt_len, const char *rreplace, size_t repl_len);
Description Replaces the last occurrence of a substring given by its pattern with another substring

string a valid ss_string-Object

pattern ss_string_rreplace(): a valid ss_string-Object containing the pattern to be replaced
ss_string_rreplace_c_string*(): the pattern (to be replaced) pointed to by pattern

replace ss_string_rreplace(): a valid ss_string-Object containing the substitute substring
ss_string_rreplace_c_string*(): the substitute substring pointed to by rreplace

patt_len The pattern length. Note that ss_string_rreplace_c_string_l() does not check whether patt_len is the right length.

repl_len The substitute substring length. Note that ss_string_rreplace_c_string_l() does not check whether repl_len is the right length.

Returns 1 on success, 0 on failure, -1 when pattern is not found in string

Error model SS_NULL if string or pattern or replace are NULL
SS_NOMEM if there is no memory available (memory cannot be allocated)
SS_EINVAL if string or pattern or replace are invalid ss_string-Objects

Delete & Crop functions

SString Funktion
int ss_string_delete(ss_string *string, size_t pos, size_t len);
Description Deletes a substring by its position

string A valid ss_string-Object

pos The position of the substring to be deleted.

len The length of the substring to be deleted.

Returns 1 on success, 0 on failure

Error model SS_NULL if string is NULL
SS_EINVAL if string is an invalid ss_string-Object / pos determines an invalid position

SString Function
int ss_string_crop(ss_string *string, const ss_string *pattern); int ss_string_crop_c_string(ss_string *string, const char *pattern); int ss_string_crop_c_string_l(ss_string *string, const char *pattern, size_t patt_len);
Description Deletes the first occurrence of a substring given by its pattern

string a valid ss_string-Object

pattern ss_string_crop(): a valid ss_string-Object containing the pattern
ss_string_crop_c_string*(): the pattern pointed to by pattern

patt_len The length of the pattern. Note that ss_string_crop_c_string_l() does not check whether patt_len is the right length.

Returns 1 on success, 0 on failure

Error model SS_NULL if string or pattern are NULL
SS_EINVAL if string or pattern are invalid ss_string-Objects

SString Function
int ss_string_rcrop(ss_string *string, const ss_string *pattern); int ss_string_rcrop_c_string(ss_string *string, const char *pattern); int ss_string_rcrop_c_string_l(ss_string *string, const char *pattern, size_t patt_len);
Description Deletes the last occurrence of a substring given by its pattern

string a valid ss_string-Object

pattern ss_string_rcrop(): a valid ss_string-Object containing the pattern
ss_string_rcrop_c_string*(): the pattern pointed to by pattern

patt_len The length of the pattern. Note that ss_string_rcrop_c_string_l() does not check whether patt_len is the right length.

Returns 1 on success, 0 on failure

Error model SS_NULL if string or pattern are NULL
SS_EINVAL if string or pattern are invalid ss_string-Objects

SString Function
int ss_string_ltrim(ss_string *string, int (*blank)(int)); int ss_string_rtrim(ss_string *string, int (*blank)(int)); int ss_string_trim(ss_string *string, int (*blank)(int)); /* callback definition */ int blank(int);
Description Deletes the leading characters of a string that are equal.
ss_string_ltrim() deletes all leading characters from left to right.
ss_string_rltrim() deletes all leading characters from right to left.
ss_string_trim() deletes all leading characters at the beginning and at the end of the string

string a valid ss_string-Object

blank a function pointer to a function that returns 1 if the character must be deleted, 0 otherwise

Returns 1 on success, 0 on failure

Error model SS_NULL if string or blank are NULL
SS_EINVAL if string is an invalid ss_string-Object

Copy functions

SString Function
int ss_string_copy(ss_string *dest, const ss_string *src); int ss_string_copy_c_string(ss_string *dest, const char *src); int ss_string_copy_c_string_l(ss_string *dest, const char *src, size_t len);
Description Copies a string into a ss_string-Object

dest A valid ss_string-Object

src ss_string_copy(): a valid ss_string-Object to be copied
ss_string_copy_c_string*(): a string (to be copied) pointed to by src

len ss_string_copy_c_string_l(): The length of the string. Note that ss_string_copy_c_string_l() does not check whether len is the right length.

Returns 1 on success, 0 on failure

Error model SS_NULL if dest or src are NULL
SS_NOMEM if there is no memory available (memory cannot be allocated)
SS_EINVAL if dest is an invalid ss_string-Object

Description	Creates a new ss_string object initialized with an initial text
`init`	The initial text to copy into the string. This argument cannot be `NULL`
Returns	A newly created ss_string object. `NULL` by failure
Error model	`SS_NULL` if `init` is NULL. `SS_NOMEM` if there is no memory available (memory cannot be allocated)

Description	frees the allocates memory for the ss_string-Object and its string
`string`	The ss_string-Object to be freed
`free_cstring`	Non-0 then the string is freed. If `free_cstring` is 0 then the string is returned
Returns	The pointer to the string if `free_cstring` is 0. `NULL` otherwise

Description	Description: When you set `free_cstring` to 0 when you use `ss_string_free()` you get the pointer to the C-String. This C-String must be freed with `ss_string_gc_free()`
`str`	The pointer to the C-String to be freed

Description	Enables the usage of the simple garbage collector. This function should be called before any other ss_string functions
Returns	1 on success, 0 on failure

Description	This function works like `perror()`. `ss_string_perror()` uses the `ss_errno` variabe instead of `errno`
`msg`	The string pointed to by `msg` that should be printed before the error message

Description	Searches for the last occurrence of a substring in a string
`haystack`	The C-String in which must be searched
`needle`	The substring
Returns	A pointer to the last occurrence of `needle` in `haystack`. `NULL` if `needle` is not found.

Description	Compares two strings to content equality
`s1`	a valid ss_string-Object
`s2`	a valid ss_string-Object
Returns	0 if both strings are equal, 1 if not, -1 on error an `ss_errno` is set
Error model	`SS_NULL` if `s1` or `s2` are `NULL` `SS_EINVAL` if `s1` or `s2` are invalid ss_string_Objects

Description	This function family append a string into a ss_string-Object.
`string`	A valid ss_string-Object
`src`	`ss_string_append()`: another valid ss_string-Object to be appended `ss_string_append_c_string()`, `ss_string_append_c_string_l()`: The string pointed to by `src`
`src_len`	If you know the right length of the C-String then you can use `ss_string_append_c_string_l()`. Note that `ss_string_append_c_string_l()` does not check whether `src_len` is the right length.
Returns	1 on success, 0 on failure
Error model	`SS_NULL` if `string` or `src` are `NULL` `SS_NOMEM` if there is no memory available (memory cannot be allocated) `SS_EINVAL` if `string` is not a valid ss_string-Object

Description	Inserts a substring into a string
`string`	a valid ss_string-Object
`insert`	`ss_string_insert()`: a valid ss_string-Object containing the substring to be inserted `ss_string_insert_c_string*()`: the substring (to be inserted) pointed to by `insert`
`pos`	The position at which `insert` must be inserted
`ins_len`	The length of `insert`. Note that `ss_string_insert_c_string_l()` does not check whether `ins_len` is the right length.
Returns	1 on success, 0 on failure
Error model	`SS_NULL` if `string` or `insert` are `NULL` `SS_NOMEM` if there is no memory available (memory cannot be allocated) `SS_EINVAL` if `string` or `insert` are invalid ss_string-Objects

Description	Replaces the first occurrence of a substring given by its pattern with another substring
`string`	a valid ss_string-Object
`pattern`	`ss_string_replace()`: a valid ss_string-Object containing the pattern to be replaced `ss_string_replace_c_string*()`: the pattern (to be replaced) pointed to by `pattern`
`replace`	`ss_string_replace()`: a valid ss_string-Object containing the substitute substring `ss_string_replace_c_string*()`: the substitute substring pointed to by `replace`
`patt_len`	The pattern length. Note that `ss_string_replace_c_string_l()` does not check whether `patt_len` is the right length.
`repl_len`	The substitute substring length. Note that `ss_string_replace_c_string_l()` does not check whether `repl_len` is the right length.
Returns	1 on success, 0 on failure, -1 when `pattern` is not found in `string`
Error model	`SS_NULL` if `string` or `pattern` or `replace` are `NULL` `SS_NOMEM` if there is no memory available (memory cannot be allocated) `SS_EINVAL` if `string` or `pattern` or `replace` are invalid ss_string-Objects

Description	Replaces the last occurrence of a substring given by its pattern with another substring
`string`	a valid ss_string-Object
`pattern`	`ss_string_rreplace()`: a valid ss_string-Object containing the pattern to be replaced `ss_string_rreplace_c_string*()`: the pattern (to be replaced) pointed to by `pattern`
`replace`	`ss_string_rreplace()`: a valid ss_string-Object containing the substitute substring `ss_string_rreplace_c_string*()`: the substitute substring pointed to by `rreplace`
`patt_len`	The pattern length. Note that `ss_string_rreplace_c_string_l()` does not check whether `patt_len` is the right length.
`repl_len`	The substitute substring length. Note that `ss_string_rreplace_c_string_l()` does not check whether `repl_len` is the right length.
Returns	1 on success, 0 on failure, -1 when `pattern` is not found in `string`
Error model	`SS_NULL` if `string` or `pattern` or `replace` are `NULL` `SS_NOMEM` if there is no memory available (memory cannot be allocated) `SS_EINVAL` if `string` or `pattern` or `replace` are invalid ss_string-Objects

Description	Deletes a substring by its position
`string`	A valid ss_string-Object
`pos`	The position of the substring to be deleted.
`len`	The length of the substring to be deleted.
Returns	1 on success, 0 on failure
Error model	`SS_NULL` if `string` is `NULL` `SS_EINVAL` if `string` is an invalid ss_string-Object / `pos` determines an invalid position

Description	Deletes the first occurrence of a substring given by its pattern
`string`	a valid ss_string-Object
`pattern`	`ss_string_crop()`: a valid ss_string-Object containing the pattern `ss_string_crop_c_string*()`: the pattern pointed to by `pattern`
`patt_len`	The length of the pattern. Note that `ss_string_crop_c_string_l()` does not check whether `patt_len` is the right length.
Returns	1 on success, 0 on failure
Error model	`SS_NULL` if `string` or `pattern` are `NULL` `SS_EINVAL` if `string` or `pattern` are invalid ss_string-Objects

Description	Deletes the last occurrence of a substring given by its pattern
`string`	a valid ss_string-Object
`pattern`	`ss_string_rcrop()`: a valid ss_string-Object containing the pattern `ss_string_rcrop_c_string*()`: the pattern pointed to by `pattern`
`patt_len`	The length of the pattern. Note that `ss_string_rcrop_c_string_l()` does not check whether `patt_len` is the right length.
Returns	1 on success, 0 on failure
Error model	`SS_NULL` if `string` or `pattern` are `NULL` `SS_EINVAL` if `string` or `pattern` are invalid ss_string-Objects

Description	Deletes the leading characters of a string that are equal. `ss_string_ltrim()` deletes all leading characters from left to right. `ss_string_rltrim()` deletes all leading characters from right to left. `ss_string_trim()` deletes all leading characters at the beginning and at the end of the string
`string`	a valid ss_string-Object
`blank`	a function pointer to a function that returns 1 if the character must be deleted, 0 otherwise
Returns	1 on success, 0 on failure
Error model	`SS_NULL` if `string` or `blank` are `NULL` `SS_EINVAL` if `string` is an invalid ss_string-Object

Description	Copies a string into a ss_string-Object
`dest`	A valid ss_string-Object
`src`	`ss_string_copy()`: a valid ss_string-Object to be copied `ss_string_copy_c_string*()`: a string (to be copied) pointed to by `src`
`len`	`ss_string_copy_c_string_l()`: The length of the string. Note that `ss_string_copy_c_string_l()` does not check whether `len` is the right length.
Returns	1 on success, 0 on failure
Error model	`SS_NULL` if `dest` or `src` are `NULL` `SS_NOMEM` if there is no memory available (memory cannot be allocated) `SS_EINVAL` if `dest` is an invalid ss_string-Object