Synesis Software

Main Page   Modules   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

/cstring/cstring.h

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

cstring Library documentation © Matthew Wilson and Synesis Software Pty Ltd, 1994-2005