TIM SDK
TIM API C
string.h File Reference

Description

String value.

Object type string.

String objects are 0-terminated but have an explicit length parameter.

String objects have no defined content encoding. They can contain any kind of encoding depending from where the string object originates.

Functions

ta_e_result_code_t ta_string_create (ta_object_t *string, const char *content, size_t length)
 Create 0-terminated string instance. More...
 
ta_e_result_code_t ta_string_format (ta_object_t *string, const char *format,...)
 Create 0-terminated formatted string instance. More...
 
ta_e_result_code_t ta_string_format_args (ta_object_t *string, const char *format, va_list args)
 Create 0-terminated formatted string instance. More...
 
ta_e_result_code_t ta_string_get_pointer (ta_object_t string, const char **pointer)
 Get 0-terminated string pointer stored in the string object. More...
 
ta_e_result_code_t ta_string_get_length (ta_object_t string, size_t *length)
 Get length of string content in bytes. More...
 

Function Documentation

◆ ta_string_create()

ta_e_result_code_t ta_string_create ( ta_object_t string,
const char *  content,
size_t  length 
)

Create 0-terminated string instance.

String is 0-terminated but has an explicit length parameter.

Caller retains a reference to the created string. Different users can individually retain the string instance themselves by calling ta_object_retain. Each call to ta_object_retain and ta_string_create has to be matched with a call to ta_object_release. The string instance is destroyed once nobody retains the string instance anymore.

Parameters
[out]stringPointer to variable to write created object instance to. Created object instance is retained.
[in]contentString content. 0-bytes are allowed. String is not required to be 0-terminated.
[in]lengthString length in bytes.
Return values
ta_c_rc_okObject instance has been created and written to string.
ta_c_rc_invalid_argumentstring is null-pointer.
ta_c_rc_invalid_argumentcontent is null-pointer.
ta_c_rc_out_of_memoryFailed allocating memory.

◆ ta_string_format()

ta_e_result_code_t ta_string_format ( ta_object_t string,
const char *  format,
  ... 
)

Create 0-terminated formatted string instance.

String is 0-terminated but has an explicit length parameter.

Caller retains a reference to the created string. Different users can individually retain the string instance themselves by calling ta_object_retain. Each call to ta_object_retain and ta_string_create has to be matched with a call to ta_object_release. The string instance is destroyed once nobody retains the string instance anymore.

Parameters
[out]stringPointer to variable to write created object instance to. Created object instance is retained.
[in]formatFormat string. String is required to be 0-terminated.
Return values
ta_c_rc_okObject instance has been created and written to string.
ta_c_rc_invalid_argumentstring is null-pointer.
ta_c_rc_invalid_argumentformat is null-pointer.
ta_c_rc_out_of_memoryFailed allocating memory.

◆ ta_string_format_args()

ta_e_result_code_t ta_string_format_args ( ta_object_t string,
const char *  format,
va_list  args 
)

Create 0-terminated formatted string instance.

String is 0-terminated but has an explicit length parameter.

Caller retains a reference to the created string. Different users can individually retain the string instance themselves by calling ta_object_retain. Each call to ta_object_retain and ta_string_create has to be matched with a call to ta_object_release. The string instance is destroyed once nobody retains the string instance anymore.

Parameters
[out]stringPointer to variable to write created object instance to. Created object instance is retained.
[in]formatFormat string. String is required to be 0-terminated.
[in]argsArguments used for formatting.
Return values
ta_c_rc_okObject instance has been created and written to string.
ta_c_rc_invalid_argumentstring is null-pointer.
ta_c_rc_invalid_argumentformat is null-pointer.
ta_c_rc_out_of_memoryFailed allocating memory.

◆ ta_string_get_length()

ta_e_result_code_t ta_string_get_length ( ta_object_t  string,
size_t *  length 
)

Get length of string content in bytes.

Parameters
[in]stringObject instance of type string.
[out]lengthPointer to variable to write string length to.
Return values
ta_c_rc_okObject instance written to length.
ta_c_rc_invalid_argumentstring is ta_invalid_object.
ta_c_rc_invalid_argumentstring is not of type string.
ta_c_rc_invalid_argumentlength is null-pointer.

◆ ta_string_get_pointer()

ta_e_result_code_t ta_string_get_pointer ( ta_object_t  string,
const char **  pointer 
)

Get 0-terminated string pointer stored in the string object.

The returned string pointer is only valid as long as the string object itself is held and not changed. Use this pointer only for short term direct access to the content like copying the content to user specific data structures outside the reach of Tim API.

Parameters
[in]stringObject instance of type string.
[out]pointerPointer to variable to write string pointer to.
Return values
ta_c_rc_okObject instance written to pointer.
ta_c_rc_invalid_argumentstring is ta_invalid_object.
ta_c_rc_invalid_argumentstring is not of type string.
ta_c_rc_invalid_argumentpointer is null-pointer.