1.Dd October 1, 2000 2.Dt sf_svect 3 3.Os 4.Sh NAME 5.Nm sinit , 6.Nm sclear , 7.Nm sfree , 8.Nm sadd , 9.Nm sadd2 , 10.Nm sadd_attach , 11.Nm saddp , 12.Nm sdel , 13.Nm sins , 14.Nm sfind , 15.Nm find , 16.Nm scfind , 17.Nm cfind , 18.Nm sget2 , 19.Nm scget2 , 20.Nm sgetp , 21.Nm scgetp , 22.Nm simport , 23.Nm scopy , 24.Nm sarray , 25.Nm mkarray , 26.Nm charize , 27.Nm free_values , 28.Nm count_values , 29.Nm copy_values 30.Nd string vector manipulation functions 31.Sh SYNOPSIS 32.Fd #include <strfunc.h> 33.Pp 34Create, clear and destroy the string vector 35.Ft svect * 36.Fn sinit "void" 37.Ft void 38.Fn sclear "svect *" 39.Ft void 40.Fn sfree "svect *" 41.Pp 42Add values to the end of the vector 43.Ft int 44.Fn sadd "svect *" "char *toadd" 45.Ft int 46.Fn sadd2 "svect *" "void *toadd" "size_t len" 47.Ft int 48.Fn sadd_attach "svect *" "void *toadd" "size_t len" 49.Ft int 50.Fn saddp "svectpait *" "char *key" "char *val" "int flags" 51.Pp 52Delete an element of the vector. Return value is -1 in case of an error, 53or the number of the remaining elements. 54.Ft int 55.Fn sdel "svect *" "size_t num" 56.Pp 57Insert data to the vector before num's element. Return value is -1 in case of an 58error, or the newly added element's index. 59.Ft ssize_t 60.Fn sins "svect *" "char *data" "size_t num" 61.Pp 62Find element within the vector 63.Ft ssize_t 64.Fn find "char **" "char *what" 65.Ft ssize_t 66.Fn sfind "svect *" "char *what" 67.Ft ssize_t 68.Fn cfind "char **" "char *what" 69.Ft ssize_t 70.Fn scfind "svect *" "char *what" 71.Pp 72Get an appropriate element from the vector 73.Em b 74when 75.Em tofind 76is found in vector 77.Em a 78.Ft char * 79.Fn sget2 "svect *a" "const char *tofind" "svect *b" 80.Ft char * 81.Fn scget2 "svect *a" "const char *tofind" "svect *b" 82.Ft char * 83.Fn sgetp "svectpair *" "const char *tofind" 84.Ft char * 85.Fn scgetp "svectpair *" "const char *tofind" 86.Pp 87Import values 88.Ft int 89.Fn simport "svect *" "char **values" 90.Pp 91Copy string vector 92.Ft svect * 93.Fn scopy "svect *src" 94.Pp 95Create the string array 96.Ft char ** 97.Fn sarray "svect *" "size_t startidx" 98.Ft char ** 99.Fn mkarray "svect *" "size_t startidx" 100.Pp 101Self-desriptive 102.Ft char ** 103.Fn charize "const char *value" 104.Ft void 105.Fn free_values "char **values" 106.Ft size_t 107.Fn count_values "char **values" 108.Ft int 109.Fn copy_values "char **from" "char ***to" 110.Sh DESCRIPTION 111These routines give the user a method of manipulating string vectors (arrays). 112To create a string vector you must invoke 113.Fn sinit 114first. Then you will be able to do whatever you want using functions with 115.Em svect * 116parameter. After all the necessary operations, the 117.Em svect * 118structure must be freed with 119.Fn sfree . 120.Pp 121After the vector creation, you might want to add a values to it. It can be 122done using 123.Fn sadd* , 124.Fn splitf , 125.Fn sins , 126or 127.Fn simport 128functions. 129.Pp 130.Fn sadd "svect *" "char *toadd" 131treats 132.Em toadd 133as a character string and makes a copy of it, attaching it to the given 134string vector. 135.Pp 136.Fn sadd2 "svect *" "void *toadd" "size_t len" 137takes additional length argument, and does not treat 138the 139.Em toadd 140specifically, allowing to store binary data in the vector. 141.Pp 142.Fn sadd_attach "svect *" "void *toadd" "size_t len" 143allows you to feed vector with an arbitrary data without copying 144it, thus allowing to eliminate memory allocation overhead. However, 145.Fn sadd_attach 146MAY reallocate it under certain circumstances, so you shouldn't assume the 147.Em toadd 148pointer will still be valid if 149.Fn sadd_attach 150returns without an error. 151.Pp 152.Fn scopy "svect *src" 153used to create a copy of existing 154.Em svect 155structure, or return NULL if 156.Em src 157is a NULL pointer. 158.Pp 159There is two functions to clear the vector, 160.Fn sdel 161and 162.Fn sclear . 163Those functions will do the one-by-one or full clearing, respectively. 164.Pp 165.Fn sarray 166and 167.Fn mkarray 168functions are used to obtain simple 169.Em char ** 170array. The differense is: 171.Fn mkarray 172produces a copy of the vector, so it must be freed by 173.Fn free_values . 174.Fn sarray 175does not require such freeing because it returns a pointer to the internally 176managed structure. 177.Pp 178.Fn charize "char *value" 179produces a simple 180.Em char ** 181array that must be freed after the use. 182.Pp 183.Fn free_values 184and 185.Fn count_values 186are too self descriptive, so I will stop here. 187.Pp 188.Fn copy_values "char **from" "char ***to" 189used to copy the simple NULL-terminated array to the newly allocated memory. 190Please note the second argument is the 191.Em char *** . 192.Sh EXAMPLES 193Here is an example of creating and filling the string vectors. 194.Bd -literal 195void main() { 196 svect *sl; /* Declare a pointer to a string vector */ 197 198 sl = sinit(); /* Create and initialize */ 199 200 /* Add some values using the different approaches */ 201 sadd(sl, "one"); 202 sadd2(sl, "two", 3); 203 sadd_attach(sl, sf_strdup("three"), 5); 204 205 /* Numbers are zero-based, 206 * so it will delete the second element, 207 * "two" 208 */ 209 sdel(sl, 1); 210 211 /* This will produce: 212 * "one, three" 213 */ 214 printf("%s\en", sjoin(sl, ", ")); 215 216 /* Destroy the vector */ 217 sfree(sl); 218}; 219.Ed 220.Pp 221And here is the usage example. 222.Bd -literal 223void test(svect *sl) { 224 int i; 225 226 /* We will show some hidden info. 227 * Refer to strfunc.h for the definition 228 * of the svect * structure 229 */ 230 printf("sl has %d elements\en", sl->count); 231 232 printf("the maximum element length is %d\en", sl->maxlen); 233 234 printf("elements are:\en"); 235 236 for(i=0; i < sl->count; i++) 237 printf("element %d: [%s] with length %d\en", 238 i, sl->list[i], sl->lens[i]); 239 240 printf("join them together: [%s]\en", sjoin(sl, "|")); 241}; 242.Ed 243.Pp 244.Sh SEE ALSO 245.Xr strfunc 3 , 246.Xr sf_split 3 , 247.Xr sf_misc 3 . 248.Sh AUTHORS 249.An Lev Walkin <vlm@lionet.info> 250