stralloc.h

Go to the documentation of this file.
00001 // Copyright 2005 Felix von Leitner <felix-libowfat@fefe.de>
00002 //           2006 Benedikt Böhm <hollow@gentoo.org>
00003 //
00004 // This program is free software; you can redistribute it and/or modify
00005 // it under the terms of the GNU General Public License as published by
00006 // the Free Software Foundation; either version 2 of the License, or
00007 // (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
00016 // Free Software Foundation, Inc.,
00017 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
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 deallocate all memory
00111  *
00112  * @param[out] sa string to initialize
00113  */
00114 void stralloc_free(stralloc_t *sa);
00115 
00116 
00117 /*!
00118  * @brief copy a static string to a dynamic one
00119  *
00120  * @param[out] dst dynamic destination string
00121  * @param[in]  src static source string
00122  * @param[in]  len copy at most len bytes
00123  *
00124  * @return 0 on success, -1 on error with errno set
00125  */
00126 int stralloc_copyb(stralloc_t *dst, const char *src, size_t len);
00127 
00128 /*!
00129  * @brief copy a static string to a dynamic one
00130  *
00131  * @param[out] dst dynamic destination string
00132  * @param[in]  src static source string
00133  *
00134  * @return 0 on success, -1 on error with errno set
00135  */
00136 int stralloc_copys(stralloc_t *dst, const char *src);
00137 
00138 /*!
00139  * @brief copy one dynamic string to another
00140  *
00141  * @param[out] dst dynamic destination string
00142  * @param[in]  src dynamic source string
00143  *
00144  * @return 0 on success, -1 on error with errno set
00145  */
00146 int stralloc_copy(stralloc_t *dst, const stralloc_t *src);
00147 
00148 
00149 /*!
00150  * @brief concatenate a dynamic string and a static one
00151  *
00152  * @param[out] dst dynamic destination string
00153  * @param[in]  src static source string
00154  * @param[in]  len append at most len bytes
00155  *
00156  * @return 0 on success, -1 on error with errno set
00157  */
00158 int stralloc_catb(stralloc_t *dst, const char *src, size_t len);
00159 
00160 /*!
00161  * @brief concatenate a dynamic string and a static one using formatted conversion
00162  *
00163  * @param[out] dst dynamic destination string
00164  * @param[in]  fmt format string
00165  * @param[in]  ... variable number of arguments
00166  *
00167  * @return 0 on success, -1 on error with errno set
00168  */
00169 int stralloc_catf(stralloc_t *dst, const char *fmt, ...);
00170 
00171 /*!
00172  * @brief concatenate a dynamic string and multiple static ones
00173  *
00174  * @param[out] dst dynamic destination string
00175  * @param[in]  ... variable number of source strings
00176  *
00177  * @return 0 on success, -1 on error with errno set
00178  *
00179  * @note the last argument must be NULL
00180  */
00181 int stralloc_catm(stralloc_t *dst, ...);
00182 
00183 /*!
00184  * @brief concatenate a dynamic string and a static one
00185  *
00186  * @param[out] dst dynamic destination string
00187  * @param[in]  src static source string
00188  *
00189  * @return 0 on success, -1 on error with errno set
00190  */
00191 int stralloc_cats(stralloc_t *dst, const char *src);
00192 
00193 /*!
00194  * @brief concatenate two dynamic strings
00195  *
00196  * @param[out] dst dynamic destination string
00197  * @param[in]  src dynamic source string
00198  *
00199  * @return 0 on success, -1 on error with errno set
00200  */
00201 int stralloc_cat(stralloc_t *dst, const stralloc_t *src);
00202 
00203 
00204 /*!
00205  * @brief compare two dynamic strings
00206  *
00207  * @param[in] a first string
00208  * @param[in] b second string
00209  *
00210  * @return An integer greater than, equal to, or less than 0, if the string
00211  *         pointed to by a is greater than, equal to, or less than the string
00212  *         pointed to by b, respectively.
00213  */
00214 int stralloc_cmp(const stralloc_t *a, const stralloc_t *b);
00215 
00216 #endif
00217 
00218 /*! @} stralloc */

Generated on Sun Dec 3 17:45:53 2006 for lucid by  doxygen 1.5.1