00001 /* /////////////////////////////////////////////////////////////////////////////
00002  * File:    cstring/cstring.h
00003  *
00004  * Purpose: Definition of the cstring API.
00005  *
00006  * Created: 16th June 1994
00007  * Updated: 26th January 2007
00008  *
00009  * Home:    http://synesis.com.au/software/
00010  *
00011  * Copyright (c) 1994-2007, Matthew Wilson and Synesis Software
00012  * All rights reserved.
00013  *
00014  * Redistribution and use in source and binary forms, with or without 
00015  * modification, are permitted provided that the following conditions are met:
00016  *
00017  * - Redistributions of source code must retain the above copyright notice, this
00018  *   list of conditions and the following disclaimer. 
00019  * - Redistributions in binary form must reproduce the above copyright notice,
00020  *   this list of conditions and the following disclaimer in the documentation
00021  *   and/or other materials provided with the distribution.
00022  * - Neither the names of Matthew Wilson and Synesis Software nor the names of
00023  *   any contributors may be used to endorse or promote products derived from
00024  *   this software without specific prior written permission.
00025  *
00026  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00027  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00028  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00029  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
00030  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00031  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00032  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00033  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00034  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00035  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00036  * POSSIBILITY OF SUCH DAMAGE.
00037  *
00038  * ////////////////////////////////////////////////////////////////////////// */
00039 
00040 
00044 #ifndef CSTRING_INCL_CSTRING_H_CSTRING
00045 #define CSTRING_INCL_CSTRING_H_CSTRING
00046 
00047 /* /////////////////////////////////////////////////////////////////////////////
00048  * Version
00049  */
00050 
00051 #ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
00052 # define CSTRING_VER_CSTRING_H_CSTRING_MAJOR    3
00053 # define CSTRING_VER_CSTRING_H_CSTRING_MINOR    4
00054 # define CSTRING_VER_CSTRING_H_CSTRING_REVISION 3
00055 # define CSTRING_VER_CSTRING_H_CSTRING_EDIT     52
00056 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
00057 
00074 #define CSTRING_VER_MAJOR       3
00075 #define CSTRING_VER_MINOR       4
00076 #define CSTRING_VER_REVISION    3
00077 
00078 #ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
00079 # define CSTRING_VER_1_0_1       0x01000100
00080 # define CSTRING_VER_1_0_2       0x01000200
00081 # define CSTRING_VER_2_0_1       0x02000100
00082 # define CSTRING_VER_2_1_1       0x02010100
00083 # define CSTRING_VER_2_2_1       0x02020100
00084 # define CSTRING_VER_3_0_1       0x03000100
00085 # define CSTRING_VER_3_1_1       0x03010100
00086 # define CSTRING_VER_3_1_2       0x03010200
00087 # define CSTRING_VER_3_1_3       0x03010300
00088 # define CSTRING_VER_3_2_1       0x03020100
00089 # define CSTRING_VER_3_3_1       0x03030100
00090 # define CSTRING_VER_3_3_2       0x03030200
00091 # define CSTRING_VER_3_4_1       0x03040100
00092 # define CSTRING_VER_3_4_2       0x03040200
00093 # define CSTRING_VER_3_4_3       0x03040300
00094 
00095 # define CSTRING_VER             CSTRING_VER_3_4_3
00096 #else /* ? CSTRING_DOCUMENTATION_SKIP_SECTION */
00097 # define CSTRING_VER             0x03040300
00098 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
00099 
00100 /* /////////////////////////////////////////////////////////////////////////////
00101  * Includes
00102  */
00103 
00104 #include <stddef.h>
00105 
00106 /* /////////////////////////////////////////////////////////////////////////////
00107  * Documentation
00108  */
00109 
00117 /* /////////////////////////////////////////////////////////////////////////////
00118  * Storage class
00119  */
00120 
00121 #ifdef __cplusplus
00122 # define CSTRING_EXTERN_C       extern "C"
00123 #else /* ? __cplusplus */
00124 # define CSTRING_EXTERN_C       extern
00125 #endif /* ? __cplusplus */
00126 
00127 /* /////////////////////////////////////////////////////////////////////////////
00128  * Constants & definitions
00129  */
00130 
00134 enum CSTRING_RC
00135 {
00136         CSTRING_RC_SUCCESS               =   0  
00137     ,   CSTRING_RC_OUTOFMEMORY                  
00138     ,   CSTRING_RC_FIXED                        
00139     ,   CSTRING_RC_BORROWED                     
00140     ,   CSTRING_RC_READONLY                     
00141     ,   CSTRING_RC_INVALIDARENA                 
00142     ,   CSTRING_RC_CUSTOMARENANOTSUPPORTED      
00143     ,   CSTRING_RC_EXCEEDFIXEDCAPACITY          
00144     ,   CSTRING_RC_EXCEEDBORROWEDCAPACITY       
00145     ,   CSTRING_RC_CANNOTYIELDFROMSO            
00146 };
00147 #ifndef OPENRJ_DOCUMENTATION_SKIP_SECTION
00148 typedef enum CSTRING_RC     CSTRING_RC;
00149 #endif /* !OPENRJ_DOCUMENTATION_SKIP_SECTION */
00150 
00151 /* /////////////////////////////////////////////////////////////////////////////
00152  * Typedefs
00153  */
00154 
00158 typedef size_t              cstring_flags_t;
00159 
00167 struct cstring_t
00168 {
00169     size_t          len;        
00170     char            *ptr;       
00171     size_t          capacity;   
00172     cstring_flags_t flags;      
00173 };
00174 #ifndef OPENRJ_DOCUMENTATION_SKIP_SECTION
00175 typedef struct cstring_t    cstring_t;
00176 #endif /* !OPENRJ_DOCUMENTATION_SKIP_SECTION */
00177 
00182 #define cstring_t_DEFAULT  { 0, NULL, 0, 0 }
00183 
00184 /* /////////////////////////////////////////////////////////////////////////////
00185  * Custom settings
00186  */
00187 
00196 #define CSTRING_F_TYPE_MASK                         (0x003f)
00197 #define CSTRING_F_MEMORY_IS_INTERNAL_HEAP           (0x0000)    
00198 #define CSTRING_F_MEMORY_IS_BORROWED                (0x0001)    
00199 #define CSTRING_F_MEMORY_IS_FIXED                   (0x0002)    
00200 #define CSTRING_F_MEMORY_IS_READONLY                (0x0004)    
00201 #define CSTRING_F_MEMORY_IS_CONST                   CSTRING_F_MEMORY_IS_READONLY 
00203 #define CSTRING_F_MEMORY_IS_OFFSET                  (0x0040)    
00205 #define CSTRING_F_ARENA_MASK                        (0xff00)
00206 #define CSTRING_F_USE_REALLOC                       (0x0000)    
00207 #if defined(WIN32)
00208 # define CSTRING_F_USE_WIN32_GLOBAL_MEMORY          (0x0100)    
00209 # define CSTRING_F_USE_WIN32_PROCESSHEAP_MEMORY     (0x0200)    
00210 # define CSTRING_F_USE_WIN32_COM_TASK_MEMORY        (0x0400)    
00211 #endif /* WIN32 */
00212 #if defined(CSTRING_USE_SYNESIS_APIS)
00213 # define CSTRING_F_USE_SYNESIS_HATOR                (0x1000)
00214 #endif /* CSTRING_USE_SYNESIS_APIS */
00215 #define CSTRING_F_USE_CUSTOMARENAFUNCTIONS          (0x2000)    
00217 #define CSTRING_F_CUSTOMARENA_CC_CDECL              (0x0000)    
00218 #define CSTRING_F_CUSTOMARENA_CC_STDCALL            (0x0040)    
00222 /* /////////////////////////////////////////////////////////////////////////////
00223  * API functions
00224  */
00225 
00234 CSTRING_EXTERN_C char const *cstring_error(     CSTRING_RC              rc);
00235 
00236 
00244 CSTRING_EXTERN_C CSTRING_RC cstring_init(       struct cstring_t        *pcs);
00245 
00257 CSTRING_EXTERN_C CSTRING_RC cstring_create(     struct cstring_t        *pcs
00258                                         ,       char const              *s);
00259 
00273 CSTRING_EXTERN_C CSTRING_RC cstring_createLen(  struct cstring_t        *pcs
00274                                         ,       char const              *s
00275                                         ,       size_t                  cch);
00276 
00277 
00298 CSTRING_EXTERN_C CSTRING_RC cstring_createEx(   struct cstring_t        *pcs
00299                                         ,       char const              *s
00300                                         ,       cstring_flags_t         flags
00301                                         ,       void                    *arena
00302                                         ,       size_t                  capacity);
00303 
00326 CSTRING_EXTERN_C CSTRING_RC cstring_createLenEx(struct cstring_t        *pcs
00327                                         ,       char const              *s
00328                                         ,       size_t                  cch
00329                                         ,       cstring_flags_t         flags
00330                                         ,       void                    *arena
00331                                         ,       size_t                  capacity);
00332 
00343 CSTRING_EXTERN_C CSTRING_RC cstring_destroy(    struct cstring_t        *pcs);
00344 
00345 
00364 CSTRING_EXTERN_C CSTRING_RC cstring_yield2(     struct cstring_t        *pcs
00365                                         ,       char                    **pPayload
00366                                         ,       void                    **pRaw);
00367 
00368 #ifdef CSTRING_OBSOLETE
00369 CSTRING_EXTERN_C CSTRING_RC cstring_yield(      struct cstring_t        *pcs
00370                                         ,       char                    **ppBuff);
00371 #endif /* CSTRING_OBSOLETE */
00372 
00389 CSTRING_EXTERN_C CSTRING_RC cstring_setCapacity(struct cstring_t        *pcs
00390                                         ,       size_t                  capacity);
00391 
00392 
00409 CSTRING_EXTERN_C CSTRING_RC cstring_assign(     struct cstring_t        *pcs
00410                                         ,       char const              *s);
00411 
00430 CSTRING_EXTERN_C CSTRING_RC cstring_assignLen(  struct cstring_t        *pcs
00431                                         ,       char const              *s
00432                                         ,       size_t                  cch);
00433 
00446 CSTRING_EXTERN_C CSTRING_RC cstring_copy(       struct cstring_t        *pcs
00447                                         ,       struct cstring_t const  *pcsSrc);
00448 
00461 CSTRING_EXTERN_C CSTRING_RC cstring_append(     struct cstring_t        *pcs
00462                                         ,       char const              *s);
00463 
00482 CSTRING_EXTERN_C CSTRING_RC cstring_appendLen(  struct cstring_t        *pcs
00483                                         ,       char const              *s
00484                                         ,       size_t                  cch);
00485 
00497 CSTRING_EXTERN_C CSTRING_RC cstring_truncate(   struct cstring_t        *pcs
00498                                         ,       size_t                  len);
00499 
00512 CSTRING_EXTERN_C CSTRING_RC cstring_swap(       struct cstring_t        *pcs1
00513                                         ,       struct cstring_t        *pcs2);
00514 
00515 /* ////////////////////////////////////////////////////////////////////////// */
00516 
00517 #ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
00518 typedef int (*cstring_allocFailHandler)(void *pv, size_t cb, cstring_flags_t flags, void *param);
00519 
00520 
00522 CSTRING_EXTERN_C CSTRING_RC cstring_createLenFn(struct cstring_t            *pcs
00523                                         ,       char const                  *s
00524                                         ,       size_t                      cch
00525                                         ,       cstring_flags_t             flags
00526                                         ,       void                        *arena
00527                                         ,       size_t                      capacity
00528                                         ,       cstring_allocFailHandler    pfnAllocFailHandler
00529                                         ,       void                        *param);
00530 
00532 CSTRING_EXTERN_C CSTRING_RC cstring_setCapacityFn(struct cstring_t          *pcs
00533                                         ,       size_t                      capacity
00534                                         ,       cstring_allocFailHandler    pfnAllocFailHandler
00535                                         ,       void                        *param);
00536 
00538 CSTRING_EXTERN_C CSTRING_RC cstring_assignFn(   struct cstring_t            *pcs
00539                                         ,       char const                  *s
00540                                         ,       cstring_allocFailHandler    pfnAllocFailHandler
00541                                         ,       void                        *param);
00543 CSTRING_EXTERN_C CSTRING_RC cstring_assignLenFn(struct cstring_t            *pcs
00544                                         ,       char const                  *s
00545                                         ,       size_t                      cch
00546                                         ,       cstring_allocFailHandler    pfnAllocFailHandler
00547                                         ,       void                        *param);
00548 
00550 CSTRING_EXTERN_C CSTRING_RC cstring_appendFn(   struct cstring_t            *pcs
00551                                         ,       char const                  *s
00552                                         ,       cstring_allocFailHandler    pfnAllocFailHandler
00553                                         ,       void                        *param);
00554 
00556 CSTRING_EXTERN_C CSTRING_RC cstring_appendLenFn(struct cstring_t            *pcs
00557                                         ,       char const                  *s
00558                                         ,       size_t                      cch
00559                                         ,       cstring_allocFailHandler    pfnAllocFailHandler
00560                                         ,       void                        *param);
00561 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
00562 
00563 
00564 /* ////////////////////////////////////////////////////////////////////////// */
00565 
00566 #endif /* CSTRING_INCL_CSTRING_H_CSTRING */
00567 
00568 /* ////////////////////////////////////////////////////////////////////////// */