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