Regular strings

Overview

Function to operate the strings. More…

// global functions

static bool te_str_is_null_or_empty(const char* str);
static const char* te_str_empty_if_null(const char* str);
bool te_str_is_equal_nospace(const char* str1, const char* str2);
char* te_str_upper(const char* src);
char* te_str_lower(const char* src);
char* te_str_concat(const char* first, const char* second);
size_t te_strlcpy(char* dst, const char* src, size_t size);
size_t te_strlcat(char* dst, const char* src, size_t size);
te_errno te_strlcpy_safe(char* dst, const char* src, size_t size);
char* te_strlcpy_verbose(const char* id, char* dst, const char* src, size_t size);
char* te_snprintf_verbose(const char* id, char* dst, size_t size, const char* fmt, ...);
te_errno te_vsnprintf(char* dst, size_t size, const char* fmt, va_list ap);
te_errno te_snprintf(char* dst, size_t size, const char* fmt, ...);
te_errno char* te_str_strip_spaces(const char* str);
static const char* te_str_strip_prefix(const char* str, const char* prefix);
size_t te_str_common_prefix(const char* str1, const char* str2);
te_errno te_strpbrk_balanced(const char* str, char opening, char closing, char escape, const char* seps, const char** result);
te_errno te_strpbrk_rev_balanced(const char* str, char opening, char closing, char escape, const char* seps, const char** result);
te_errno te_strtoumax(const char* str, int base, uintmax_t* value);
te_errno te_strtou_size(const char* str, int base, void* value, size_t size);
te_errno te_strtoi_size(const char* str, int base, void* value, size_t size);
te_errno te_strtoimax(const char* str, int base, intmax_t* value);
te_errno te_str_to_uint64(const char* str, int base, uint64_t* value);
te_errno te_strtoul(const char* str, int base, unsigned long int* value);
te_errno te_strtoi(const char* str, int base, int* value);
te_errno te_strtoui(const char* str, int base, unsigned int* value);
te_errno te_strtol_raw(const char* input, char** endptr, int base, long int* result);
te_errno te_strtol_raw_silent(const char* str, char** endptr, int base, long int* result);
te_errno te_strtol_silent(const char* input, int base, long int* result);
te_errno te_strtol(const char* input, int base, long int* result);
te_errno te_strtol_bool(const char* input, bool* bresult);
te_errno te_strtoi_range_raw(const char* input, int minval, int maxval, char** endptr, int base, int* result);
te_errno te_strtod_raw(const char* str, char** endptr, double* result);
te_errno te_strtod(const char* str, double* result);
te_errno te_str_hex_raw2str(const uint8_t* data, size_t data_len, te_string* str);
te_errno te_str_hex_str2raw(const char* str, uint8_t* data, size_t data_len);
te_errno te_str_find_index(const char* str, const char** str_array, unsigned int str_array_len, unsigned int* index);
char** te_str_make_array(const char* fst, ...);
void te_str_free_array(char** str);
te_errno te_str_compare_versions(const char* v1, const char* v2, int* res);

// macros

#define TE_SNPRINTF(_dst, _size, _fmt...)
#define TE_SPRINTF(_buf, _fmt...)
#define TE_STRLCPY(_dst, _src, _size)
#define TE_STR_HEX_DELIMITER

Detailed Documentation

Function to operate the strings.

Global Functions

static bool te_str_is_null_or_empty(const char* str)

Check for empty string.

Parameters:

str	Byte string.

Returns:

true if the string is NULL or zero-length; false otherwise.

static const char* te_str_empty_if_null(const char* str)

Return pointer to an empty string if the string is NULL or pointer to the string itself.

Parameters:

str	Byte string.

Returns:

str or static empty string if str is NULL

bool te_str_is_equal_nospace(const char* str1, const char* str2)

Checks whether two strings are equal modulo space difference.

In particular:

leading and trailing spaces are completely ignored
in the middle all non-empty sequences of whitespace characters are considered equal.

Parameters:

str1	the first string
str2	the second string

Returns:

true iff str1 and str2 are equal up to space difference.

char* te_str_upper(const char* src)

Convert lowercase letters of the string to uppercase. The function does not work with multibyte/wide strings.

Return value should be freed with free(3) when it is no longer needed.

Parameters:

src	Source string.

Returns:

Uppercase letters string, or NULL if it fails to allocate memory.

char* te_str_lower(const char* src)

Convert uppercase letters of the string to lowercase. The function does not work with multibyte/wide strings.

