DragonFly On-Line Manual Pages

Search: Section:  


sf_svect(3)           DragonFly Library Functions Manual           sf_svect(3)

NAME

sinit, sclear, sfree, sadd, sadd2, sadd_attach, saddp, sdel, sins, sfind, find, scfind, cfind, sget2, scget2, sgetp, scgetp, simport, scopy, sarray, mkarray, charize, free_values, count_values, copy_values - string vector manipulation functions

SYNOPSIS

#include <strfunc.h> Create, clear and destroy the string vector svect * sinit(void); void sclear(svect *); void sfree(svect *); Add values to the end of the vector int sadd(svect *, char *toadd); int sadd2(svect *, void *toadd, size_t len); int sadd_attach(svect *, void *toadd, size_t len); int saddp(svectpait *, char *key, char *val, int flags); Delete an element of the vector. Return value is -1 in case of an error, or the number of the remaining elements. int sdel(svect *, size_t num); Insert data to the vector before num's element. Return value is -1 in case of an error, or the newly added element's index. ssize_t sins(svect *, char *data, size_t num); Find element within the vector ssize_t find(char **, char *what); ssize_t sfind(svect *, char *what); ssize_t cfind(char **, char *what); ssize_t scfind(svect *, char *what); Get an appropriate element from the vector b when tofind is found in vector a char * sget2(svect *a, const char *tofind, svect *b); char * scget2(svect *a, const char *tofind, svect *b); char * sgetp(svectpair *, const char *tofind); char * scgetp(svectpair *, const char *tofind); Import values int simport(svect *, char **values); Copy string vector svect * scopy(svect *src); Create the string array char ** sarray(svect *, size_t startidx); char ** mkarray(svect *, size_t startidx); Self-desriptive char ** charize(const char *value); void free_values(char **values); size_t count_values(char **values); int copy_values(char **from, char ***to);

DESCRIPTION

These routines give the user a method of manipulating string vectors (arrays). To create a string vector you must invoke sinit() first. Then you will be able to do whatever you want using functions with svect * parameter. After all the necessary operations, the svect * structure must be freed with sfree(). After the vector creation, you might want to add a values to it. It can be done using sadd*(), splitf(), sins(), or simport() functions. sadd(svect *, char *toadd) treats toadd as a character string and makes a copy of it, attaching it to the given string vector. sadd2(svect *, void *toadd, size_t len) takes additional length argument, and does not treat the toadd specifically, allowing to store binary data in the vector. sadd_attach(svect *, void *toadd, size_t len) allows you to feed vector with an arbitrary data without copying it, thus allowing to eliminate memory allocation overhead. However, sadd_attach() MAY reallocate it under certain circumstances, so you shouldn't assume the toadd pointer will still be valid if sadd_attach() returns without an error. scopy(svect *src) used to create a copy of existing svect structure, or return NULL if src is a NULL pointer. There is two functions to clear the vector, sdel() and sclear(). Those functions will do the one-by-one or full clearing, respectively. sarray() and mkarray() functions are used to obtain simple char ** array. The differense is: mkarray() produces a copy of the vector, so it must be freed by free_values(). sarray() does not require such freeing because it returns a pointer to the internally managed structure. charize(char *value) produces a simple char ** array that must be freed after the use. free_values() and count_values() are too self descriptive, so I will stop here. copy_values(char **from, char ***to) used to copy the simple NULL- terminated array to the newly allocated memory. Please note the second argument is the char ***.

EXAMPLES

Here is an example of creating and filling the string vectors. void main() { svect *sl; /* Declare a pointer to a string vector */ sl = sinit(); /* Create and initialize */ /* Add some values using the different approaches */ sadd(sl, "one"); sadd2(sl, "two", 3); sadd_attach(sl, sf_strdup("three"), 5); /* Numbers are zero-based, * so it will delete the second element, * "two" */ sdel(sl, 1); /* This will produce: * "one, three" */ printf("%s\n", sjoin(sl, ", ")); /* Destroy the vector */ sfree(sl); }; And here is the usage example. void test(svect *sl) { int i; /* We will show some hidden info. * Refer to strfunc.h for the definition * of the svect * structure */ printf("sl has %d elements\n", sl->count); printf("the maximum element length is %d\n", sl->maxlen); printf("elements are:\n"); for(i=0; i < sl->count; i++) printf("element %d: [%s] with length %d\n", i, sl->list[i], sl->lens[i]); printf("join them together: [%s]\n", sjoin(sl, "|")); };

SEE ALSO

strfunc(3), sf_split(3), sf_misc(3).

AUTHORS

Lev Walkin <vlm@lionet.info> DragonFly 6.5-DEVELOPMENT October 1, 2000 DragonFly 6.5-DEVELOPMENT

Search: Section: