Counted-Length Strings

Implementation of counted-length strings. More...

Data Structures

• struct _str

  Data structure used across SER sources to store counted-length strings. More...
  

Files

• file str.h

  This header field defines the str data structure that is used across SER sources to store counted-length strings.

  
  

Defines

• #define STR_EQ(x, y)

  Compares two str strings.
  

• #define STR_FMT(_pstr_)

  Formats str string for use in printf-like functions.
  

• #define STR_NULL   {0, 0}

  Initializes str string with NULL pointer and zero length.
  

• #define STR_STATIC_INIT(v)   {(v), sizeof(v) - 1}

  Initializes static str string with string literal.
  

Typedefs

• typedef struct _str str

  Data structure used across SER sources to store counted-length strings.
  

---

Detailed Description

In SER and its modules, strings are often stored in the str structure. In addition to the pointer pointing to the first character of the string, the structure also contains the length of the string.

Motivation

Storing the length of the string together with the pointer to the string has two advantages. First, it makes many string operations faster because it is not necessary to count the number of characters at runtime. Second, the pointer can point to arbitrary substrings within a SIP message (which itself is stored as one long string spanning the whole message) without the need to make a zero-terminated copy of it.

Drawbacks

Note well that the fact that string stored using this data structure are not zero terminated makes them a little incovenient to use with many standard libc string functions, because these usually expect the input to be zero-terminated. In this case you have to either make a zero-terminated copy or inject the terminating zero behind the actuall string (if possible). Note that injecting a zero terminating characters is considered to be dangerous.

---

Define Documentation

#define STR_EQ	(		x,
			y
	)

Value:

(((x).len == (y).len) && \
                                         (memcmp((x).s, (y).s, (x).len) == 0))

This macro implements comparison of two strings represented using str structures. First it compares the lengths of both string and if and only if they are same then both strings are compared using memcmp.

Parameters:

	x	is first string to be compared
	y	is second string to be compared

Returns:

1 if strings are same, 0 otherwise

Definition at line 119 of file str.h.

#define STR_FMT

(

_pstr_

)

Value:

((_pstr_ != (str *)0) ? (_pstr_)->len : 0), \
  ((_pstr_ != (str *)0) ? (_pstr_)->s : "")

This is a macro that prepares a str string for use in functions which use printf-like formatting strings. This macro is necessary because str strings do not have to be zero-terminated and thus it is necessary to provide printf-like functions with the number of characters in the string manually. Here is an example how to use the macro:

 printf("%.*s\n", STR_FMT(var));

Note well that the correct sequence in the formatting string is %.*, see the man page of printf for more details.

Definition at line 106 of file str.h.

Referenced by cfg_parser_init(), db_cmd(), get_abs_pathname(), and print_event().

#define STR_NULL   {0, 0}

This is a convenience macro that can be used to initialize str string variable to NULL string with zero length:

 str var = STR_NULL; 

See also:

STR_STATIC_INIT

Definition at line 94 of file str.h.

#define STR_STATIC_INIT

(

v

)

{(v), sizeof(v) - 1}

This is a convenience macro that can be used to initialize static str strings with string literals like this:

 static str var = STR_STATIC_INIT("some_string"); 

Parameters:

v

is a string literal

See also:

STR_NULL

Definition at line 83 of file str.h.

Referenced by xmlrpc_reply().

---

Typedef Documentation

typedef struct _str str

See also:

_str

Definition at line 74 of file str.h.