stralloc.h

Go to the documentation of this file.
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 */

Generated on Tue Jun 19 20:38:27 2007 for lucid by  doxygen 1.5.2