atobase 3.2.0
ATOMAS atobase
String

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_Stringato_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_Stringato_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...
 

Detailed Description

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 Documentation

◆ ato_String

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.

Function Documentation

◆ ato_str_create()

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().

Parameters
strthe address of the object to create. The caller must free with ato_str_free().
valuethe char array to encapsulate - caller must NOT free. IMPORTANT: the "ownership" of value is transferred to the ato_String object. See ato_str_free().
lenthe length of the char array.
iscstrif TRUE an extra '\0' is expected at the end of the string
Returns
pointer to the allocated ato_String object or NULL if allocation failed. Note that, currently, out of memory errors result in assert failures.

◆ ato_str_createconst()

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().

Parameters
strthe address of the object to create. The caller must free with ato_str_free().
valuethe char array to encapsulate. In this case the array is not freed when calling ato_str_free().
lenthe length of the char array.
iscstrif TRUE an extra '\0' is expected at the end of the string
Returns
pointer to the allocated ato_String object or NULL if allocation failed. Note that, currently, out of memory errors result in assert failures.

◆ ato_str_free()

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.

Parameters
strthe string object.
Returns
NULL

◆ ato_str_value()

ATO_EXPORT const char * ato_str_value ( const ato_String str)

Return the char array as a const.

Parameters
strthe string object.
Returns
the char array or NULL if currently not assigned or str is NULL.

◆ ato_str_len()

ATO_EXPORT size_t ato_str_len ( const ato_String str)

Return the length of the char array.

Parameters
strthe string object.
Returns
the length of the char array. 0 is returned if NULL or empty.

◆ ato_str_iscstr()

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.

Parameters
strthe string object.
Returns
TRUE or FALSE.