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