Main Page   Alphabetical List   Data Structures   File List   Data Fields   Globals   Examples  

dstring.c

Go to the documentation of this file.
00001 /*! \file dstring.c
00002     This file implements dynamic string manipulation functions.
00003  */
00004 
00005 #include <stdlib.h>
00006 #include <string.h>
00007 #include "dstring.h"
00008 
00009 
00010 #include <stdio.h>
00011 
00012 /*! \brief Initialize a dynamic string.
00013     \param s Pointer to a given dynamic string.
00014     \param init_size Initial size of the dynamic string.
00015     \return Upon successful completion, the function returns 0. Otherwise the function returns 1 (this means
00016             that the process is running out of memory.
00017     \warning You <b>MUST</b> initialize a dynamic string (using dstring_init()), before you can do any
00018              operation on it.
00019  */
00020 
00021 int dstring_init (dstring *s, size_t init_size)
00022 {
00023   s->data   = (char*)malloc(init_size);
00024   if (s->data == NULL) { return 1; }
00025   memset ((void*)s->data, 0, init_size);
00026   s->size   = init_size;
00027   s->nb_car = 0;
00028 
00029   return 0;
00030 }
00031 
00032 /*! \example test_dstring.c
00033     This file shows how to use the entire API for dynamic string manipulation.
00034  */
00035 
00036 /*! \brief Free all memory allocated for a dynamic string.
00037     \param s Pointer to a given dynamic string.
00038  */
00039 
00040 void dstring_free (dstring *s)
00041 {
00042   free (s->data);
00043   s->data   = NULL;
00044   s->size   = 0;
00045   s->nb_car = 0;
00046 }
00047 
00048 /*! \example test_dstring.c
00049     This file shows how to use the entire API for dynamic string manipulation.
00050  */
00051 
00052 /*! \brief Add characters into a given dynamic string.
00053     \param s Pointer to a given dynamic string.
00054     \param buff Pointer to a buffer that contains the characters to add to the dynamic string.
00055     \param nb_elem Number of characters to add.
00056     \return Upon successful completion, the function returns 0. Otherwise the function returns 1 (this means
00057             that the process is running out of memory.
00058     \warning You <b>MUST</b> initialize a dynamic string (using dstring_init()), before you can add data into it.
00059  */
00060 
00061 int dstring_add (dstring *s, char *buff, size_t nb_elem)
00062 {
00063 
00064   /* --------------------------------------------- */
00065   /* We may need to allocate memory                */
00066   /* --------------------------------------------- */
00067 
00068   while ((s->nb_car + nb_elem) > s->size)
00069   {     
00070     s->size = 2 * s->size;
00071     s->data = (char*)realloc((void*)s->data, s->size);
00072     if (s->data == NULL) { return 1; }
00073   }
00074 
00075   memcpy ((void*)(s->data + s->nb_car), (void*)buff, nb_elem);
00076 
00077   s->nb_car = s->nb_car + nb_elem;
00078 
00079   return 0;
00080 }
00081 
00082 /*! \example test_dstring.c
00083     This file shows how to use the entire API for dynamic string manipulation.
00084  */
00085 
00086 /*! \brief Return the content of a dynamic string.
00087     \param s Pointer to a given dynamic string.
00088     \param size pointer to a <i>size_t</i> value that will be used to store the number of bytes extracted
00089            from the dynamic string.
00090     \return Upon successful completion, the function returns a pointer to a dynamically allocated buffer
00091             that contains the dynamic string's data. The value pointed by <i>size</i> represents the number
00092             of bytes allocated for the returned string (including the final 0). If the function could not
00093             allocate memory, then it returns NULL.
00094     \warning The returned pointer points to a memory location that has been allocated within the function.
00095              Therefore you should free it (using free()) when you don't need it anymore.
00096  */
00097 
00098 char* dstring_get_data (dstring *s, size_t *size)
00099 {
00100   char *st;
00101 
00102   *size = s->nb_car + 1;
00103 
00104   st = (char*)malloc(*size);
00105   if (st == NULL) { return NULL; }
00106 
00107   memcpy ((void*)st, (void*)s->data, s->nb_car);
00108 
00109   /* --------------------------------------------- */
00110   /* Add a zero at the end ...                     */
00111   /* --------------------------------------------- */
00112 
00113   *(st + s->nb_car) = 0;
00114 
00115   return st;
00116 }
00117 
00118 /*! \example test_dstring.c
00119     This file shows how to use the entire API for dynamic string manipulation.
00120  */
00121 

Generated on Thu Apr 3 16:23:43 2003 for Common_C_libraries by doxygen1.3-rc1