list.h File Reference

Description

List value.

Object type list.

Functions
ta_e_result_code_t	ta_list_create (ta_object_t *list)
	Create empty list. More...
ta_e_result_code_t	ta_list_add (ta_object_t list, ta_object_t element)
	Add element to list. More...
ta_e_result_code_t	ta_list_remove (ta_object_t list, size_t index)
	Remove element from list. More...
ta_e_result_code_t	ta_list_remove_all (ta_object_t list)
	Remove all elements from list. More...
ta_e_result_code_t	ta_list_has (ta_object_t list, ta_object_t element, ta_e_boolean_t *is_present)
	Element is present in list. More...
ta_e_result_code_t	ta_list_get_count (ta_object_t list, size_t *count)
	Get number of elements in list. More...
ta_e_result_code_t	ta_list_get_at (ta_object_t list, size_t index, ta_object_t *element)
	Get element at index in list. More...
ta_e_result_code_t	ta_list_index_of (ta_object_t list, ta_object_t element, int *index)
	Get index of first occurance of element or -1 if absent. More...

Function Documentation

ta_list_add()

ta_e_result_code_t ta_list_add	(	ta_object_t	list,
		ta_object_t	element
	)

Add element to list.

Added element is retained if not null-pointer. Adding null-pointers to list is allowed. The user is responsible to verify no null-pointers are added to the list if desired.

Parameters

[in]	list	Object instance of type list.
[in]	element	Object instance to add. Object instance can be ta_invalid_object.

Return values

ta_c_rc_ok	Object instance added to list.
ta_c_rc_invalid_argument	list is ta_invalid_object.
ta_c_rc_invalid_argument	list is not of type list.
ta_c_rc_invalid_argument	list is read-only.

ta_list_create()

ta_e_result_code_t ta_list_create

(

ta_object_t *

list

)

Create empty list.

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

Lists can be read-only. In this case all functions trying to modify the list return an error.

Parameters

[out]

list

Pointer to variable to write created object instance to. Created object instance is retained.

Return values

ta_c_rc_ok	Object instance has been created and written to list.
ta_c_rc_invalid_argument	list is null-pointer.
ta_c_rc_out_of_memory	Failed allocating memory.

ta_list_get_at()

ta_e_result_code_t ta_list_get_at	(	ta_object_t	list,
		size_t	index,
		ta_object_t *	element
	)

Get element at index in list.

Returned element is not retained. User has to call ta_object_retain to hold the returned object outside of the list.

Parameters

[in]	list	Object instance of type list.
[in]	index	Index of element to get.
[out]	element	Pointer to variable to write object instance to. Written object instance can be ta_invalid_object. Written object instance is not retained.

Return values

ta_c_rc_ok	Object instance written to to element.
ta_c_rc_invalid_argument	list is ta_invalid_object.
ta_c_rc_invalid_argument	list is not of type list.
ta_c_rc_invalid_argument	element is null-pointer.
ta_c_rc_invalid_argument	index is less than 0.
ta_c_rc_invalid_argument	index is larger than or equal to element count.

ta_list_get_count()

ta_e_result_code_t ta_list_get_count	(	ta_object_t	list,
		size_t *	count
	)

Get number of elements in list.

Parameters

[in]	list	Object instance of type list.
[out]	count	Pointer to variable to write count to.

Return values

ta_c_rc_ok	Count written to to count.
ta_c_rc_invalid_argument	list is ta_invalid_object.
ta_c_rc_invalid_argument	list is not of type list.
ta_c_rc_invalid_argument	is_present is null-pointer.

ta_list_has()

ta_e_result_code_t ta_list_has	(	ta_object_t	list,
		ta_object_t	element,
		ta_e_boolean_t *	is_present
	)

Element is present in list.

Parameters

[in]	list	Object instance of type list.
[in]	element	Object instance to find. Object instance can be ta_invalid_object.
[out]	is_present	Pointer to variable to write result to. Set to ta_c_b_true if element is present in list. Set to ta_c_b_false if element is absent from list.

Return values

ta_c_rc_ok	Result written to to is_present.
ta_c_rc_invalid_argument	list is ta_invalid_object.
ta_c_rc_invalid_argument	list is not of type list.
ta_c_rc_invalid_argument	is_present is null-pointer.

ta_list_index_of()

ta_e_result_code_t ta_list_index_of	(	ta_object_t	list,
		ta_object_t	element,
		int *	index
	)

Get index of first occurance of element or -1 if absent.

Parameters

[in]	list	Object instance of type list.
[in]	element	Object instance to search for. Object instance can be ta_invalid_object.
[out]	index	Pointer to variable to write index to. Index is -1 if element is absent.

Return values

ta_c_rc_ok	Object instance written to to element.
ta_c_rc_invalid_argument	list is ta_invalid_object.
ta_c_rc_invalid_argument	list is not of type list.
ta_c_rc_invalid_argument	index is null-pointer.

ta_list_remove()

ta_e_result_code_t ta_list_remove	(	ta_object_t	list,
		size_t	index
	)

Remove element from list.

Removed element is release if not null-pointer.

Parameters

[in]	list	Object instance of type list.
[in]	index	Index of element to remove.

Return values

ta_c_rc_ok	Object instance removed from list.
ta_c_rc_invalid_argument	list is ta_invalid_object.
ta_c_rc_invalid_argument	list is not of type list.
ta_c_rc_invalid_argument	list is read-only.
ta_c_rc_invalid_argument	index is less than 0.
ta_c_rc_invalid_argument	index is larger than or equal to element count.

ta_list_remove_all()

ta_e_result_code_t ta_list_remove_all

(

ta_object_t

list

)

Remove all elements from list.

Removed element are release if not null-pointer.

Parameters

[in]

list

Object instance of type list.

Return values

ta_c_rc_ok	All object instances removed from list.
ta_c_rc_invalid_argument	list is ta_invalid_object.
ta_c_rc_invalid_argument	list is not of type list.
ta_c_rc_invalid_argument	list is read-only.