pkg: fix wrong package name, closes FS#148, reported from Andrew Pogrebennyk
[sip-router] / str.h
1 /*
2  * Copyright (C) 2001-2003 FhG Fokus
3  *
4  * This file is part of ser, a free SIP server.
5  *
6  * ser is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version
10  *
11  * For a license to use the ser software under conditions
12  * other than those described here, or to purchase support for this
13  * software, please contact iptel.org by e-mail at the following addresses:
14  *    info@iptel.org
15  *
16  * ser is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License 
22  * along with this program; if not, write to the Free Software 
23  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
24  */
25
26 #ifndef str_h
27 #define str_h
28
29 /** @defgroup str_string Counted-Length Strings 
30  * @{
31  * 
32  * Implementation of counted-length strings. In SER and its modules, strings
33  * are often stored in the ::str structure. In addition to the pointer
34  * pointing to the first character of the string, the structure also contains
35  * the length of the string.
36  * 
37  * @section motivation Motivation
38  * Storing the length of the string together with the pointer to the string
39  * has two advantages. First, it makes many string operations faster because
40  * it is not necessary to count the number of characters at runtime. Second,
41  * the pointer can point to arbitrary substrings within a SIP message (which
42  * itself is stored as one long string spanning the whole message) without the
43  * need to make a zero-terminated copy of it. 
44  *
45  * @section drawbacks Drawbacks 
46  * Note well that the fact that string stored
47  * using this data structure are not zero terminated makes them a little
48  * incovenient to use with many standard libc string functions, because these
49  * usually expect the input to be zero-terminated. In this case you have to
50  * either make a zero-terminated copy or inject the terminating zero behind
51  * the actuall string (if possible). Note that injecting a zero terminating
52  * characters is considered to be dangerous.
53  */
54
55 /** @file 
56  * This header field defines the ::str data structure that is used across
57  * SER sources to store counted-length strings. The file also defines several
58  * convenience macros.
59  */
60
61 /** Data structure used across SER sources to store counted-length strings.
62  * This is the data structure that is used to store counted-length
63  * strings in SER core and modules.
64  */
65 struct _str{
66         char* s; /**< Pointer to the first character of the string */
67         int len; /**< Length of the string */
68 };
69
70
71 /** Data structure used across SER sources to store counted-length strings.
72  * @see _str
73  */
74 typedef struct _str str;
75
76 /** Initializes static ::str string with string literal.
77  * This is a convenience macro that can be used to initialize
78  * static ::str strings with string literals like this:
79  * \code static str var = STR_STATIC_INIT("some_string"); \endcode
80  * @param v is a string literal
81  * @sa STR_NULL
82  */
83 #define STR_STATIC_INIT(v) {(v), sizeof(v) - 1}
84
85 /* kamailio compatibility macro (same thing as above) */
86 #define str_init(v) STR_STATIC_INIT(v)
87
88 /** Initializes ::str string with NULL pointer and zero length.
89  * This is a convenience macro that can be used to initialize
90  * ::str string variable to NULL string with zero length:
91  * \code str var = STR_NULL; \endcode
92  * @sa STR_STATIC_INIT
93  */
94 #define STR_NULL {0, 0}
95
96 /** Formats ::str string for use in printf-like functions.
97  * This is a macro that prepares a ::str string for use in functions which 
98  * use printf-like formatting strings. This macro is necessary  because 
99  * ::str strings do not have to be zero-terminated and thus it is necessary 
100  * to provide printf-like functions with the number of characters in the 
101  * string manually. Here is an example how to use the macro: 
102  * \code printf("%.*s\n", STR_FMT(var));\endcode Note well that the correct 
103  * sequence in the formatting string is %.*, see the man page of printf for 
104  * more details.
105  */
106 #define STR_FMT(_pstr_) \
107   ((_pstr_ != (str *)0) ? (_pstr_)->len : 0), \
108   ((_pstr_ != (str *)0) ? (_pstr_)->s : "")
109
110
111 /** Compares two ::str strings.
112  * This macro implements comparison of two strings represented using ::str 
113  * structures. First it compares the lengths of both string and if and only 
114  * if they are same then both strings are compared using memcmp.
115  * @param x is first string to be compared
116  * @param y is second string to be compared
117  * @return 1 if strings are same, 0 otherwise
118  */
119 #define STR_EQ(x,y) (((x).len == (y).len) && \
120                                          (memcmp((x).s, (y).s, (x).len) == 0))
121
122 /** @} */
123
124 #endif