00001 /* /////////////////////////////////////////////////////////////////////////////
00002  * File:    cstring/cstring.h
00003  *
00004  * Purpose: Definition of the cstring API.
00005  *
00006  * Created: 16th June 1994
00007  * Updated: 24th February 2006
00008  *
00009  * Home:    http://synesis.com.au/software/
00010  *
00011  * Copyright (c) 1994-2006, 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 2
00055 # define CSTRING_VER_CSTRING_H_CSTRING_EDIT     51
00056 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
00057 
00074 #define CSTRING_VER_MAJOR       3
00075 #define CSTRING_VER_MINOR       4
00076 #define CSTRING_VER_REVISION    2
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 
00094 # define CSTRING_VER             CSTRING_VER_3_4_2
00095 #else /* ? CSTRING_DOCUMENTATION_SKIP_SECTION */
00096 # define CSTRING_VER             0x03040100
00097 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
00098 
00099 /* /////////////////////////////////////////////////////////////////////////////
00100  * Includes
00101  */
00102 
00103 #include <stddef.h>
00104 
00105 /* /////////////////////////////////////////////////////////////////////////////
00106  * Documentation
00107  */
00108 
00116 /* /////////////////////////////////////////////////////////////////////////////
00117  * Storage class
00118  */
00119 
00120 #ifdef __cplusplus
00121 # define CSTRING_EXTERN_C       extern "C"
00122 #else /* ? __cplusplus */
00123 # define CSTRING_EXTERN_C       extern
00124 #endif /* ? __cplusplus */
00125 
00126 /* /////////////////////////////////////////////////////////////////////////////
00127  * Constants & definitions
00128  */
00129 
00133 enum CSTRING_RC
00134 {
00135         CSTRING_RC_SUCCESS               =   0  
00136     ,   CSTRING_RC_OUTOFMEMORY                  
00137     ,   CSTRING_RC_FIXED                        
00138     ,   CSTRING_RC_BORROWED                     
00139     ,   CSTRING_RC_READONLY                     
00140     ,   CSTRING_RC_INVALIDARENA                 
00141     ,   CSTRING_RC_CUSTOMARENANOTSUPPORTED      
00142     ,   CSTRING_RC_EXCEEDFIXEDCAPACITY          
00143     ,   CSTRING_RC_EXCEEDBORROWEDCAPACITY       
00144     ,   CSTRING_RC_CANNOTYIELDFROMSO            
00145 };
00146 #ifndef OPENRJ_DOCUMENTATION_SKIP_SECTION
00147 typedef enum CSTRING_RC     CSTRING_RC;
00148 #endif /* !OPENRJ_DOCUMENTATION_SKIP_SECTION */
00149 
00150 /* /////////////////////////////////////////////////////////////////////////////
00151  * Typedefs
00152  */
00153 
00157 typedef size_t              cstring_flags_t;
00158 
00166 struct cstring_t
00167 {
00168     size_t          len;        
00169     char            *ptr;       
00170     size_t          capacity;   
00171     cstring_flags_t flags;      
00172 };
00173 #ifndef OPENRJ_DOCUMENTATION_SKIP_SECTION
00174 typedef struct cstring_t    cstring_t;
00175 #endif /* !OPENRJ_DOCUMENTATION_SKIP_SECTION */
00176 
00181 #define cstring_t_DEFAULT  { 0, NULL, 0, 0 }
00182 
00183 /* /////////////////////////////////////////////////////////////////////////////
00184  * Custom settings
00185  */
00186 
00195 #define CSTRING_F_TYPE_MASK                         (0x003f)
00196 #define CSTRING_F_MEMORY_IS_INTERNAL_HEAP           (0x0000)    
00197 #define CSTRING_F_MEMORY_IS_BORROWED                (0x0001)    
00198 #define CSTRING_F_MEMORY_IS_FIXED                   (0x0002)    
00199 #define CSTRING_F_MEMORY_IS_READONLY                (0x0004)    
00200 #define CSTRING_F_MEMORY_IS_CONST                   CSTRING_F_MEMORY_IS_READONLY 
00202 #define CSTRING_F_MEMORY_IS_OFFSET                  (0x0040)    
00204 #define CSTRING_F_ARENA_MASK                        (0xff00)
00205 #define CSTRING_F_USE_REALLOC                       (0x0000)    
00206 #if defined(WIN32)
00207 # define CSTRING_F_USE_WIN32_GLOBAL_MEMORY          (0x0100)    
00208 # define CSTRING_F_USE_WIN32_PROCESSHEAP_MEMORY     (0x0200)    
00209 # define CSTRING_F_USE_WIN32_COM_TASK_MEMORY        (0x0400)    
00210 #endif /* WIN32 */
00211 #if defined(CSTRING_USE_SYNESIS_APIS)
00212 # define CSTRING_F_USE_SYNESIS_HATOR                (0x1000)
00213 #endif /* CSTRING_USE_SYNESIS_APIS */
00214 #define CSTRING_F_USE_CUSTOMARENAFUNCTIONS          (0x2000)    
00216 #define CSTRING_F_CUSTOMARENA_CC_CDECL              (0x0000)    
00217 #define CSTRING_F_CUSTOMARENA_CC_STDCALL            (0x0040)    
00221 /* /////////////////////////////////////////////////////////////////////////////
00222  * API functions
00223  */
00224 
00233 CSTRING_EXTERN_C char const *cstring_error(     CSTRING_RC              rc);
00234 
00235 
00243 CSTRING_EXTERN_C CSTRING_RC cstring_init(       struct cstring_t        *pcs);
00244 
00256 CSTRING_EXTERN_C CSTRING_RC cstring_create(     struct cstring_t        *pcs
00257                                         ,       char const              *s);
00258 
00272 CSTRING_EXTERN_C CSTRING_RC cstring_createLen(  struct cstring_t        *pcs
00273                                         ,       char const              *s
00274                                         ,       size_t                  cch);
00275 
00276 
00297 CSTRING_EXTERN_C CSTRING_RC cstring_createEx(   struct cstring_t        *pcs
00298                                         ,       char const              *s
00299                                         ,       cstring_flags_t         flags
00300                                         ,       void                    *arena
00301                                         ,       size_t                  capacity);
00302 
00325 CSTRING_EXTERN_C CSTRING_RC cstring_createLenEx(struct cstring_t        *pcs
00326                                         ,       char const              *s
00327                                         ,       size_t                  cch
00328                                         ,       cstring_flags_t         flags
00329                                         ,       void                    *arena
00330                                         ,       size_t                  capacity);
00331 
00342 CSTRING_EXTERN_C CSTRING_RC cstring_destroy(    struct cstring_t        *pcs);
00343 
00344 
00363 CSTRING_EXTERN_C CSTRING_RC cstring_yield2(     struct cstring_t        *pcs
00364                                         ,       char                    **pPayload
00365                                         ,       void                    **pRaw);
00366 
00367 #ifdef CSTRING_OBSOLETE
00368 CSTRING_EXTERN_C CSTRING_RC cstring_yield(      struct cstring_t        *pcs
00369                                         ,       char                    **ppBuff);
00370 #endif /* CSTRING_OBSOLETE */
00371 
00388 CSTRING_EXTERN_C CSTRING_RC cstring_setCapacity(struct cstring_t        *pcs
00389                                         ,       size_t                  capacity);
00390 
00391 
00408 CSTRING_EXTERN_C CSTRING_RC cstring_assign(     struct cstring_t        *pcs
00409                                         ,       char const              *s);
00410 
00429 CSTRING_EXTERN_C CSTRING_RC cstring_assignLen(  struct cstring_t        *pcs
00430                                         ,       char const              *s
00431                                         ,       size_t                  cch);
00432 
00445 CSTRING_EXTERN_C CSTRING_RC cstring_copy(       struct cstring_t        *pcs
00446                                         ,       struct cstring_t const  *pcsSrc);
00447 
00460 CSTRING_EXTERN_C CSTRING_RC cstring_append(     struct cstring_t        *pcs
00461                                         ,       char const              *s);
00462 
00481 CSTRING_EXTERN_C CSTRING_RC cstring_appendLen(  struct cstring_t        *pcs
00482                                         ,       char const              *s
00483                                         ,       size_t                  cch);
00484 
00496 CSTRING_EXTERN_C CSTRING_RC cstring_truncate(   struct cstring_t        *pcs
00497                                         ,       size_t                  len);
00498 
00511 CSTRING_EXTERN_C CSTRING_RC cstring_swap(       struct cstring_t        *pcs1
00512                                         ,       struct cstring_t        *pcs2);
00513 
00514 /* ////////////////////////////////////////////////////////////////////////// */
00515 
00516 #ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
00517 typedef int (*cstring_allocFailHandler)(void *pv, size_t cb, cstring_flags_t flags, void *param);
00518 
00519 
00521 CSTRING_EXTERN_C CSTRING_RC cstring_createLenFn(struct cstring_t            *pcs
00522                                         ,       char const                  *s
00523                                         ,       size_t                      cch
00524                                         ,       cstring_flags_t             flags
00525                                         ,       void                        *arena
00526                                         ,       size_t                      capacity
00527                                         ,       cstring_allocFailHandler    pfnAllocFailHandler
00528                                         ,       void                        *param);
00529 
00531 CSTRING_EXTERN_C CSTRING_RC cstring_setCapacityFn(struct cstring_t          *pcs
00532                                         ,       size_t                      capacity
00533                                         ,       cstring_allocFailHandler    pfnAllocFailHandler
00534                                         ,       void                        *param);
00535 
00537 CSTRING_EXTERN_C CSTRING_RC cstring_assignFn(   struct cstring_t            *pcs
00538                                         ,       char const                  *s
00539                                         ,       cstring_allocFailHandler    pfnAllocFailHandler
00540                                         ,       void                        *param);
00542 CSTRING_EXTERN_C CSTRING_RC cstring_assignLenFn(struct cstring_t            *pcs
00543                                         ,       char const                  *s
00544                                         ,       size_t                      cch
00545                                         ,       cstring_allocFailHandler    pfnAllocFailHandler
00546                                         ,       void                        *param);
00547 
00549 CSTRING_EXTERN_C CSTRING_RC cstring_appendFn(   struct cstring_t            *pcs
00550                                         ,       char const                  *s
00551                                         ,       cstring_allocFailHandler    pfnAllocFailHandler
00552                                         ,       void                        *param);
00553 
00555 CSTRING_EXTERN_C CSTRING_RC cstring_appendLenFn(struct cstring_t            *pcs
00556                                         ,       char const                  *s
00557                                         ,       size_t                      cch
00558                                         ,       cstring_allocFailHandler    pfnAllocFailHandler
00559                                         ,       void                        *param);
00560 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
00561 
00562 
00563 /* ////////////////////////////////////////////////////////////////////////// */
00564 
00565 #endif /* CSTRING_INCL_CSTRING_H_CSTRING */
00566 
00567 /* ////////////////////////////////////////////////////////////////////////// */