Container Map

  • This file contains a set of functions to perform the Container Map-specific APIs.

  • The container map functionalities are based on a sorted singly linked list concept.

  • The first four bytes of memory are reserved (0 to 3). From the next byte onwards, data is structured as single nodes.

  • Each node contains a header, key, and value.

Map Structure Format

  • In map buffer, the structure format of map contains header, key and value. The key and value has different size. Following is the cases that container map supports different types of key-value pair structures:

Case 1 - Key and Value (Except String or Complex Data Types)

  • Header - 4 bytes (default)

  • Key - Depends on the key data size

  • Value - Depends on the value data size

This is considered a single node.

Case 2 - Key and Value (String or Complex Data Types like Arrays, Structures, etc.)

  • Header - 4 bytes (default)

  • Key Length - 1 byte

  • Key - Depends on the key length

  • Value Length - 1 byte

  • Value - Depends on the value length

This is considered a single node.

Case 3 - Key (String) and Value (Fixed Data Type: uint8, int8, uint16, int16, uint32, int32, float, double)

  • Header - 4 bytes (default)

  • Key Length - 1 byte

  • Key - Depends on the key size

  • Value - Fixed data type size

This is considered a single node.

Case 4 - Key (Fixed Data Type) and Value (String)

  • Header - 4 bytes (default)

  • Key - Depends on the key size

  • Value Length - 1 byte

  • Value - Depends on the value length

This is considered a single node.

Usage

  1. All API functions use the first argument as the container map instance.

  2. The container is initialized with a specified maximum capacity.

  3. Data is inserted using a key-value pair mechanism.

  4. Supports retrieval, deletion, and checking the existence of keys.

  5. Ensures efficient space utilization by reusing deleted slots.

  6. Return codes of API functions are defined in the header file .

Container Map Calls

Function

Description

rs_map_init

Function to initialize the container map with a given size

rs_map_set

Function to insert a key-value pair into the container map

rs_map_get

Function to retrieve a value based on the key

rs_map_erase

Function to delete a key-value pair from the container map

rs_map_erase_all

Function to delete all key-value pair from the container map

rs_map_get_num_entries

Function to get the current number of entries in the container map

rs_map_is_full

Function to check if the container map is full

Features Supported

  • The container map supports dynamic key-value storage.

  • Efficient deletion mechanism ensures space is reused.

  • Allows querying whether a key exists before accessing.

  • Supports fixed or variable-sized storage for values.

  • Provides a method to clear all stored entries when needed.

Limitations

  • Container Map (Key - string data type, Value - string/any data type) Set support only for fresh new node (Erased old free node not supported)

Error Code

  • Every API function for the container map module returns success or failure values. Please refer to the following section:

    RAPIDSEA ERROR CODES

Example Demo

Please refer to the following section:

Container Map Header Details

Documentation from the relevant header is as follows:

Dispatcher Specific APIs.

Defines macros and functions specific to Rapidsea container MAP functionality

Author

Embien RAPIDSEA Team

Copyright

Embien Technologies India Pvt. Ltd.

Defines

RS_MAP_MAX_SIZE

Maximum size of the map.

RS_MAP_INVALID
RS_MAP_KEY_TYPE_STRING
RS_MAP_KEY_TYPE_INT8S
RS_MAP_KEY_TYPE_INT8U
RS_MAP_KEY_TYPE_INT16S
RS_MAP_KEY_TYPE_INT16U
RS_MAP_KEY_TYPE_INT32S
RS_MAP_KEY_TYPE_INT32U
RS_MAP_KEY_TYPE_FLOAT
RS_MAP_VALUE_TYPE_STRING
RS_MAP_VALUE_TYPE_INT8S
RS_MAP_VALUE_TYPE_INT8U
RS_MAP_VALUE_TYPE_INT16S
RS_MAP_VALUE_TYPE_INT16U
RS_MAP_VALUE_TYPE_INT32S
RS_MAP_VALUE_TYPE_INT32U
RS_MAP_VALUE_TYPE_FLOAT
RS_MAP_VALUE_TYPE_ANY

Typedefs

typedef struct tag_rs_map_info rs_map_info_t

Structure of map information.

Functions

rs_ret_val_t rs_map_init(rs_map_info_t *ptr_map_info, uint8_t *ptr_buff, uint32_t u32_buff_size, uint8_t u8_key_type, uint8_t u8_val_type)

Initializes the Map with key and value.

This function init the map with key and value and map entry information

Parameters:

  • ptr_map_info – [in] - Pointer to the Map information

  • ptr_buff – [in] - Pointer to the map buff

  • u32_buff_size – [in] - Size of the map buffer

  • u8_key_type – [in] - Data type of the key

  • u8_val_type – [in] - Data type of the value

Returns:

return 0 for success negative value for failure

rs_ret_val_t rs_map_set(rs_map_info_t *ptr_map_info, void *ptr_key, void *ptr_value, uint32_t u32_key_size, uint32_t u32_value_size)

Sets the key information and value to the map.

This function sets the key information and value information to the corresponding key to the map

Parameters:

  • ptr_map_info – [in] - Pointer to the Map information

  • ptr_key – [in] - Pointer to the key information

  • ptr_value – [in] - Pointer to the value information

  • u32_key_size – [in] - Size of the key

  • u32_value_size – [in] - Size of the value

Returns:

return 0 for success negative value for failure

rs_ret_val_t rs_map_get(rs_map_info_t *ptr_map_info, void *ptr_key, void *ptr_value)

Gets the key information and value from the map.

This function gets the value information to the corresponding key from the map

Parameters:

  • ptr_map_info – [in] - Pointer to the Map information

  • ptr_key – [in] - Pointer to the key information

  • ptr_value – [in] - Pointer to the value information

Returns:

return 0 for success negative value for failure

rs_ret_val_t rs_map_get_num_entries(rs_map_info_t *ptr_map_info)

Gets the number of entries in the map.

This function gets number of entries in the map

Parameters:

ptr_map_info – [in] - Pointer to the Map information

Returns:

return number of entries for success negative value for failure

rs_ret_val_t rs_map_erase(rs_map_info_t *ptr_map_info, void *ptr_key)

Erase the key information and value in the map.

This function erase the particular key and value to the corresponding key

Parameters:

  • ptr_map_info – [in] - Pointer to the Map information

  • ptr_key – [in] - Pointer to the key information

Returns:

return 0 for success negative value for failure

rs_ret_val_t rs_map_erase_all(rs_map_info_t *ptr_map_info)

Erase entire key information and value information in the map.

This function erase the entire key and value information

Parameters:

ptr_map_info – [in] - Pointer to the Map information

Returns:

return 0 for success negative value for failure

rs_ret_val_t rs_map_is_full(rs_map_info_t *ptr_map_info)

Checks whether the map is full or not.

This function checks the map is full or not

Parameters:

ptr_map_info – [in] - Pointer to the Map information

Returns:

return 1 for success , negative value for failure

struct tag_rs_map_info
#include <rs_map.h>

Structure of map information.

Public Members

uint8_t *ptr_map_buff

Pointer to the map buffer.

uint32_t buff_size

Size of the map buffer.

uint32_t num_entry

Number of entries.

int32_t last_write_index

Last write index.

uint8_t key_type

Data type of the key.

uint8_t value_type

Data type of the value.

uint32_t first_offset

Least key offset.

uint32_t first_free_offset

Free map offset.