Browse code

- added macro STR_EQ - doxygen documentation added

Jan Janak authored on 29/01/2008 08:14:27
Showing 1 changed files
... ...
@@ -25,22 +25,98 @@
25 25
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
26 26
  */
27 27
 
28
-
29 28
 #ifndef str_h
30 29
 #define str_h
31 30
 
31
+/** @defgroup str_string Counted-Length Strings 
32
+ * @{
33
+ * 
34
+ * Implementation of counted-length strings. In SER and its modules, strings
35
+ * are often stored in the ::str structure. In addition to the pointer
36
+ * pointing to the first character of the string, the structure also contains
37
+ * the length of the string.
38
+ * 
39
+ * @section motivation Motivation
40
+ * Storing the length of the string together with the pointer to the string
41
+ * has two advantages. First, it makes many string operations faster because
42
+ * it is not necessary to count the number of characters at runtime. Second,
43
+ * the pointer can point to arbitrary substrings within a SIP message (which
44
+ * itself is stored as one long string spanning the whole message) without the
45
+ * need to make a zero-terminated copy of it. 
46
+ *
47
+ * @section drawbacks Drawbacks 
48
+ * Note well that the fact that string stored
49
+ * using this data structure are not zero terminated makes them a little
50
+ * incovenient to use with many standard libc string functions, because these
51
+ * usually expect the input to be zero-terminated. In this case you have to
52
+ * either make a zero-terminated copy or inject the terminating zero behind
53
+ * the actuall string (if possible). Note that injecting a zero terminating
54
+ * characters is considered to be dangerous.
55
+ */
56
+
57
+/** @file 
58
+ * This header field defines the ::str data structure that is used across
59
+ * SER sources to store counted-length strings. The file also defines several
60
+ * convenience macros.
61
+ */
32 62
 
63
+/** Data structure used across SER sources to store counted-length strings.
64
+ * This is the data structure that is used to store counted-length
65
+ * strings in SER core and modules.
66
+ */
33 67
 struct _str{
34
-	char* s; /*string*/
35
-	int len; /*string len*/
68
+	char* s; /**< Pointer to the first character of the string */
69
+	int len; /**< Length of the string */
36 70
 };
37 71
 
72
+
73
+/** Data structure used across SER soruces to store counted-length strings.
74
+ * @see _str
75
+ */
38 76
 typedef struct _str str;
39 77
 
78
+/** Initializes static ::str string with string literal.
79
+ * This is a convenience macro that can be used to initialize
80
+ * static ::str strings with string literals like this:
81
+ * \code static str var = STR_STATIC_INIT("some_string"); \endcode
82
+ * @param v is a string literal
83
+ * @sa STR_NULL
84
+ */
40 85
 #define STR_STATIC_INIT(v) {(v), sizeof(v) - 1}
86
+
87
+/** Initializes ::str string with NULL pointer and zero length.
88
+ * This is a convenience macro that can be used to initialize
89
+ * ::str string variable to NULL string with zero length:
90
+ * \code str var = STR_NULL; \endcode
91
+ * @sa STR_STATIC_INIT
92
+ */
41 93
 #define STR_NULL {NULL, 0}
42 94
 
95
+/** Formats ::str string for use in printf-like functions.
96
+ * This is a macro that prepares a ::str string for use in functions which 
97
+ * use printf-like formatting strings. This macro is necessary  because 
98
+ * ::str strings do not have to be zero-terminated and thus it is necessary 
99
+ * to provide printf-like functions with the number of characters in the 
100
+ * string manually. Here is an example how to use the macro: 
101
+ * \code printf("%.*s\n", STR_FMT(var));\endcode Note well that the correct 
102
+ * sequence in the formatting string is %.*, see the man page of printf for 
103
+ * more details.
104
+ */
43 105
 #define STR_FMT(_pstr_)	\
44 106
   ((_pstr_) ? (_pstr_)->len : 0), ((_pstr_) ? (_pstr_)->s : "")
45 107
 
108
+
109
+/** Compares two ::str strings.
110
+ * This macro implements comparison of two strings represented using ::str 
111
+ * structures. First it compares the lengths of both string and if and only 
112
+ * if they are same then both strings are compared using memcmp.
113
+ * @param x is first string to be compared
114
+ * @param y is second string to be compared
115
+ * @return 1 if strings are same, 0 otherwise
116
+ */
117
+#define STR_EQ(x,y) (((x).len == (y).len) && \
118
+					 (memcmp((x).s, (y).s, (x).len) == 0))
119
+
120
+/** @} */
121
+
46 122
 #endif