String lists. More...

#include <sofia-sip/su_alloc.h>

Include dependency graph for su_strlst.h:

Defines
#define	SU_STRLST_H
	Defined when <sofia-sip/su_strlst.h> has been included.
Functions
su_strlst_t *	su_strlst_create (su_home_t *home))
	Create a string list.
void	su_strlst_destroy (su_strlst_t *)
	Destroy a string list.
su_strlst_t *	su_strlst_create_with (su_home_t , char const ,...))
	Create a string list with initial values.
su_strlst_t *	su_strlst_create_with_dup (su_home_t , char const ,...))
	Create a string list with duplicatedd initial values.
su_strlst_t *	su_strlst_vcreate_with (su_home_t , char const , va_list va))
	Create a string list with initial values.
su_strlst_t *	su_strlst_vcreate_with_dup (su_home_t , char const , va_list va))
	Create a string list with duplicates of initial values.
su_strlst_t *	su_strlst_copy (su_home_t home, su_strlst_t const orig)
	Shallow copy a string list.
su_strlst_t *	su_strlst_dup (su_home_t home, su_strlst_t const orig)
	Deep copy a string list.
char *	su_strlst_dup_append (su_strlst_t , char const str)
	Duplicate and append a string to list.
char const *	su_strlst_append (su_strlst_t , char const str)
	Append a string to list.
char const *	su_slprintf (su_strlst_t self, char const fmt,...)
	Append a formatted string to the list.
char const *	su_slvprintf (su_strlst_t self, char const fmt, va_list ap)
	Append a formatted string to the list.
char const *	su_strlst_item (su_strlst_t const *, usize_t i)
	Get a numbered item from list.
char const *	su_strlst_set_item (su_strlst_t self, usize_t i, char const s)
	Set a numbered item to list.
char const *	su_strlst_remove (su_strlst_t *, usize_t i)
	Remove a numbered item from list.
char *	su_strlst_join (su_strlst_t s, su_home_t home, char const *sep))
	Concatenate list of strings to one string.
su_strlst_t *	su_strlst_split (su_home_t , char s, char const *sep))
	Split a string.
su_strlst_t *	su_strlst_dup_split (su_home_t , char const s, char const *sep))
	Duplicate and split a string.
usize_t	su_strlst_len (su_strlst_t const *l)
	Get number of items in list.
char const **	su_strlst_get_array (su_strlst_t *self))
	Get a string array from list.
void	su_strlst_free_array (su_strlst_t self, char const array[])
	Free a string array.

Detailed Description

String lists.

Author:: Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>

Date:: Created: Fri May 3 09:13:22 2002 ppessi

Define Documentation

#define SU_STRLST_H

Defined when <sofia-sip/su_strlst.h> has been included.

Function Documentation

char const* su_slprintf	(	su_strlst_t *	self,
		char const *	fmt,
			...
	)

Append a formatted string to the list.

Format a string according to a fmt like printf(). The resulting string is copied to a memory area freshly allocated from a the memory home of the list and appended to the string list.

Parameters:

	self	pointer to a string list object
	fmt	format string
	...	argument list (must match with the fmt format string)

Returns:: A pointer to a fresh copy of formatting result, or NULL upon an error.

char const* su_slvprintf	(	su_strlst_t *	self,
		char const *	fmt,
		va_list	ap
	)

Append a formatted string to the list.

Format a string according to a fmt like vprintf(). The resulting string is copied to a memory area freshly allocated from a the memory home of the list and appended to the string list.

Parameters:

	self	pointer to a string list object
	fmt	format string
	ap	stdarg argument list (must match with the fmt format string)

Returns:: A pointer to a fresh copy of formatting result, or NULL upon an error.

char const* su_strlst_append	(	su_strlst_t *	self,
		char const *	str
	)

Append a string to list.

The string is not copied, and it must not be modified while string list exists.

Parameters:

	self	pointer to a string list object
	str	string to be appended

Returns:: Pointer to string, if successful, or NULL upon an error.

su_strlst_t* su_strlst_copy	(	su_home_t *	home,
		su_strlst_t const *	orig
	)

Shallow copy a string list.

su_strlst_t* su_strlst_create ( su_home_t * home )

Create a string list.

The list is initially empty. The memory home for the list is cloned from home.

su_strlst_t* su_strlst_create_with	(	su_home_t *	home,
		char const *	value,
			...
	)

Create a string list with initial values.

The list is initialized with strings in argument. The argument list is terminated with NULL. The memory home for the list is cloned from home.

