Dynamic strings [CDS library - Common Data Structures]

Dynamic strings were introduced to satisfy needs of presence modules when building presence documents. More...

Collaboration diagram for Dynamic strings:

Data Structures

• struct _dstr_buff_t

  Buffer used by dynamic string. More...
  

• struct _dstring_t

  Dynamic string structure. More...
  

• typedef struct _dstr_buff_t dstr_buff_t

  Buffer used by dynamic string.
  

• typedef struct _dstring_t dstring_t

  Dynamic string structure.
  

• int dstr_append_zt (dstring_t *dstr, const char *s)

  Appends zero terminated string to dynamic string.
  

• int dstr_append (dstring_t *dstr, const char *s, int len)

  Appends string with given length to dynamic string.
  

• int dstr_append_str (dstring_t *dstr, const str_t *s)

  Appends string to dynamic string.
  

• int dstr_get_data (dstring_t *dstr, char *dst)

  Returns data stored in dynamic string.
  

• int dstr_get_str (dstring_t *dstr, str_t *dst)

  Returns data stored in dynamic string.
  

• int dstr_get_str_pkg (dstring_t *dstr, str_t *dst)

  Returns data stored in dynamic string.
  

• int dstr_init (dstring_t *dstr, int buff_size)

  Initializes dynamic string.
  

• int dstr_destroy (dstring_t *dstr)

  Destroys dynamic string.
  

• #define dstr_get_data_length(dstr)   (dstr)->len

  Macro returning length of data stored in dynamic string.
  

• #define dstr_error(dstr)   (dstr)->error

  Macro pointing to error in dynamic string.
  

• #define dstr_clear_error(dstr)   (dstr)->error = 0

  Macro for cleaning error flag in dynamic string.
  

---

Detailed Description

Dynamic string uses a list of buffers holding data. Buffers are allocated when needed - when there is not enough space in the last buffer. The whole result can be copied into one destination buffer with dstr_get_data, dstr_get_str or dstr_get_str_pkg function.

Todo:

Function with sprintf syntax which will help with readibility of code using dynamic strings.

---

Define Documentation

#define dstr_clear_error

(

dstr

)

(dstr)->error = 0

Definition at line 143 of file dstring.h.

#define dstr_error

(

dstr

)

(dstr)->error

If set there was an error during a previous operation with this dynamic string.

Definition at line 140 of file dstring.h.

#define dstr_get_data_length

(

dstr

)

(dstr)->len

Definition at line 135 of file dstring.h.

Referenced by dstr_get_str(), and dstr_get_str_pkg().

---

Typedef Documentation

typedef struct _dstr_buff_t dstr_buff_t

Todo:

'len' and 'used' can be replaced by 'unused' member but it doesn't save too much

typedef struct _dstring_t dstring_t

It is used for muliple appends of any strings.

Note:

There was an attempt to add flags for SHM/PKG memory using, ... but it shows that it slows down, thus they were removed and only the "most quick" version is used (rather two functions than one with param)

---

Function Documentation

int dstr_append	(	dstring_t *	dstr,
		const char *	s,
		int	len
	)

Return values:

	0	if successful
	negative	on error

Definition at line 57 of file dstring.c.

References _dstring_t::error, _dstring_t::len, _dstr_buff_t::len, and _dstr_buff_t::used.

Referenced by dstr_append_str(), and dstr_append_zt().

Here is the caller graph for this function:

int dstr_append_str	(	dstring_t *	dstr,
		const str_t *	s
	)

Return values:

	0	if successful
	negative	on error

Definition at line 93 of file dstring.c.

References dstr_append(), and _dstring_t::len.

Here is the call graph for this function:

int dstr_append_zt	(	dstring_t *	dstr,
		const char *	s
	)

Return values:

	0	if successful
	negative	on error

Definition at line 86 of file dstring.c.

References dstr_append().

Here is the call graph for this function:

int dstr_destroy

(

dstring_t *

dstr

)

It frees all allocated buffers.

Definition at line 189 of file dstring.c.

References cds_free_pkg, _dstring_t::first, _dstring_t::last, and _dstr_buff_t::next.

int dstr_get_data	(	dstring_t *	dstr,
		char *	dst
	)

It does NOT allocate space for them - it expects that the buffer is already allocated.

Return values:

	0	if successful
	negative	on error

Definition at line 106 of file dstring.c.

References _dstring_t::error, _dstring_t::first, _dstr_buff_t::next, and _dstr_buff_t::used.

Referenced by dstr_get_str(), and dstr_get_str_pkg().

Here is the caller graph for this function:

int dstr_get_str	(	dstring_t *	dstr,
		str_t *	dst
	)

It allocates space for them with cds_malloc (SER's shared memory).

Return values:

	0	if successful
	negative	on error

Definition at line 122 of file dstring.c.

References cds_malloc, dstr_get_data(), dstr_get_data_length, and _dstring_t::error.

Here is the call graph for this function:

int dstr_get_str_pkg	(	dstring_t *	dstr,
		str_t *	dst
	)

It allocates space for them with cds_malloc_pkg (SER's package memory).

Return values:

	0	if successful
	negative	on error

Definition at line 150 of file dstring.c.

References cds_malloc_pkg, dstr_get_data(), dstr_get_data_length, and _dstring_t::error.

Here is the call graph for this function:

int dstr_init	(	dstring_t *	dstr,
		int	buff_size
	)

Parameters:

	dstr	dynamic string to be initialized
	buff_size	size of buffer used with this dynamic string

Return values:

	0	if successful
	negative	on error

Definition at line 178 of file dstring.c.

References _dstring_t::buff_size, _dstring_t::error, _dstring_t::first, _dstring_t::last, and _dstring_t::len.