sf_svect(3) BSD 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 vec‐
tor 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-termi‐
nated array to the newly allocated memory. Please note the second argu‐
ment 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 ALSOstrfunc(3), sf_split(3), sf_misc(3).
AUTHORS
Lev Walkin <vlm@lionet.info>
BSD October 1, 2000 BSD
