C-String utility functions

group jsdrv_cstr

C-style string utilities.

This module supplies c-style (null terminated byte array) string utilities. The utilities are designed for memory safety (unlike <string.h>).

Defines

jsdrv_cstr_array_copy(tgt, src)

Safely copy src to tgt.

Parameters:

  • tgt – The null-terminated destination character array.

  • src – The null-terminated source string.

Returns:

0 on success, 1 if truncated, -1 on other errors.

Functions

int jsdrv_cstr_copy(char *tgt, char const *src, size_t tgt_size)

Safely copy src to tgt.

Parameters:

  • tgt – The null-terminated destination string.

  • src – The null-terminated source string. If NULL, then tgt will be populated with an empty string.

  • tgt_size – The total number of total_bytes available in tgt.

Returns:

0 on success, 1 if truncated, -1 on tgt NULL or tgt_size <= 0.

int jsdrv_cstr_join(char *tgt, char const *src1, char const *src2, size_t tgt_size)

Safely copy src to tgt.

Parameters:

  • tgt – The null-terminated destination string.

  • src1 – The first null-terminated source string. tgt may be src1.

  • src2 – The second null-terminated source string. tgt may NOT be src2.

  • tgt_size – The total number of total_bytes available in tgt.

Returns:

0 on success, 1 if truncated, -1 on tgt NULL or tgt_size <= 0.

int jsdrv_cstr_casecmp(const char *s1, const char *s2)

Compare strings ignoring case.

Parameters:

  • s1 – The first null-terminated string.

  • s2 – The second null-terminated string.

Returns:

0 if s1 and s2 are comparable, -1 if s1 < s2, 1 if s2 > s1.

const char *jsdrv_cstr_starts_with(const char *s, const char *prefix)

Determine if a string starts with another string.

Parameters:

  • s – The string to search.

  • prefix – The case-sensitive string prefix to match in s.

Returns:

0 on no match. On match, return the pointer to s at the location of the first character after the matching prefix.

const char *jsdrv_cstr_ends_with(const char *s, const char *prefix)

Determine if a string ends with another string.

Parameters:

  • s – The string to search.

  • prefix – The case-sensitive string suffix to match in s.

Returns:

0 on no match. On match, return the pointer to s at the location of the first character matching the suffix.

int jsdrv_cstr_to_u32(const char *src, uint32_t *value)

Convert a string to an unsigned 32-bit integer.

Parameters:

  • src – The input source string containing an integer. Strings that start with “0x” are processed as case-insensitive hexadecimal.

  • value – The output unsigned 32-bit integer value.

Returns:

0 on success or error code. On error, the value will not be modified. To allow default values on parsing errors, set value before calling this function.

int jsdrv_cstr_to_i32(const char *src, int32_t *value)

Convert a string to an signed 32-bit integer.

Parameters:

  • src – The input source string containing an integer.

  • value – The output integer value.

Returns:

0 on success or error code. On error, the value will not be modified. To allow default values on parsing errors, set value before calling this function.

int jsdrv_cstr_to_i32s(const char *src, int32_t exponent, int32_t *value)

Convert a fractional value into a scaled 32-bit integer.

Examples: 

jsdrv_cstr_to_i32s("1", 0, &x) => 1
jsdrv_cstr_to_i32s("1", 2, &x) => 100
jsdrv_cstr_to_i32s("1.01", 2, &x) => 101
jsdrv_cstr_to_i32s("   1.01   ", 2, &x) => 101
jsdrv_cstr_to_i32s("+1.01", 2, &x) => 101
jsdrv_cstr_to_i32s("-1.01", 2, &x) => -101
jsdrv_cstr_to_i32s("1.019", 2, &x) => 101

Parameters:

  • src – The input source string. Excess fractional digits will be truncated and ignored, not rounded.

  • exponent – The base10 exponent.

  • value – The resulting integer value.

Returns:

0 on success or error code. On error, the value will not be modified. To allow default values on parsing errors, set value before calling this function.

int jsdrv_cstr_to_u64(const char *src, uint64_t *value)

Convert a string to an unsigned 64-bit integer.

Parameters:

  • src – The input source string containing an integer. Strings that start with “0x” are processed as case-insensitive hexadecimal.

  • value – The output unsigned 64-bit integer value.

Returns:

0 on success or error code. On error, the value will not be modified. To allow default values on parsing errors, set value before calling this function.

int jsdrv_cstr_to_i64(const char *src, int64_t *value)

Convert a string to an signed 64-bit integer.

Parameters:

  • src – The input source string containing an integer.

  • value – The output integer value.

Returns:

0 on success or error code. On error, the value will not be modified. To allow default values on parsing errors, set value before calling this function.

int jsdrv_cstr_to_f32(const char *src, float *value)

Convert a string to a floating point number.

Parameters:

  • src – The input source string containing a floating point number.

  • value – The output floating point value.

Returns:

0 on success or error code. On error, the value will not be modified. To allow default values on parsing errors, set value before calling this function.

int jsdrv_u32_to_cstr(uint32_t u32, char *str, size_t str_size)

Convert an unsigned 32-bit integer to a string.

Parameters:

  • u32 – The input unsigned 32-bit integer value.

  • str – The output string. To support all values, it should have at least 11 bytes free.

  • str_size – The available bytes in str.

Returns:

0 on success or error code. On error, return str[0] = 0 unless size is <= 0.

int jsdrv_cstr_toupper(char *s)

Convert a string to upper case.

Equivalent to nonstandard strupr().

Parameters:

s – [inout] The null-terminated ASCII string to convert which is modified in place. This function will corrupt UTF-8 data! NULL will cause error. All other inputs are valid and return success.

Returns:

0 on success or error code.

int jsdrv_cstr_to_index(char const *s, char const *const *table, int *index)

Convert a string value into an index into table.

Parameters:

  • s – [in] The null-terminated ASCII string value input.

  • table – [in] The list of possible null-terminated string values. The list is terminated with a NULL entry.

  • index – [inout] The output index. Index is only modified on a successful conversion, a default value can be set before calling this function.

Returns:

0 or error code.

int jsdrv_cstr_to_bool(char const *s, bool *value)

Convert a string value into a boolean.

Parameters:

  • s – [in] The null-terminated ASCII string value input which is not case sensitive. True values include “TRUE”, “ON”, “1”, “ENABLE”. False values include “FALSE”, “OFF”, “0”, “DISABLE”.

  • value – [inout] The output value. Value is only modified on a successful conversion, a default value can be set before calling this function.

Returns:

SUCCESS or error code.

uint8_t jsdrv_cstr_hex_to_u4(char v)

Convert a hex character to a 4-bit nibble.

Parameters:

v – The ASCII character value to convert.

Returns:

The nibble value (0 to 16) or 0 on error.

char jsdrv_cstr_u4_to_hex(uint8_t v)

Convert a 4-bit nibble to a hex character.

Parameters:

v – The 4-bit nibble value.

Returns:

The ASCII character value or ‘0’ on error.