Create and manage "string" objects that encapsulate non-const and const char arrays with explicit length. More...
Typedefs | |
typedef struct _ato_String | ato_String |
The object type encapsulating: C strings and char arrays with length, which can be const and non-const. More... | |
Functions | |
ATO_EXPORT ato_String * | ato_str_create (ato_String **str, char *value, size_t len, bool iscstr) |
Create an ato_String object with the given non-const value and length. More... | |
ATO_EXPORT ato_String * | ato_str_createconst (ato_String **str, const char *value, size_t len, bool iscstr) |
Create an ato_String object with the given const value and length. More... | |
ATO_EXPORT void * | ato_str_free (ato_String *str) |
Free the ato_String object. More... | |
ATO_EXPORT const char * | ato_str_value (const ato_String *str) |
Return the char array as a const. More... | |
ATO_EXPORT size_t | ato_str_len (const ato_String *str) |
Return the length of the char array. More... | |
ATO_EXPORT bool | ato_str_iscstr (ato_String *str) |
Checks if this is was originally set as a null terminated cstr. More... | |
Create and manage "string" objects that encapsulate non-const and const char arrays with explicit length.
Unlike many other languages, C does not associate lengths with "strings" or arrays.
This results in length (size_t) and "string" data (char *) being handled (passed) separately in many methods. Since this is so frequent in the API, ato_String and its associated API, encapsulates length and data together. It can also handle const and non-const char arrays. This should be used for all public methods and, where convenient, for internal methods.
ato_String does not rely on NULL termination of the array.
typedef struct _ato_String ato_String |
The object type encapsulating: C strings and char arrays with length, which can be const and non-const.
This is used as a convenient abstraction by many API methods to tie length to "strings" and to track "constanceness" to determine how content should be free.
ATO_EXPORT ato_String * ato_str_create | ( | ato_String ** | str, |
char * | value, | ||
size_t | len, | ||
bool | iscstr | ||
) |
Create an ato_String object with the given non-const value and length.
See also ato_str_createconst().
str | the address of the object to create. The caller must free with ato_str_free(). |
value | the char array to encapsulate - caller must NOT free. IMPORTANT: the "ownership" of value is transferred to the ato_String object. See ato_str_free(). |
len | the length of the char array. |
iscstr | if TRUE an extra '\0' is expected at the end of the string |
ATO_EXPORT ato_String * ato_str_createconst | ( | ato_String ** | str, |
const char * | value, | ||
size_t | len, | ||
bool | iscstr | ||
) |
Create an ato_String object with the given const value and length.
See also ato_str_create().
str | the address of the object to create. The caller must free with ato_str_free(). |
value | the char array to encapsulate. In this case the array is not freed when calling ato_str_free(). |
len | the length of the char array. |
iscstr | if TRUE an extra '\0' is expected at the end of the string |
ATO_EXPORT void * ato_str_free | ( | ato_String * | str | ) |
Free the ato_String object.
If the underlying value is non-const, then free that as well.
str | the string object. |
ATO_EXPORT const char * ato_str_value | ( | const ato_String * | str | ) |
Return the char array as a const.
str | the string object. |
ATO_EXPORT size_t ato_str_len | ( | const ato_String * | str | ) |
Return the length of the char array.
str | the string object. |
ATO_EXPORT bool ato_str_iscstr | ( | ato_String * | str | ) |
Checks if this is was originally set as a null terminated cstr.
If str is NULL this returns FALSE.
str | the string object. |