map.h File Reference

Description

Map value.

Object type map.

Functions
ta_e_result_code_t	ta_map_create (ta_object_t *map)
	Create empty map. More...
ta_e_result_code_t	ta_map_set (ta_object_t map, ta_object_t key, ta_object_t value)
	Set entry in map. More...
ta_e_result_code_t	ta_map_remove (ta_object_t map, ta_object_t key)
	Remove entry from map. More...
ta_e_result_code_t	ta_map_remove_all (ta_object_t map)
	Remove all entries from map. More...
ta_e_result_code_t	ta_map_has (ta_object_t map, ta_object_t key, ta_e_boolean_t *is_present)
	Entry is present in map. More...
ta_e_result_code_t	ta_map_get_count (ta_object_t map, size_t *count)
	Get number of entries in map. More...
ta_e_result_code_t	ta_map_get (ta_object_t map, ta_object_t key, ta_object_t *value)
	Get value for key in map. More...
ta_e_result_code_t	ta_map_get_default (ta_object_t map, ta_object_t key, ta_object_t *value, ta_object_t default_value)
	Get value for key in map or default value if absent. More...
ta_e_result_code_t	ta_map_get_at (ta_object_t map, size_t index, ta_object_t *key, ta_object_t *value)
	Get key and value by index from map. More...

Function Documentation

ta_map_create()

ta_e_result_code_t ta_map_create

(

ta_object_t *

map

)

Create empty map.

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

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

Parameters

[out]

map

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 map.
ta_c_rc_invalid_argument	map is null-pointer.
ta_c_rc_out_of_memory	Failed allocating memory.

ta_map_get()

ta_e_result_code_t ta_map_get	(	ta_object_t	map,
		ta_object_t	key,
		ta_object_t *	value
	)

Get value for key in map.

Value is not retained. User has to call ta_object_retain to hold the returned object outside of the map.

Parameters

[in]	map	Object instance of type map.
[in]	key	Key object instance to get value object instance for.
[out]	value	Pointer to variable to write value object instance to. Written object instance can be ta_object_invalid. Written object instance is not retained.

Return values

ta_c_rc_ok	Object instance written to to value.
ta_c_rc_invalid_argument	map is ta_object_invalid.
ta_c_rc_invalid_argument	map is not of type map.
ta_c_rc_invalid_argument	key is not present in the map.
ta_c_rc_invalid_argument	value is null-pointer.

ta_map_get_at()

ta_e_result_code_t ta_map_get_at	(	ta_object_t	map,
		size_t	index,
		ta_object_t *	key,
		ta_object_t *	value
	)

Get key and value by index from map.

Warning

This is for iteration purpose only. The order of entries in the map can change with any call to ta_map_set and ta_map_remove.

Key and value are not retained. User has to call ta_object_retain to hold the returned objects outside of the map.

Parameters

[in]	map	Object instance of type map.
[in]	index	Index of entry to retrieve.
[out]	key	Pointer to variable to write key object instance to. Written object instance is not retained.
[out]	value	Pointer to variable to write value object instance to. Written object instance can be ta_object_invalid. Written object instance is not retained.

Return values

ta_c_rc_ok	Object instance written to to value.
ta_c_rc_invalid_argument	map is ta_object_invalid.
ta_c_rc_invalid_argument	map is not of type map.
ta_c_rc_invalid_argument	index is less than 0 or greater than or equal to ta_map_count.
ta_c_rc_invalid_argument	key is null-pointer.
ta_c_rc_invalid_argument	value is null-pointer.

ta_map_get_count()

ta_e_result_code_t ta_map_get_count	(	ta_object_t	map,
		size_t *	count
	)

Get number of entries in map.

Parameters

[in]	map	Object instance of type map.
[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	map is ta_object_invalid.
ta_c_rc_invalid_argument	map is not of type map.
ta_c_rc_invalid_argument	is_present is null-pointer.

ta_map_get_default()

ta_e_result_code_t ta_map_get_default	(	ta_object_t	map,
		ta_object_t	key,
		ta_object_t *	value,
		ta_object_t	default_value
	)

Get value for key in map or default value if absent.

Value is not retained. User has to call ta_object_retain to hold the returned object outside of the map.

Parameters

[in]	map	Object instance of type map.
[in]	key	Key object instance to get value object instance for.
[out]	value	Pointer to variable to write value object instance to. Written object instance can be ta_object_invalid. Written object instance is not retained.
[in]	default_value	Default object instance to use if key object instance is absent from map. Object instance can be ta_object_invalid.

Return values

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

ta_map_has()

ta_e_result_code_t ta_map_has	(	ta_object_t	map,
		ta_object_t	key,
		ta_e_boolean_t *	is_present
	)

Entry is present in map.

Parameters

[in]	map	Object instance of type map.
[in]	key	Key object instance to find.
[out]	is_present	Pointer to variable to write result to. Set to ta_c_b_true if key is present in map. Set to ta_c_b_false if key is absent from map.

Return values

ta_c_rc_ok	Result written to to is_present.
ta_c_rc_invalid_argument	map is ta_object_invalid.
ta_c_rc_invalid_argument	map is not of type map.
ta_c_rc_invalid_argument	is_present is null-pointer.

ta_map_remove()

ta_e_result_code_t ta_map_remove	(	ta_object_t	map,
		ta_object_t	key
	)

Remove entry from map.

Entry key and value are release if not null-pointer.

Parameters

[in]	map	Object instance of type map.
[in]	key	Object instance to use as key.

Return values

ta_c_rc_ok	Entry with key object instance removed from map. Key object instance has been released. If value object instance is not ta_object_invalid value object instance has been released.
ta_c_rc_invalid_argument	map is ta_object_invalid.
ta_c_rc_invalid_argument	map is not of type map.
ta_c_rc_invalid_argument	map is read-only.
ta_c_rc_invalid_argument	key is not present in the map.

ta_map_remove_all()

ta_e_result_code_t ta_map_remove_all

(

ta_object_t

map

)

Remove all entries from map.

Keys and values of removed entries are release if not null-pointer.

Parameters

[in]

map

Object instance of type map.

Return values

ta_c_rc_ok	All entries removed from map. All key object instance have been released. All value object instance that are not ta_object_invalid have been released.
ta_c_rc_invalid_argument	map is ta_object_invalid.
ta_c_rc_invalid_argument	map is not of type map.
ta_c_rc_invalid_argument	map is read-only.

ta_map_set()

ta_e_result_code_t ta_map_set	(	ta_object_t	map,
		ta_object_t	key,
		ta_object_t	value
	)

Set entry in map.

If entry is added the key and value are retained if not null-pointer. Adding null-pointers as value to map is allowed. The user is responsible to verify no null-pointers are added to the map if desired.

Parameters

[in]	map	Object instance of type map.
[in]	key	Object instance to use as key.
[in]	value	Object instance to use as value. Object instance can be ta_object_invalid.

Return values

ta_c_rc_ok	Entry with key and value object instance added to map.
ta_c_rc_invalid_argument	map is ta_object_invalid.
ta_c_rc_invalid_argument	map is not of type map.
ta_c_rc_invalid_argument	map is read-only.
ta_c_rc_invalid_argument	key is ta_object_invalid.