src/stringpair.h
author Roker <roker@pep-project.org>
Fri, 01 Jul 2016 10:59:53 +0200
changeset 786 cd0c6d03e539
parent 281 9f7691853773
child 832 8a54e3a6b155
permissions -rw-r--r--
clarify which values are okay in stringpair
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
vb@98
    66
vb@281
    67
DYNAMIC_API stringpair_list_t *new_stringpair_list(stringpair_t *value);
vb@98
    68
vb@98
    69
vb@98
    70
// stringpair_list_dup() - duplicate a stringpair_list
vb@98
    71
//
vb@98
    72
//  parameters:
vb@98
    73
//      src (in)                stringpair_list to copy
vb@98
    74
//
vb@98
    75
//  return value:
vb@98
    76
//      pointer to stringpair_list_t object or NULL if out of memory
vb@98
    77
vb@98
    78
DYNAMIC_API stringpair_list_t *stringpair_list_dup(
vb@98
    79
        const stringpair_list_t *src
vb@98
    80
    );
vb@98
    81
vb@98
    82
vb@98
    83
// stringpair_list_add() - add key to stringpair_list
vb@98
    84
//
vb@98
    85
//  parameters:
vb@98
    86
//      stringpair_list (in)    stringpair_list struct or NULL to create a new
vb@98
    87
//                              one
vb@281
    88
//      value (in)              stringpair to add
vb@98
    89
//
vb@98
    90
//  return value:
vb@98
    91
//      pointer to last element in stringpair_list or NULL if out of memory
vb@98
    92
//
vb@98
    93
//  caveat:
roker@786
    94
//      the ownership of the value goes to the stringpair_list if add is successful
vb@98
    95
vb@98
    96
DYNAMIC_API stringpair_list_t *stringpair_list_add(
vb@98
    97
        stringpair_list_t *stringpair_list,
vb@281
    98
        stringpair_t *value
vb@98
    99
    );
vb@98
   100
vb@98
   101
vb@98
   102
// stringpair_list_append() - append stringpair_list to stringpair_list
vb@98
   103
//
vb@98
   104
//  parameters:
vb@98
   105
//      stringpair_list (in)    stringpair_list struct to append to
vb@98
   106
//      second (in)             stringpair_list struct to append
vb@98
   107
//
vb@98
   108
//  return value:
vb@98
   109
//      pointer to last element in stringpair_list or NULL if out of memory
vb@98
   110
//
vb@98
   111
//  caveat:
vb@98
   112
//      all values are being copied before being added to the list
vb@98
   113
//      the original values are still being owned by the caller
vb@98
   114
vb@98
   115
DYNAMIC_API stringpair_list_t *stringpair_list_append(
vb@98
   116
        stringpair_list_t *stringpair_list,
vb@98
   117
        stringpair_list_t *second
vb@98
   118
    );
vb@98
   119
vb@98
   120
vb@98
   121
// stringpair_list_length() - get length of stringpair_list
vb@98
   122
//
vb@98
   123
//  parameters:
vb@98
   124
//      stringpair_list (in)    stringpair_list struct to determine length of
vb@98
   125
//
vb@98
   126
//  return value:
vb@98
   127
//      length of stringpair_list in number of elements
vb@98
   128
vb@98
   129
DYNAMIC_API int stringpair_list_length(
vb@98
   130
        const stringpair_list_t *stringpair_list
vb@98
   131
    );
vb@98
   132
vb@98
   133
vb@98
   134
// free_stringpair_list() - free memory occupied by stringpair_list
vb@98
   135
//
vb@98
   136
//  parameters:
vb@98
   137
//      stringpair_list (in)    stringpair_list to free
vb@98
   138
vb@98
   139
DYNAMIC_API void free_stringpair_list(stringpair_list_t *stringpair_list);
vb@98
   140
vb@98
   141
vb@98
   142
// stringpair_list_find() - find element in list using key
vb@98
   143
//
vb@98
   144
//  parameters:
vb@98
   145
//      stringpair_list (in)    list to search
vb@98
   146
//      key (in)                key to search for
vb@98
   147
//
vb@98
   148
//  return value:
vb@104
   149
//      node with result if found or NULL if not
vb@98
   150
vb@104
   151
DYNAMIC_API stringpair_list_t *stringpair_list_find(
vb@98
   152
        stringpair_list_t *stringpair_list,
vb@98
   153
        const char *key
vb@98
   154
    );
vb@98
   155
vb@98
   156
vb@98
   157
#ifdef __cplusplus
vb@98
   158
}
vb@98
   159
#endif
vb@98
   160