su_strlst_t* su_strlst_create_with_dup	(	su_home_t *	home,
		char const *	value,
			...
	)

Create a string list with duplicatedd initial values.

The list is initialized with copies of strings in argument list. The argument list is terminated with NULL. The memory home for the list is cloned from home.

void su_strlst_destroy ( su_strlst_t * self )

Destroy a string list.

The function su_strlst_destroy() destroys a list of strings and frees all duplicated strings belonging to it.

su_strlst_t* su_strlst_dup	(	su_home_t *	home,
		su_strlst_t const *	orig
	)

Deep copy a string list.

char* su_strlst_dup_append	(	su_strlst_t *	self,
		char const *	str
	)

Duplicate and append a string to list.

Parameters:

	self	pointer to a string list object
	str	string to be duplicated and appended

Returns:: Pointer to duplicated string, if successful, or NULL upon an error.

su_strlst_t* su_strlst_dup_split	(	su_home_t *	home,
		char const *	cstr,
		char const *	sep
	)

Duplicate and split a string.

Duplicates a string and splits the result to substrings. It returns a string list object. The string to be splitted is not modified.

Parameters:

	home	home pointer
	cstr	string to be split
	sep	separator between substrings

Returns:: Pointer to list of strings, if successful, or NULL upon an error.

char const** su_strlst_get_array ( su_strlst_t * self )

Get a string array from list.

The function su_strlst_get_array() returns an array of strings. The length of the array is always one longer than the length of the string list, and the last string in the returned array is always NULL.

Parameters:

self

pointer to a string list object

Returns:: Pointer to array of strings, or NULL if error occurred.

char const* su_strlst_item	(	su_strlst_t const *	self,
		usize_t	i
	)

Get a numbered item from list.

The numbering starts from 0.

Parameters:

	self	pointer to a string list object
	i	string index

Returns:: Pointer to string, if item exists, or NULL if index is out of bounds or list does not exist.

char* su_strlst_join	(	su_strlst_t *	self,
		su_home_t *	home,
		char const *	sep
	)

Concatenate list of strings to one string.

The function su_strlst_join() concatenates the list of strings. Between each string in list it uses sep. The separator is not inserted after the last string in list, but one can always append an empty string to the list.

The string is allocated from the memory home. If home is NULL, the string is allocated using malloc().

Parameters:

	self	pointer to a string list object
	home	home pointer
	sep	separator (may be NULL)

Returns:

The function su_strlst_join() returns a concatenation of the strings in list, or NULL upon an error.

usize_t su_strlst_len ( su_strlst_t const * l )

Get number of items in list.

The function su_strlst_len() returns the number of items in the string list.

char const* su_strlst_remove	(	su_strlst_t *	self,
		usize_t	i
	)

Remove a numbered item from list.

The numbering starts from 0. The caller is responsible of reclaiming memory used by the removed string.

Parameters:

	self	pointer to a string list object
	i	string index

Returns:: Pointer to string, if item exists, or NULL if index is out of bounds or list does not exist.

char const* su_strlst_set_item	(	su_strlst_t *	self,
		usize_t	i,
		char const *	s
	)

Set a numbered item to list.

Note that the item numbering starts from 0.

Parameters:

	self	pointer to a string list object
	i	string index
	s	string to be set as item i

Returns:: Pointer to string, if item exists, or NULL if index is out of bounds or list does not exist.

su_strlst_t* su_strlst_split	(	su_home_t *	home,
		char *	str,
		char const *	sep
	)

Split a string.

Splits a string to substrings. It returns a string list object. The string to be split is not copied but instead modified in place. Use su_strlst_dup_split() if you do not want to modify str.

Parameters:

	home	home pointer
	str	string to be split
	sep	separator between substrings

Returns:: Pointer to list of strings, if successful, or NULL upon an error.

su_strlst_t* su_strlst_vcreate_with	(	su_home_t *	home,
		char const *	value,
		va_list	va
	)

Create a string list with initial values.

The string list is initialized with strings from va_list va. The argument list is terminated with NULL. The memory home for the list is cloned from home.

su_strlst_t* su_strlst_vcreate_with_dup	(	su_home_t *	home,
		char const *	value,
		va_list	va
	)

Create a string list with duplicates of initial values.

The string list is initialized with copies of strings from va_list va. The argument list is terminated with NULL. The memory home for the list is cloned from home.

sofia-sip/su_strlst.h File Reference

Defines

Functions

Detailed Description

Define Documentation

Function Documentation