Changed the signature of osrfStringArrayGetString():
[OpenSRF.git] / include / opensrf / string_array.h
index 77b3de0..57675c3 100644 (file)
@@ -1,41 +1,63 @@
+/**
+       @file string_array.h
+       @brief Header for osrfStringArray, a vector of strings.
+
+       An osrfStringArray manages an array of character pointers pointing to nul-terminated
+       strings.  New entries are added at the end.  When a string is removed, entries above
+       it are shifted down to fill in the gap.
+*/
+
+#ifndef STRING_ARRAY_H
+#define STRING_ARRAY_H
+
 #include <stdio.h>
 
 #include <opensrf/utils.h>
 #include <opensrf/log.h>
+#include <opensrf/osrf_list.h>
 
-#define STRING_ARRAY_MAX_SIZE 1024
+#ifdef __cplusplus
+extern "C" {
+#endif
 
-#ifndef STRING_ARRAY_H
-#define STRING_ARRAY_H
+/**
+       @brief Maximum number of strings in an osrfStringArray.
+
+       This ostensible limit is not enforced.  If you exceed it, you'll get an error message,
+       but only as a slap on the wrist.  You'll still get your big list of strings.
+*/
+#define STRING_ARRAY_MAX_SIZE 4096
 
-struct string_array_struct {
-               char** array;   
-               int size;
-               int arr_size;
-               int total_string_size;
-};
-typedef struct string_array_struct string_array;
-typedef struct string_array_struct osrfStringArray;
+/** @brief Macro version of osrfStringArrayFree() */
+#define OSRF_STRING_ARRAY_FREE(arr) osrfListFree( (osrfList*) (arr) )
 
-osrfStringArray* init_string_array(int size);
-osrfStringArray* osrfNewStringArray(int size);
+/**
+       @brief Structure of an osrfStringArray.
+*/
+typedef struct {
+       /** @brief The underlying container of pointers. */
+    osrfList list;
+       /** @brief The number of strings stored. */
+       int size;    // redundant with list.size
+} osrfStringArray;
 
-void string_array_add(osrfStringArray*, char* string);
-void osrfStringArrayAdd(osrfStringArray*, char* string);
+osrfStringArray* osrfNewStringArray( int size );
 
-char* string_array_get_string(osrfStringArray* arr, int index);
-char* osrfStringArrayGetString(osrfStringArray* arr, int index);
+void osrfStringArrayAdd( osrfStringArray*, const char* str );
 
-/* returns true if this array contains the given string */
-int osrfStringArrayContains( osrfStringArray* arr, char* string );
+const char* osrfStringArrayGetString( const osrfStringArray* arr, int index );
 
+int osrfStringArrayContains(
+       const osrfStringArray* arr, const char* string );
 
-void string_array_destroy(osrfStringArray*);
-void osrfStringArrayFree(osrfStringArray*);
+void osrfStringArrayFree( osrfStringArray* );
 
-/* total size of all included strings */
-int string_array_get_total_size(osrfStringArray* arr);
+void osrfStringArrayRemove( osrfStringArray* arr, const char* str );
 
-void osrfStringArrayRemove( osrfStringArray* arr, char* str);
+osrfStringArray* osrfStringArrayTokenize( const char* src, char delim );
+
+#ifdef __cplusplus
+}
+#endif
 
 #endif