pEpEngine/src/stringpair.h

// This file is under GNU General Public License 3.0
// see LICENSE.txt

#pragma once

#include "dynamic_api.h"

#ifdef __cplusplus
extern "C" {
#endif


typedef struct _stringpair_t {
    char * key;   // may point to "" but must not be NULL!
    char * value; // may point to "" but must not be NULL!
} stringpair_t;


// new_stringpair() - allocate new stringpair_t
//
//  parameters:
//      key (in)        utf-8 string used as key, should not be NULL
//      value (in)      utf-8 string containing the value, should not be NULL
//
//  return value:
//      pointer to stringpair_t or NULL on failure
//
//  caveat:
//      key and value are copied and remain in the ownership of the caller

DYNAMIC_API stringpair_t * new_stringpair(const char *key, const char *value);


// free_stringpair() - free memory allocated by stringpair_t
//
//  parameters:
//      pair (in)       pointer to stringpair_t to free

DYNAMIC_API void free_stringpair(stringpair_t * pair);


// stringpair_dup() - duplicate stringpair_t (deep copy)
//
//  parameters:
//      src (in)        pointer to stringpair_t to duplicate
//
//  return value:
//      pointer to copy of src or NULL on failure

DYNAMIC_API stringpair_t * stringpair_dup(const stringpair_t *src);


typedef struct _stringpair_list_t {
    stringpair_t *value;
    struct _stringpair_list_t *next;
} stringpair_list_t;


// new_stringpair_list() - allocate a new stringpair_list
//
//  parameters:
//      value (in)              initial value
//
//  return value:
//      pointer to stringpair_list_t object or NULL if out of memory
//
//  caveat:
//      the ownership of the value goes to the stringpair_list
//      next pointer is NULL

DYNAMIC_API stringpair_list_t *new_stringpair_list(stringpair_t *value);


// stringpair_list_dup() - duplicate a stringpair_list (deep copy)
//
//  parameters:
//      src (in)                stringpair_list to copy
//
//  return value:
//      pointer to stringpair_list_t object or NULL if out of memory
//      stringpair value copies created by this function belong to the returned list

DYNAMIC_API stringpair_list_t *stringpair_list_dup(
        const stringpair_list_t *src
    );


// stringpair_list_add() - add key to stringpair_list
//
//  parameters:
//      stringpair_list (in)    stringpair_list struct or NULL to create a new
//                              one
//      value (in)              stringpair to add
//
//  return value:
//      pointer to last element in stringpair_list or NULL if out of memory
//
//  caveat:
//      the ownership of the value goes to the stringpair_list if add is successful

DYNAMIC_API stringpair_list_t *stringpair_list_add(
        stringpair_list_t *stringpair_list,
        stringpair_t *value
    );


// stringpair_list_append() - append stringpair_list to stringpair_list
//
//  parameters:
//      stringpair_list (in)    stringpair_list struct to append to
//      second (in)             stringpair_list struct to append
//
//  return value:
//      pointer to last element in stringpair_list or NULL if out of memory
//      or stringpair_list is NULL
//
//  caveat:
//      all values are being copied before being added to the list
//      the original values are still being owned by the caller

DYNAMIC_API stringpair_list_t *stringpair_list_append(
        stringpair_list_t *stringpair_list,
        stringpair_list_t *second
    );


// stringpair_list_length() - get length of stringpair_list
//
//  parameters:
//      stringpair_list (in)    stringpair_list struct to determine length of
//
//  return value:
//      length of stringpair_list in number of elements

DYNAMIC_API int stringpair_list_length(
        const stringpair_list_t *stringpair_list
    );


// free_stringpair_list() - free memory occupied by stringpair_list
//
//  parameters:
//      stringpair_list (in)    stringpair_list to free

DYNAMIC_API void free_stringpair_list(stringpair_list_t *stringpair_list);


// stringpair_list_find() - find element in list using key
//
//  parameters:
//      stringpair_list (in)    list to search
//      key (in)                key to search for
//
//  return value:
//      node with result if found or NULL if not

DYNAMIC_API stringpair_list_t *stringpair_list_find(
        stringpair_list_t *stringpair_list,
        const char *key
    );

// ONLY DELETES ONE.
DYNAMIC_API stringpair_list_t *stringpair_list_delete_by_key(
        stringpair_list_t *sp_list,
        const char *key
    );


#ifdef __cplusplus
}
#endif