Loading...
Searching...
No Matches
su_strlst.h File Reference
String Lists

String lists. More...

`#include <sofia-sip/su_alloc.h>`
Include dependency graph for su_strlst.h:

Go to the source code of this file.

## Macros

#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.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com

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

## Function Documentation

## su_slprintf()

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.

## su_slvprintf()

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.

## su_strlst_append()

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_create()

su_strlst_t * su_strlst_create | ( | su_home_t * | home | ) |

Create a string list.

Create a string list.

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

## su_strlst_create_with()

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_create_with_dup()

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.

## su_strlst_destroy()

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_dup_append()

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_dup_split()

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.

## su_strlst_get_array()

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.

## su_strlst_item()

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

Get a numbered item from list.

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.

## su_strlst_join()

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.

## su_strlst_len()

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.

## su_strlst_remove()

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

Remove a numbered item from list.

Remove a numbered item from list.

The numbering starts from

1. 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.

## su_strlst_set_item()

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

Set a numbered item to list.

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_split()

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_vcreate_with()

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_vcreate_with_dup()

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 1.12.11devel - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.