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
char *
find(char **, char *what);
char *
sfind(svect *, char *what);
char *
cfind(char **, char *what);
char *
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@spelio.net.ru>