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]	string	Pointer to variable to write created object instance to. Created object instance is retained.
[in]	content	String content. 0-bytes are allowed. String is not required to be 0-terminated.
[in]	length	String length in bytes.

Return values

ta_c_rc_ok	Object instance has been created and written to string.
ta_c_rc_invalid_argument	string is null-pointer.
ta_c_rc_invalid_argument	content is null-pointer.
ta_c_rc_out_of_memory	Failed 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]	string	Pointer to variable to write created object instance to. Created object instance is retained.
[in]	format	Format string. String is required to be 0-terminated.

Return values

ta_c_rc_ok	Object instance has been created and written to string.
ta_c_rc_invalid_argument	string is null-pointer.
ta_c_rc_invalid_argument	format is null-pointer.
ta_c_rc_out_of_memory	Failed 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]	string	Pointer to variable to write created object instance to. Created object instance is retained.
[in]	format	Format string. String is required to be 0-terminated.
[in]	args	Arguments used for formatting.

Return values

ta_c_rc_ok	Object instance has been created and written to string.
ta_c_rc_invalid_argument	string is null-pointer.
ta_c_rc_invalid_argument	format is null-pointer.
ta_c_rc_out_of_memory	Failed 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]	string	Object instance of type string.
[out]	length	Pointer to variable to write string length to.

Return values

ta_c_rc_ok	Object instance written to length.
ta_c_rc_invalid_argument	string is ta_object_invalid.
ta_c_rc_invalid_argument	string is not of type string.
ta_c_rc_invalid_argument	length 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]	string	Object instance of type string.
[out]	pointer	Pointer to variable to write string pointer to.

Return values

ta_c_rc_ok	Object instance written to pointer.
ta_c_rc_invalid_argument	string is ta_object_invalid.
ta_c_rc_invalid_argument	string is not of type string.
ta_c_rc_invalid_argument	pointer is null-pointer.