// 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

    );

#ifdef __cplusplus

}

#endif