Synesis Software

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

/include/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: 29th July 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_INCL_H_CSTRING
00045 #define CSTRING_INCL_CSTRING_H_CSTRING_INCL_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    2
00054 # define CSTRING_VER_CSTRING_H_CSTRING_REVISION 1
00055 # define CSTRING_VER_CSTRING_H_CSTRING_EDIT     44
00056 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
00057 
00074 #define CSTRING_VER_MAJOR       3
00075 #define CSTRING_VER_MINOR       2
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 
00090 # define CSTRING_VER             CSTRING_VER_3_2_1
00091 #else /* ? CSTRING_DOCUMENTATION_SKIP_SECTION */
00092 # define CSTRING_VER             0x03020100
00093 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
00094 
00095 /* 
00096  * Includes
00097  */
00098 
00099 #include <stddef.h>
00100 
00101 /* 
00102  * Storage class
00103  */
00104 
00105 #ifdef __cplusplus
00106 # define CSTRING_EXTERN_C       extern "C"
00107 #else /* ? __cplusplus */
00108 # define CSTRING_EXTERN_C       extern
00109 #endif /* ? __cplusplus */
00110 
00111 /* 
00112  * Constants & definitions
00113  */
00114 
00117 enum CSTRING_RC
00118 {
00119         CSTRING_RC_SUCCESS               =   0  
00120     ,   CSTRING_RC_OUTOFMEMORY                  
00121     ,   CSTRING_RC_FIXED                        
00122     ,   CSTRING_RC_BORROWED                     
00123     ,   CSTRING_RC_READONLY                     
00124     ,   CSTRING_RC_INVALIDARENA                 
00125     ,   CSTRING_RC_CUSTOMARENANOTSUPPORTED      
00126     ,   CSTRING_RC_EXCEEDFIXEDCAPACITY          
00127     ,   CSTRING_RC_EXCEEDBORROWEDCAPACITY       
00128 };
00129 #ifndef OPENRJ_DOCUMENTATION_SKIP_SECTION
00130 typedef enum CSTRING_RC     CSTRING_RC;
00131 #endif /* !OPENRJ_DOCUMENTATION_SKIP_SECTION */
00132 
00133 /* 
00134  * Typedefs
00135  */
00136 
00143 struct cstring_t
00144 {
00145     size_t  len;        
00146     char    *ptr;       
00147     size_t  capacity;   
00148     size_t  flags;      
00149 };
00150 #ifndef OPENRJ_DOCUMENTATION_SKIP_SECTION
00151 typedef struct cstring_t    cstring_t;
00152 #endif /* !OPENRJ_DOCUMENTATION_SKIP_SECTION */
00153 
00157 #define cstring_t_DEFAULT  { 0, NULL, 0, 0 }
00158 
00159 /* 
00160  * Custom settings
00161  */
00162 
00163 #define CSTRING_F_TYPE_MASK                         (0x003f)
00164 #define CSTRING_F_MEMORY_IS_INTERNAL_HEAP           (0x0000)    
00165 #define CSTRING_F_MEMORY_IS_BORROWED                (0x0001)    
00166 #define CSTRING_F_MEMORY_IS_FIXED                   (0x0002)    
00167 #define CSTRING_F_MEMORY_IS_READONLY                (0x0004)    
00168 #define CSTRING_F_MEMORY_IS_CONST                   CSTRING_F_MEMORY_IS_READONLY 
00170 #define CSTRING_F_ARENA_MASK                        (0xff00)
00171 #define CSTRING_F_USE_REALLOC                       (0x0000)    
00172 #if defined(WIN32)
00173 # define CSTRING_F_USE_WIN32_GLOBAL_MEMORY          (0x0100)    
00174 # define CSTRING_F_USE_WIN32_PROCESSHEAP_MEMORY     (0x0200)    
00175 # define CSTRING_F_USE_WIN32_COM_TASK_MEMORY        (0x0400)    
00176 #endif /* WIN32 */
00177 #if defined(CSTRING_USE_SYNESIS_APIS)
00178 # define CSTRING_F_USE_SYNESIS_HATOR                (0x1000)
00179 #endif /* CSTRING_USE_SYNESIS_APIS */
00180 #define CSTRING_F_USE_CUSTOMARENAFUNCTIONS          (0x2000)    
00182 #define CSTRING_F_CUSTOMARENA_CC_CDECL              (0x0000)    
00183 #define CSTRING_F_CUSTOMARENA_CC_STDCALL            (0x0040)    
00185 /* 
00186  * API functions
00187  */
00188 
00196 CSTRING_EXTERN_C char const *cstring_error(     CSTRING_RC              rc);
00197 
00198 
00205 CSTRING_EXTERN_C CSTRING_RC cstring_init(       struct cstring_t        *pcs);
00206 
00217 CSTRING_EXTERN_C CSTRING_RC cstring_create(     struct cstring_t        *pcs
00218                                         ,       char const              *s);
00219 
00232 CSTRING_EXTERN_C CSTRING_RC cstring_createLen(  struct cstring_t        *pcs
00233                                         ,       char const              *s
00234                                         ,       size_t                  cch);
00235 
00236 
00256 CSTRING_EXTERN_C CSTRING_RC cstring_createEx(   struct cstring_t        *pcs
00257                                         ,       char const              *s
00258                                         ,       size_t                  flags
00259                                         ,       void                    *arena
00260                                         ,       size_t                  capacity);
00261 
00283 CSTRING_EXTERN_C CSTRING_RC cstring_createLenEx(struct cstring_t        *pcs
00284                                         ,       char const              *s
00285                                         ,       size_t                  cch
00286                                         ,       size_t                  flags
00287                                         ,       void                    *arena
00288                                         ,       size_t                  capacity);
00289 
00299 CSTRING_EXTERN_C CSTRING_RC cstring_destroy(    struct cstring_t        *pcs);
00300 
00301 
00311 CSTRING_EXTERN_C CSTRING_RC cstring_yield(      struct cstring_t        *pcs
00312                                         ,       char                    **ppBuff);
00313 
00329 CSTRING_EXTERN_C CSTRING_RC cstring_setCapacity(struct cstring_t        *pcs
00330                                         ,       size_t                  capacity);
00331 
00347 CSTRING_EXTERN_C CSTRING_RC cstring_assign(     struct cstring_t        *pcs
00348                                         ,       char const              *s);
00349 
00367 CSTRING_EXTERN_C CSTRING_RC cstring_assignLen(  struct cstring_t        *pcs
00368                                         ,       char const              *s
00369                                         ,       size_t                  cch);
00370 
00382 CSTRING_EXTERN_C CSTRING_RC cstring_copy(       struct cstring_t        *pcs
00383                                         ,       struct cstring_t const  *pcsSrc);
00384 
00396 CSTRING_EXTERN_C CSTRING_RC cstring_append(     struct cstring_t        *pcs
00397                                         ,       char const              *s);
00398 
00416 CSTRING_EXTERN_C CSTRING_RC cstring_appendLen(  struct cstring_t        *pcs
00417                                         ,       char const              *s
00418                                         ,       size_t                  cch);
00419 
00430 CSTRING_EXTERN_C CSTRING_RC cstring_truncate(   struct cstring_t        *pcs
00431                                         ,       size_t                  len);
00432 
00444 CSTRING_EXTERN_C CSTRING_RC cstring_swap(       struct cstring_t        *pcs1
00445                                         ,       struct cstring_t        *pcs2);
00446 
00447 /* 
00448 
00449 #endif /* CSTRING_INCL_CSTRING_H_CSTRING_INCL_H_CSTRING */
00450 
00451 /* 

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