TIM SDK
TIM API C
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]mapPointer to variable to write created object instance to. Created object instance is retained.
Return values
ta_c_rc_okObject instance has been created and written to map.
ta_c_rc_invalid_argumentmap is null-pointer.
ta_c_rc_out_of_memoryFailed 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]mapObject instance of type map.
[in]keyKey object instance to get value object instance for.
[out]valuePointer to variable to write value object instance to. Written object instance can be ta_invalid_object. Written object instance is not retained.
Return values
ta_c_rc_okObject instance written to to value.
ta_c_rc_invalid_argumentmap is ta_invalid_object.
ta_c_rc_invalid_argumentmap is not of type map.
ta_c_rc_invalid_argumentkey is not present in the map.
ta_c_rc_invalid_argumentvalue 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]mapObject instance of type map.
[in]indexIndex of entry to retrieve.
[out]keyPointer to variable to write key object instance to. Written object instance is not retained.
[out]valuePointer to variable to write value object instance to. Written object instance can be ta_invalid_object. Written object instance is not retained.
Return values
ta_c_rc_okObject instance written to to value.
ta_c_rc_invalid_argumentmap is ta_invalid_object.
ta_c_rc_invalid_argumentmap is not of type map.
ta_c_rc_invalid_argumentindex is less than 0 or greater than or equal to ta_map_count.
ta_c_rc_invalid_argumentkey is null-pointer.
ta_c_rc_invalid_argumentvalue 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]mapObject instance of type map.
[out]countPointer to variable to write count to.
Return values
ta_c_rc_okCount written to to count.
ta_c_rc_invalid_argumentmap is ta_invalid_object.
ta_c_rc_invalid_argumentmap is not of type map.
ta_c_rc_invalid_argumentis_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]mapObject instance of type map.
[in]keyKey object instance to get value object instance for.
[out]valuePointer to variable to write value object instance to. Written object instance can be ta_invalid_object. Written object instance is not retained.
[in]default_valueDefault object instance to use if key object instance is absent from map. Object instance can be ta_invalid_object.
Return values
ta_c_rc_okObject instance written to to value.
ta_c_rc_invalid_argumentmap is ta_invalid_object.
ta_c_rc_invalid_argumentmap is not of type map.
ta_c_rc_invalid_argumentvalue 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]mapObject instance of type map.
[in]keyKey object instance to find.
[out]is_presentPointer 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_okResult written to to is_present.
ta_c_rc_invalid_argumentmap is ta_invalid_object.
ta_c_rc_invalid_argumentmap is not of type map.
ta_c_rc_invalid_argumentis_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]mapObject instance of type map.
[in]keyObject instance to use as key.
Return values
ta_c_rc_okEntry with key object instance removed from map. Key object instance has been released. If value object instance is not ta_invalid_object value object instance has been released.
ta_c_rc_invalid_argumentmap is ta_invalid_object.
ta_c_rc_invalid_argumentmap is not of type map.
ta_c_rc_invalid_argumentmap is read-only.
ta_c_rc_invalid_argumentkey 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]mapObject instance of type map.
Return values
ta_c_rc_okAll entries removed from map. All key object instance have been released. All value object instance that are not ta_invalid_object have been released.
ta_c_rc_invalid_argumentmap is ta_invalid_object.
ta_c_rc_invalid_argumentmap is not of type map.
ta_c_rc_invalid_argumentmap 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]mapObject instance of type map.
[in]keyObject instance to use as key.
[in]valueObject instance to use as value. Object instance can be ta_invalid_object.
Return values
ta_c_rc_okEntry with key and value object instance added to map.
ta_c_rc_invalid_argumentmap is ta_invalid_object.
ta_c_rc_invalid_argumentmap is not of type map.
ta_c_rc_invalid_argumentmap is read-only.
ta_c_rc_invalid_argumentkey is ta_invalid_object.