str.h
7fa84b41
 /*
53c7e0f1
  * Copyright (C) 2001-2003 FhG Fokus
7dd0b342
  *
  * This file is part of ser, a free SIP server.
  *
  * ser is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
  * For a license to use the ser software under conditions
  * other than those described here, or to purchase support for this
  * software, please contact iptel.org by e-mail at the following addresses:
  *    info@iptel.org
  *
  * ser is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License 
  * along with this program; if not, write to the Free Software 
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
7fa84b41
  */
 
 #ifndef str_h
 #define str_h
 
67fdd78b
 /** @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.
  */
7fa84b41
 
67fdd78b
 /** 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.
  */
7fa84b41
 struct _str{
67fdd78b
 	char* s; /**< Pointer to the first character of the string */
 	int len; /**< Length of the string */
7fa84b41
 };
 
67fdd78b
 
7a437761
 /** Data structure used across SER sources to store counted-length strings.
67fdd78b
  * @see _str
  */
7fa84b41
 typedef struct _str str;
 
67fdd78b
 /** 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
  */
c89df7e5
 #define STR_STATIC_INIT(v) {(v), sizeof(v) - 1}
67fdd78b
 
8eb94bf9
 /* kamailio compatibility macro (same thing as above) */
 #define str_init(v) STR_STATIC_INIT(v)
 
67fdd78b
 /** 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
  */
077552bd
 #define STR_NULL {0, 0}
7fa84b41
 
67fdd78b
 /** 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.
  */
374f5e86
 #define STR_FMT(_pstr_)	\
03d7d3b9
   ((_pstr_ != (str *)0) ? (_pstr_)->len : 0), \
   ((_pstr_ != (str *)0) ? (_pstr_)->s : "")
374f5e86
 
67fdd78b
 
 /** 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))
 
 /** @} */
 
7fa84b41
 #endif