src/stringpair.h
author Roker <roker@pep-project.org>
Tue, 20 Sep 2016 15:54:57 +0200
branchroker-linux
changeset 1168 4d4e3ecbaf8b
parent 909 e39e9fec2da0
child 1285 e9015701a9b4
permissions -rw-r--r--
merge "default" into my branch
vb@98
     1
#pragma once
vb@98
     2
vb@98
     3
#include "dynamic_api.h"
vb@98
     4
vb@98
     5
#ifdef __cplusplus
vb@98
     6
extern "C" {
vb@98
     7
#endif
vb@98
     8
vb@98
     9
vb@98
    10
typedef struct _stringpair_t {
roker@786
    11
    char * key;   // may point to "" but must not be NULL!
roker@786
    12
    char * value; // may point to "" but must not be NULL!
vb@98
    13
} stringpair_t;
vb@98
    14
vb@98
    15
vb@98
    16
// new_stringpair() - allocate new stringpair_t
vb@98
    17
//
vb@98
    18
//  parameters:
roker@786
    19
//      key (in)        utf-8 string used as key; may point to "" but must not be NULL!
roker@786
    20
//      value (in)      utf-8 string containing the value; may point to "" but must not be NULL!
vb@98
    21
//
vb@98
    22
//  return value:
vb@98
    23
//      pointer to stringpair_t or NULL on failure
vb@98
    24
//
vb@98
    25
//  caveat:
vb@98
    26
//      key and value are copied and remain in the ownership of the caller
vb@98
    27
vb@98
    28
DYNAMIC_API stringpair_t * new_stringpair(const char *key, const char *value);
vb@98
    29
vb@98
    30
vb@98
    31
// free_stringpair() - free memory allocated by stringpair_t
vb@98
    32
//
vb@98
    33
//  parameters:
vb@98
    34
//      pair (in)       pointer to stringpair_t to free
vb@98
    35
vb@98
    36
DYNAMIC_API void free_stringpair(stringpair_t * pair);
vb@98
    37
vb@98
    38
vb@98
    39
// stringpair_dup() - duplicate stringpair_t (deep copy)
vb@98
    40
//
vb@98
    41
//  parameters:
vb@98
    42
//      src (in)        pointer to stringpair_t to duplicate
vb@98
    43
//
vb@98
    44
//  return value:
vb@98
    45
//      pointer to copy of src or NULL on failure
vb@98
    46
vb@98
    47
DYNAMIC_API stringpair_t * stringpair_dup(const stringpair_t *src);
vb@98
    48
vb@98
    49
vb@98
    50
typedef struct _stringpair_list_t {
vb@98
    51
    stringpair_t *value;
vb@98
    52
    struct _stringpair_list_t *next;
vb@98
    53
} stringpair_list_t;
vb@98
    54
vb@98
    55
vb@98
    56
// new_stringpair_list() - allocate a new stringpair_list
vb@98
    57
//
vb@98
    58
//  parameters:
vb@281
    59
//      value (in)              initial value
vb@98
    60
//
vb@98
    61
//  return value:
vb@98
    62
//      pointer to stringpair_list_t object or NULL if out of memory
vb@98
    63
//
vb@98
    64
//  caveat:
vb@281
    65
//      the ownership of the value goes to the stringpair_list
krista@909
    66
//      next pointer is NULL
vb@98
    67
vb@281
    68
DYNAMIC_API stringpair_list_t *new_stringpair_list(stringpair_t *value);
vb@98
    69
vb@98
    70
krista@832
    71
// stringpair_list_dup() - duplicate a stringpair_list (deep copy)
vb@98
    72
//
vb@98
    73
//  parameters:
vb@98
    74
//      src (in)                stringpair_list to copy
vb@98
    75
//
vb@98
    76
//  return value:
vb@98
    77
//      pointer to stringpair_list_t object or NULL if out of memory
krista@832
    78
//      stringpair value copies created by this function belong to the returned list
vb@98
    79
vb@98
    80
DYNAMIC_API stringpair_list_t *stringpair_list_dup(
vb@98
    81
        const stringpair_list_t *src
vb@98
    82
    );
vb@98
    83
vb@98
    84
vb@98
    85
// stringpair_list_add() - add key to stringpair_list
vb@98
    86
//
vb@98
    87
//  parameters:
vb@98
    88
//      stringpair_list (in)    stringpair_list struct or NULL to create a new
vb@98
    89
//                              one
vb@281
    90
//      value (in)              stringpair to add
vb@98
    91
//
vb@98
    92
//  return value:
vb@98
    93
//      pointer to last element in stringpair_list or NULL if out of memory
vb@98
    94
//
vb@98
    95
//  caveat:
roker@786
    96
//      the ownership of the value goes to the stringpair_list if add is successful
vb@98
    97
vb@98
    98
DYNAMIC_API stringpair_list_t *stringpair_list_add(
vb@98
    99
        stringpair_list_t *stringpair_list,
vb@281
   100
        stringpair_t *value
vb@98
   101
    );
vb@98
   102
vb@98
   103
vb@98
   104
// stringpair_list_append() - append stringpair_list to stringpair_list
vb@98
   105
//
vb@98
   106
//  parameters:
vb@98
   107
//      stringpair_list (in)    stringpair_list struct to append to
vb@98
   108
//      second (in)             stringpair_list struct to append
vb@98
   109
//
vb@98
   110
//  return value:
vb@98
   111
//      pointer to last element in stringpair_list or NULL if out of memory
krista@836
   112
//      or stringpair_list is NULL
vb@98
   113
//
vb@98
   114
//  caveat:
vb@98
   115
//      all values are being copied before being added to the list
vb@98
   116
//      the original values are still being owned by the caller
vb@98
   117
vb@98
   118
DYNAMIC_API stringpair_list_t *stringpair_list_append(
vb@98
   119
        stringpair_list_t *stringpair_list,
vb@98
   120
        stringpair_list_t *second
vb@98
   121
    );
vb@98
   122
vb@98
   123
vb@98
   124
// stringpair_list_length() - get length of stringpair_list
vb@98
   125
//
vb@98
   126
//  parameters:
vb@98
   127
//      stringpair_list (in)    stringpair_list struct to determine length of
vb@98
   128
//
vb@98
   129
//  return value:
vb@98
   130
//      length of stringpair_list in number of elements
vb@98
   131
vb@98
   132
DYNAMIC_API int stringpair_list_length(
vb@98
   133
        const stringpair_list_t *stringpair_list
vb@98
   134
    );
vb@98
   135
vb@98
   136
vb@98
   137
// free_stringpair_list() - free memory occupied by stringpair_list
vb@98
   138
//
vb@98
   139
//  parameters:
vb@98
   140
//      stringpair_list (in)    stringpair_list to free
vb@98
   141
vb@98
   142
DYNAMIC_API void free_stringpair_list(stringpair_list_t *stringpair_list);
vb@98
   143
vb@98
   144
vb@98
   145
// stringpair_list_find() - find element in list using key
vb@98
   146
//
vb@98
   147
//  parameters:
vb@98
   148
//      stringpair_list (in)    list to search
vb@98
   149
//      key (in)                key to search for
vb@98
   150
//
vb@98
   151
//  return value:
vb@104
   152
//      node with result if found or NULL if not
vb@98
   153
vb@104
   154
DYNAMIC_API stringpair_list_t *stringpair_list_find(
vb@98
   155
        stringpair_list_t *stringpair_list,
vb@98
   156
        const char *key
vb@98
   157
    );
vb@98
   158
vb@98
   159
vb@98
   160
#ifdef __cplusplus
vb@98
   161
}
vb@98
   162
#endif
vb@98
   163