- added macro STR_EQ

- doxygen documentation added

str.h

@@ -25,22 +25,98 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
-
 #ifndef str_h
 #define str_h
 
+/** @defgroup str_string Counted-Length Strings 
+ * @{
+ * 
+ * Implementation of counted-length strings. 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.
+ * 
+ * @section motivation 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. 
+ *
+ * @section drawbacks 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.
+ */
+
+/** @file 
+ * This header field defines the ::str data structure that is used across
+ * SER sources to store counted-length strings. The file also defines several
+ * convenience macros.
+ */
 
+/** Data structure used across SER sources to store counted-length strings.
+ * This is the data structure that is used to store counted-length
+ * strings in SER core and modules.
+ */
 struct _str{
-	char* s; /*string*/
-	int len; /*string len*/
+	char* s; /**< Pointer to the first character of the string */
+	int len; /**< Length of the string */
 };
 
+
+/** Data structure used across SER soruces to store counted-length strings.
+ * @see _str
+ */
 typedef struct _str str;
 
+/** Initializes static ::str string with string literal.
+ * This is a convenience macro that can be used to initialize
+ * static ::str strings with string literals like this:
+ * \code static str var = STR_STATIC_INIT("some_string"); \endcode
+ * @param v is a string literal
+ * @sa STR_NULL
+ */
 #define STR_STATIC_INIT(v) {(v), sizeof(v) - 1}
+
+/** Initializes ::str string with NULL pointer and zero length.
+ * This is a convenience macro that can be used to initialize
+ * ::str string variable to NULL string with zero length:
+ * \code str var = STR_NULL; \endcode
+ * @sa STR_STATIC_INIT
+ */
 #define STR_NULL {NULL, 0}
 
+/** Formats ::str string for use in printf-like functions.
+ * 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: 
+ * \code printf("%.*s\n", STR_FMT(var));\endcode Note well that the correct 
+ * sequence in the formatting string is %.*, see the man page of printf for 
+ * more details.
+ */
 #define STR_FMT(_pstr_)	\
   ((_pstr_) ? (_pstr_)->len : 0), ((_pstr_) ? (_pstr_)->s : "")
 
+
+/** Compares two ::str strings.
+ * 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.
+ * @param x is first string to be compared
+ * @param y is second string to be compared
+ * @return 1 if strings are same, 0 otherwise
+ */
+#define STR_EQ(x,y) (((x).len == (y).len) && \
+					 (memcmp((x).s, (y).s, (x).len) == 0))
+
+/** @} */
+
 #endif