Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 (ar-
     rays).  To	create a string	vector you must	invoke sinit() first. Then you
     will be able to do	whatever you want using	functions with svect * parame-
     ter. 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 un-
     der 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 ALSO
     strfunc(3), sf_split(3), sf_misc(3).

AUTHORS
     Lev Walkin	<vlm@lionet.info>

BSD				October	1, 2000				   BSD

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=svect&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help