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