Regular strings

Overview

Function to operate the strings. More…

// global functions

static te_bool te_str_is_null_or_empty(const char* str);
static const char* te_str_empty_if_null(const char* str);
te_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, ...);
char* te_str_strip_spaces(const char* str);
static const char* te_str_strip_prefix(const char* str, const char* prefix);
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, te_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 te_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

te_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

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.

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, te_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

See also:

TE_SPRINTF

#define TE_SPRINTF(_buf, _fmt...)

Fill a destination buffer according to a format string. It should only be used if the buffer is a real array, not a pointer

See also:

TE_SNPRINTF

#define TE_STRLCPY(_dst, _src, _size)

Call te_strlcpy_verbose() with id “__func__”.

Parameters:

_dst

Destination buffer

_src

String to copy

_size

Size of destination buffer