Return value should be freed with free(3) when it is no longer needed.

Parameters:

src	Source string.

Returns:

Lowercase letters string, or NULL if it fails to allocate memory.

char* te_str_concat(const char* first, const char* second)

Concatenate two strings and put result to the newly allocated string. The function does not work with multibyte/wide strings.

Return value should be freed with free(3) when it is no longer needed.

Parameters:

first	First string to concatenate. May be `NULL`, in this case it will be interpreted as empty string, i.e. “”.
second	Second string to concatenate. May be `NULL`, in this case it will be interpreted as empty string, i.e. “”.

Returns:

Concatenated string, or NULL if insufficient memory available to allocate a resulting string.

size_t te_strlcpy(char* dst, const char* src, size_t size)

Copy a string to provided buffer with NUL-terminated result guarantee.

Parameters:

dst	Destination buffer
src	String to copy
size	Size of destination buffer

Returns:

Total length even if it is larger than buffer size.

size_t te_strlcat(char* dst, const char* src, size_t size)

Concatenate with NUL-terminated result guarantee a string to provided string which is located in buffer of specified size.

Parameters:

dst	Buffer with a string to concatenate to
src	String to append
size	Size of destination buffer

Returns:

Total length even if it is larger than buffer size.

te_errno te_strlcpy_safe(char* dst, const char* src, size_t size)

Same as te_strlcpy() except it checks the result itself and returns a status code

char* te_strlcpy_verbose(const char* id, char* dst, const char* src, size_t size)

Call te_strlcpy_safe() and print an error message if there is no enough space in the buffer to allocate the whole input string.

Parameters:

id	Prefix for error message, usually func
dst	Destination buffer
src	String to copy
size	Size of destination buffer

Returns:

A pointer to the destination buffer dst.

char* te_snprintf_verbose(const char* id, char* dst, size_t size, const char* fmt, ...)

The function is equivalent to the function te_snprintf(), except that it just prints error messages instead of returning error code

Parameters:

id	Prefix for error message, usually func
dst	Pointer to destination buffer
size	Size of destination buffer
fmt	Format string
…	Format string arguments

Returns:

A pointer to the destination string dst

te_errno te_vsnprintf(char* dst, size_t size, const char* fmt, va_list ap)

Write at most size bytes (including the terminating null byte (’0’)) to the buffer pointed to by dst according to a format string.

The function does not call the va_end macro. Because it invokes the va_arg macro, the value of ap is undefined after the call

Parameters:

dst	Pointer to destination buffer
size	Size of destination buffer
fmt	Format string
ap	List of arguments
TE_ESMALLBUF	Size of destination buffer is not big enough to store the whole source string. If `size` = `0`, `dst` is not modified
errno	An output error is encountered

Returns:

Status code

See also:

te_snprintf, te_strnprintf

te_errno te_snprintf(char* dst, size_t size, const char* fmt, ...)

The function is equivalent to the function te_vsnprintf(), except that it is called with a variable number of arguments instead of a va_list

te_errno char* te_str_strip_spaces(const char* str)

Take off heading and trailing spaces (all the symbols “ fnrtv”).

Parameters:

str	String to strip spaces.

Returns:

Pointer to the duplicated (heap) string without surrounding spaces, or NULL in case of memory allocation failure.

static const char* te_str_strip_prefix(const char* str, const char* prefix)

Skips the prefix from the string str if it has one.

The function does not allocate any memory, just returning a pointer into the original string or NULL if str does not start with prefix, so it can freely be used just to test for a string prefix.

Parameters:

str	Source string.
prefix	Expected prefix.

Returns:

A pointer into str after the prefix or NULL.

size_t te_str_common_prefix(const char* str1, const char* str2)

Return the longest common prefix of str1 and str2.

Terminating zeroes are never considered part of the prefix. If any of the strings is NULL, the prefix is considered to be zero.

Parameters:

str1	First string.
str2	Second string.

Returns:

Common prefix length.

te_errno te_strpbrk_balanced(const char* str, char opening, char closing, char escape, const char* seps, const char** result)

Search for the leftmost char from seps outside balanced parentheses.

The function scans characters starting from str searching for any char in seps that is outside any nested group of parentheses defined by opening and closing. If seps is NULL, the leftmost character outside any parentheses is returned.

If escape is not NUL, it is used to escape parentheses and separator characters.

te_strpbrk_balanced("a(b,c),d", '(', ')', '\0', ",", result);
result == ",d";

