# C-String utility functions ### *group* C-style string utilities C-style string utilities. This module supplies c-style (null terminated byte array) string utilities. The utilities are designed for memory safety (unlike ). ### 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 ### int32_t jsdrv_cstr_copy(char \*tgt, const char \*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. ### int32_t jsdrv_cstr_join(char \*tgt, const char \*src1, const char \*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. ### int32_t 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 \*suffix) Determine if a string ends with another string. * **Parameters:** * **s** – The string to search. * **suffix** – 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. ### int32_t 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. ### int32_t 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. ### int32_t jsdrv_cstr_to_i32s(const char \*src, int32_t exponent, int32_t \*value) Convert a fractional value into a scaled 32-bit integer. Examples: ```default 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. ### int32_t 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. ### int32_t 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. ### int32_t 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. ### int32_t 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. ### int32_t 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. ### int32_t jsdrv_cstr_to_index(const char \*s, const char \*const \*table, int32_t \*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. ### int32_t jsdrv_cstr_to_bool(const char \*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 15) 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.