src/stringlist.h
author Krista Bennett <krista@pep-project.org>
Tue, 01 Aug 2017 16:40:24 +0200
branchmessage-2.0
changeset 1979 3d0a778d035a
parent 1694 032e59ccdd93
child 2963 a80bc5f9167e
permissions -rw-r--r--
Changed name to ENGINE-214 for JIRA tracking - please use that branch instead.
     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 _stringlist_t {
    14     char *value;
    15     struct _stringlist_t *next;
    16 } stringlist_t;
    17 
    18 
    19 // new_stringlist() - allocate a new stringlist
    20 //
    21 //  parameters:
    22 //      value (in)        initial value as C string or NULL for empty list
    23 //
    24 //  return value:
    25 //      pointer to stringlist_t object or NULL if out of memory
    26 //
    27 //  caveat:
    28 //      the value is being copied before being added to the list
    29 //      the original string is still being owned by the caller
    30 //      the "next" pointer of the returned object is NULL
    31 
    32 DYNAMIC_API stringlist_t *new_stringlist(const char *value);
    33 
    34 
    35 // stringlist_dup() - duplicate a stringlist
    36 //
    37 //  parameters:
    38 //      src (in)            stringlist to copy
    39 //
    40 //  return value:
    41 //      pointer to stringlist_t object or NULL if out of memory
    42 
    43 DYNAMIC_API stringlist_t *stringlist_dup(const stringlist_t *src);
    44 
    45 
    46 // stringlist_add() - add key to stringlist
    47 //
    48 //  parameters:
    49 //      stringlist (in)     stringlist struct or NULL to create a new one
    50 //      value (in)          value as C string
    51 //
    52 //  return value:
    53 //      pointer to last element in stringlist or NULL if out of memory
    54 //
    55 //  caveat:
    56 //      the value is being copied before being added to the list
    57 //      the original string is still being owned by the caller
    58 
    59 DYNAMIC_API stringlist_t *stringlist_add(
    60         stringlist_t *stringlist,
    61         const char *value
    62     );
    63 
    64 // stringlist_add_unique() - add string to stringlist, if not already there
    65 //
    66 //  parameters:
    67 //      stringlist (in)     stringlist struct or NULL to create a new one
    68 //      value (in)          value as C string
    69 //
    70 //  return value:
    71 //      pointer to last element in stringlist or NULL if out of memory
    72 //
    73 //  caveat:
    74 //      the value is being copied before being added to the list
    75 //      the original string is still being owned by the caller
    76 
    77 DYNAMIC_API stringlist_t *stringlist_add_unique(
    78         stringlist_t *stringlist,
    79         const char *value
    80     );
    81 
    82 
    83 // stringlist_append() - append stringlist to stringlist
    84 //
    85 //  parameters:
    86 //      stringlist (in)     stringlist struct to append to
    87 //      second (in)         stringlist struct to append
    88 //
    89 //  return value:
    90 //      pointer to last element in stringlist or NULL if out of memory
    91 //      or stringpair_list is NULL
    92 //
    93 //  caveat:
    94 //      all values are being copied before being added to the list
    95 //      the original values are still being owned by the caller
    96 
    97 DYNAMIC_API stringlist_t *stringlist_append(
    98         stringlist_t *stringlist,
    99         stringlist_t *second
   100     );
   101 
   102 
   103 // stringlist_length() - get length of stringlist
   104 //
   105 //  parameters:
   106 //      stringlist (in)     stringlist struct to determine length of
   107 //
   108 //  return value:
   109 //      length of stringlist in number of elements
   110 
   111 DYNAMIC_API int stringlist_length(const stringlist_t *stringlist);
   112 
   113 
   114 // stringlist_delete() - delete entry from stringlist
   115 //
   116 //  parameters:
   117 //      stringlist (in)     stringlist struct to delete from
   118 //      value (in)          data to delete
   119 //
   120 //  return value:
   121 //      modified stringlist
   122 
   123 DYNAMIC_API stringlist_t *stringlist_delete(
   124         stringlist_t *stringlist,
   125         const char *value
   126     );
   127 
   128 
   129 // free_stringlist() - free memory occupied by stringlist
   130 //
   131 //  parameters:
   132 //      stringlist (in)    stringlist to free
   133 
   134 DYNAMIC_API void free_stringlist(stringlist_t *stringlist);
   135 
   136 
   137 #ifdef __cplusplus
   138 }
   139 #endif
   140