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>