00001 // Copyright (C) 2005 Felix von Leitner <felix-libowfat@fefe.de> 00002 // 2006-2007 Benedikt Böhm <hollow@gentoo.org> 00003 // 00004 // This program is free software; you can redistribute it and/or 00005 // modify it under the terms of the GNU General Public License 00006 // as published by the Free Software Foundation; either version 2 00007 // of the License, or (at your option) any later version. 00008 // 00009 // This program is distributed in the hope that it will be useful, 00010 // but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 // GNU General Public License for more details. 00013 // 00014 // You should have received a copy of the GNU General Public License 00015 // along with this program; if not, write to the Free Software 00016 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA 00017 00018 00019 /*! 00020 * @defgroup stralloc Dynamic string allocator 00021 * 00022 * A stralloc variable holds a byte string in dynamically allocated space. 00023 * String contents are unrestricted; in particular, strings may contain \\0. 00024 * String length is limited only by memory and by the size of an unsigned int. 00025 * 00026 * A stralloc structure has three components: sa.s is a pointer to the first 00027 * byte of the string, or 0 if space is not allocated; sa.len is the number of 00028 * bytes in the string, or undefined if space is not allocated; sa.a is the 00029 * number of bytes allocated for the string, or undefined if space is not 00030 * allocated. 00031 * 00032 * Applications are expected to use sa.s and sa.len directly. 00033 * 00034 * The stralloc_ready() function makes sure that sa has enough space allocated 00035 * to hold len bytes. The stralloc_readyplus() function is like stralloc_ready() 00036 * except that, if sa is already allocated, stralloc_readyplus adds the current 00037 * length of sa to len. 00038 * 00039 * The stralloc_copyb() function copies the string pointed to by src into dst, 00040 * allocating space if necessary. The stralloc_copys() function copies a 00041 * \\0-terminated string from src into dst, without the \\0. It is the same as 00042 * stralloc_copyb(&dst,buf,str_len(buf)). stralloc_copy copies the string 00043 * stored in src into dst. It is the same as 00044 * stralloc_copyb(&dst,src.s,src.len); src must already be allocated. 00045 * 00046 * The stralloc_catb() adds the string pointed to by src to the end of the 00047 * string stored in dst, allocating space if necessary. If dst is unallocated, 00048 * stralloc_catb is the same as stralloc_copyb. The stralloc_cats() function is 00049 * analogous to stralloc_copys, and stralloc_cat is analogous to stralloc_copy. 00050 * The stralloc_catf() and stralloc_catm() functions are analogous to 00051 * stralloc_cats() except that they take a formatted conversion or variable 00052 * number of arguments, respectively, and appends these to the string stored in 00053 * dst. 00054 * 00055 * @{ 00056 */ 00057 00058 #ifndef _LUCID_STRALLOC_H 00059 #define _LUCID_STRALLOC_H 00060 00061 #include <sys/types.h> 00062 00063 /*! 00064 * @brief dynamic string allocator tracking data 00065 * 00066 * This struct is used to keep track of the dynamic string state, i.e. its 00067 * contents, its length and its additionaly allocated memory. 00068 */ 00069 typedef struct { 00070 char *s; /*!< pointer to dynamic string */ 00071 size_t len; /*!< current length of s */ 00072 size_t a; /*!< additional free memory in s */ 00073 } stralloc_t; 00074 00075 /*! 00076 * @brief initialize dynamic string allocator 00077 * 00078 * @param[out] sa string to initialize 00079 */ 00080 void stralloc_init(stralloc_t *sa); 00081 00082 /*! 00083 * @brief truncate string length to zero 00084 * 00085 * @param[out] sa string to truncate 00086 */ 00087 void stralloc_zero(stralloc_t *sa); 00088 00089 /*! 00090 * @brief ensure that enough memory has been allocated 00091 * 00092 * @param[in] sa string to check 00093 * @param[in] len minimum length that has to be available 00094 * 00095 * @return 0 on success, -1 on error with errno set 00096 */ 00097 int stralloc_ready(stralloc_t *sa, size_t len); 00098 00099 /*! 00100 * @brief ensure that enough memory has been allocated 00101 * 00102 * @param[in] sa string to check 00103 * @param[in] len additional length that has to be available 00104 * 00105 * @return 0 on success, -1 on error with errno set 00106 */ 00107 int stralloc_readyplus(stralloc_t *sa, size_t len); 00108 00109 /*! 00110 * @brief finalize dynamic string in new buffer 00111 * 00112 * @param[in] sa string to finalize 00113 * 00114 * @return Newly allocated null-terminated string on success, NULL otherwise. 00115 */ 00116 char *stralloc_finalize(stralloc_t *sa); 00117 00118 /*! 00119 * @brief deallocate all memory 00120 * 00121 * @param[out] sa string to initialize 00122 */ 00123 void stralloc_free(stralloc_t *sa); 00124 00125 00126 /*! 00127 * @brief copy a static string to a dynamic one 00128 * 00129 * @param[out] dst dynamic destination string 00130 * @param[in] src static source string 00131 * @param[in] len copy at most len bytes 00132 * 00133 * @return 0 on success, -1 on error with errno set 00134 */ 00135 int stralloc_copyb(stralloc_t *dst, const char *src, size_t len); 00136 00137 /*! 00138 * @brief copy a static string to a dynamic one 00139 * 00140 * @param[out] dst dynamic destination string 00141 * @param[in] src static source string 00142 * 00143 * @return 0 on success, -1 on error with errno set 00144 */ 00145 int stralloc_copys(stralloc_t *dst, const char *src); 00146 00147 /*! 00148 * @brief copy one dynamic string to another 00149 * 00150 * @param[out] dst dynamic destination string 00151 * @param[in] src dynamic source string 00152 * 00153 * @return 0 on success, -1 on error with errno set 00154 */ 00155 int stralloc_copy(stralloc_t *dst, const stralloc_t *src); 00156 00157 00158 /*! 00159 * @brief concatenate a dynamic string and a static one 00160 * 00161 * @param[out] dst dynamic destination string 00162 * @param[in] src static source string 00163 * @param[in] len append at most len bytes 00164 * 00165 * @return 0 on success, -1 on error with errno set 00166 */ 00167 int stralloc_catb(stralloc_t *dst, const char *src, size_t len); 00168 00169 /*! 00170 * @brief concatenate a dynamic string and a static one using formatted conversion 00171 * 00172 * @param[out] dst dynamic destination string 00173 * @param[in] fmt format string 00174 * @param[in] ... variable number of arguments 00175 * 00176 * @return 0 on success, -1 on error with errno set 00177 */ 00178 int stralloc_catf(stralloc_t *dst, const char *fmt, ...); 00179 00180 /*! 00181 * @brief concatenate a dynamic string and multiple static ones 00182 * 00183 * @param[out] dst dynamic destination string 00184 * @param[in] ... variable number of source strings 00185 * 00186 * @return 0 on success, -1 on error with errno set 00187 * 00188 * @note the last argument must be NULL 00189 */ 00190 int stralloc_catm(stralloc_t *dst, ...); 00191 00192 /*! 00193 * @brief concatenate a dynamic string and a static one 00194 * 00195 * @param[out] dst dynamic destination string 00196 * @param[in] src static source string 00197 * 00198 * @return 0 on success, -1 on error with errno set 00199 */ 00200 int stralloc_cats(stralloc_t *dst, const char *src); 00201 00202 /*! 00203 * @brief concatenate two dynamic strings 00204 * 00205 * @param[out] dst dynamic destination string 00206 * @param[in] src dynamic source string 00207 * 00208 * @return 0 on success, -1 on error with errno set 00209 */ 00210 int stralloc_cat(stralloc_t *dst, const stralloc_t *src); 00211 00212 00213 /*! 00214 * @brief compare two dynamic strings 00215 * 00216 * @param[in] a first string 00217 * @param[in] b second string 00218 * 00219 * @return An integer greater than, equal to, or less than 0, if the string 00220 * pointed to by a is greater than, equal to, or less than the string 00221 * pointed to by b, respectively. 00222 */ 00223 int stralloc_cmp(const stralloc_t *a, const stralloc_t *b); 00224 00225 #endif 00226 00227 /*! @} stralloc */