te_strpbrk_balanced("a(b,(c,d)),e", '(', ')', '\0', ",", result);
result == ",e";

te_strpbrk_balanced("a(b,\\),c,d)\\,e,f", '(', ')', '\\', ",", result);
result == ",f";

te_strpbrk_balanced("(abc)def", '(', ')', '\0', NULL, result);
result == "def";

Parameters:

str	Source string.
opening	Opening parenthesis character.
closing	Closing parenthesis character.
escape	Escape character (use `NUL` for no escape character).
seps	List of separators to search for (may be `NULL`).
result	The location of a pointer to the leftmost found character or `NULL` if none found. If `result` itself may be `NULL`, the found pointer is discarded.
TE_ENOENT	No suitable character found.
TE_EILSEQ	`str` contains unbalanced parentheses or dangling escape characters.

Returns:

Status code.

te_errno te_strpbrk_rev_balanced(const char* str, char opening, char closing, char escape, const char* seps, const char** result)

Like te_strpbrk_balanced(), but search for the rightmost character.

te_strpbrk_rev_balanced("a,(b,c)d", '(', ')', '\0', ",", result);
result == ",(b,c)d";

te_strpbrk_rev_balanced("a,(b,(c,d))e", '(', ')', '\0', ",", result);
result == ",(b,(c,d))e";

te_strpbrk_rev_balanced("a,(b,\\(,c,d)\\,e", '(', ')', '\\', ",", result);
result == ",(b,\\(,c,d)\\,e";

te_strpbrk_rev_balanced("abc(def)", '(', ')', '\0', NULL, result);
result == "c(def)";

There is slight asymmtetry between forward and reverse search functions: if seps is empty and the whole string is enclosed in parentheses, then forward searching would point to a terminating zero, but reverse searching would return NULL, because we cannot assume there may be any characters before the string.

Parameters:

str	Source string.
opening	Opening parenthesis character.
closing	Closing parenthesis character.
escape	Escape character (use `NUL` for no escape character).
seps	List of separators to search for (may be `NULL`).
result	The location of a pointer to the rightmost found character or `NULL` if none found. If `result` itself may be `NULL`, the found pointer is discarded.
TE_ENOENT	No suitable character found.
TE_EILSEQ	`str` contains unbalanced parentheses or dangling escape characters.

Returns:

Status code.

te_errno te_strtoumax(const char* str, int base, uintmax_t* value)

Wrapper over strtoumax().

Parameters:

str	String to convert.
base	Base of a numeral system.
value	Where to save conversion result (may be `NULL`).

Returns:

Status code.

te_errno te_strtou_size(const char* str, int base, void* value, size_t size)

Parse unsigned integer of a given size.

Parameters:

str	String to parse.
base	Base of a numeral system.
value	Parsed value (may be `NULL`).
size	Size of `value` in bytes (1, 2, 4 and 8 are supported).

Returns:

Status code.

te_errno te_strtoi_size(const char* str, int base, void* value, size_t size)

Parse signed integer of a given size.

Parameters:

str	String to parse.
base	Base of a numeral system.
value	Parsed value (may be `NULL`).
size	Size of `value` in bytes (1, 2, 4 and 8 are supported).

Returns:

Status code.

te_errno te_strtoimax(const char* str, int base, intmax_t* value)

Wrapper over strtoimax().

Parameters:

str	String to convert.
base	Base of a numeral system.
value	Where to save conversion result (may be `NULL`).

Returns:

Status code.

te_errno te_str_to_uint64(const char* str, int base, uint64_t* value)

Wrapper over te_strtoumax() with overflow check.

Parameters:

str	String to convert.
base	Base of a numeral system.
value	Where to save conversion result (may be `NULL`).

Returns:

Status code.

te_errno te_strtoul(const char* str, int base, unsigned long int* value)

Wrapper over te_strtoumax() with overflow check.

Parameters:

str	String to convert.
base	Base of a numeral system.
value	Where to save conversion result (may be `NULL`).

Returns:

Status code.

te_errno te_strtoi(const char* str, int base, int* value)

Wrapper for te_strtol() with overflow check

Parameters:

str	String to convert.
base	Base of the numeral system.
value	Location for the resulting value (may be `NULL`).

Returns:

Status code.

te_errno te_strtoui(const char* str, int base, unsigned int* value)

Wrapper for te_strtoumax() with overflow check.

Parameters:

