DragonFly On-Line Manual Pages

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