str	String to convert.
base	Base of the numeral system.
value	Location for the resulting value (may be `NULL`).

Returns:

Status code.

te_errno te_strtol_raw(const char* input, char** endptr, int base, long int* result)

Convert string to long int. Following characters are allowed.

Parameters:

input	String to convert.
endptr	Pointer to the end of parsed int.
base	Base to be used.
result	Storage for result (may be `NULL`).

Returns:

0 or error

te_errno te_strtol_raw_silent(const char* str, char** endptr, int base, long int* result)

Convert a prefix of string to a long int without logging any errors.

Parameters:

input	String to convert.
endptr	Pointer to the end of a parsed prefix.
base	Conversion base (`0` to auto-detect).
result	Storage for result.

Returns:

Status code.

te_errno te_strtol_silent(const char* input, int base, long int* result)

Convert string to long int without error logs input is not a number.

Should be used to avoid creating extra vars for ‘end’ parameter in the code.

Parameters:

input	String to convert.
base	Base to be used.
result	Storage for result (may be `NULL`).

Returns:

0 or error

te_errno te_strtol(const char* input, int base, long int* result)

Convert string to long int. Should be used to avoid creating extra vars for ‘end’ parameter in the code.

Parameters:

input	String to convert.
base	Base to be used.
result	Storage for result (may be `NULL`).

Returns:

0 or error

te_errno te_strtol_bool(const char* input, bool* bresult)

Convert string to bool where 0 means false, not 0 true.

Parameters:

input	String to convert.
bresult	Storage for result (may be `NULL`).

Returns:

0 or error

te_errno te_strtoi_range_raw(const char* input, int minval, int maxval, char** endptr, int base, int* result)

Convert a string to an integer which must fit into a given range.

Parameters:

input	String to convert.
minval	Minimum allowed value.
maxval	Maximum allowed value.
endptr	Pointer to the tail of the string.
base	Conversion base as per strtol().
result	Result value (may be `NULL`).
TE_ERANGE	The value is not within `minval`.. `maxval`

Returns:

Status code.

te_errno te_strtod_raw(const char* str, char** endptr, double* result)

Convert string to double. Following characters are allowed.

Parameters:

str	String to convert.
endptr	Pointer to the end of parsed double.
result	Storage for result (may be `NULL`).

Returns:

Status code.

te_errno te_strtod(const char* str, double* result)

Convert string to double. Should be used to avoid creating extra vars for ‘end’ parameter in the code.

Parameters:

str	String to convert.
result	Storage for result (may be `NULL`).

Returns:

Status code.

te_errno te_str_hex_raw2str(const uint8_t* data, size_t data_len, te_string* str)

Convert raw data to hex-string representation

Parameters:

data	Raw data to be converted
data_len	Length of the `data`
str	Pointer to te_string

Returns:

Status code

te_errno te_str_hex_str2raw(const char* str, uint8_t* data, size_t data_len)

Convert hex-string to raw data

Parameters:

str	Null-terminated hex-string
data	Storage to raw data
data_len	The length of the `data`

Returns:

Status code

te_errno te_str_find_index(const char* str, const char** str_array, unsigned int str_array_len, unsigned int* index)

Find index of the string in the array of strings.

Parameters:

str	Null-terminated string
str_array	Array of strings
str_array_len	The length of the `str_array`
index	The index of the `srt` in the `str_array`

Returns:

Status code

char** te_str_make_array(const char* fst, ...)

Copy requested values to the new string array.

Parameters:

fst	Pointer to the first string (it may be `NULL`).
…	Other args for copying (it must end with `NULL`).

Returns:

A pointer to the newly allocated string array with NULL as the last element.

void te_str_free_array(char** str)

Free array of strings

Parameters:

str	The array of strings with `NULL` item at the end

te_errno te_str_compare_versions(const char* v1, const char* v2, int* res)

Compares two version strings in Major.Minor.Patch format.

Major/Minor/Patch parts should consist of digits only.

res may take value that is

>0 if v1 is greater (later) than v2,
<0 if v1 is less (earlier) than v2,
0 if v1 is the same as v2.

Parameters:

v1	First version.
v2	Second version.
res	Comparison result.

Returns:

Status code.

Macros

#define TE_SNPRINTF(_dst, _size, _fmt...)

Fill a destination buffer according to a format string. It is a wrapper for te_snprintf_verbose()

Parameters:

_dst	Pointer to destination buffer
_size	Size of destination buffer
_fmt	Format string with arguments