Synesis Software

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: 19th May 2010
00008  *
00009  * Home:    http://synesis.com.au/software/
00010  *
00011  * Copyright (c) 1994-2010, 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    7
00054 # define CSTRING_VER_CSTRING_H_CSTRING_REVISION 2
00055 # define CSTRING_VER_CSTRING_H_CSTRING_EDIT     59
00056 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
00057 
00074 #ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
00075 # define CSTRING_VER_1_0_1      0x01000100
00076 # define CSTRING_VER_1_0_2      0x01000200
00077 # define CSTRING_VER_2_0_1      0x02000100
00078 # define CSTRING_VER_2_1_1      0x02010100
00079 # define CSTRING_VER_2_2_1      0x02020100
00080 # define CSTRING_VER_3_0_1      0x03000100
00081 # define CSTRING_VER_3_1_1      0x03010100
00082 # define CSTRING_VER_3_1_2      0x03010200
00083 # define CSTRING_VER_3_1_3      0x03010300
00084 # define CSTRING_VER_3_2_1      0x03020100
00085 # define CSTRING_VER_3_3_1      0x03030100
00086 # define CSTRING_VER_3_3_2      0x03030200
00087 # define CSTRING_VER_3_4_1      0x03040100
00088 # define CSTRING_VER_3_4_2      0x03040200
00089 # define CSTRING_VER_3_4_3      0x03040300
00090 # define CSTRING_VER_3_4_4      0x03040400
00091 # define CSTRING_VER_3_5_1      0x03050100
00092 # define CSTRING_VER_3_5_2      0x03050200
00093 # define CSTRING_VER_3_5_3      0x03050300
00094 # define CSTRING_VER_3_5_4      0x03050400
00095 
00096 # define CSTRING_VER            CSTRING_VER_3_5_4
00097 #else /* ? CSTRING_DOCUMENTATION_SKIP_SECTION */
00098 # define CSTRING_VER            0x03050400
00099 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
00100 
00101 #define CSTRING_VER_MAJOR       3
00102 #define CSTRING_VER_MINOR       5
00103 #define CSTRING_VER_REVISION    4
00104 
00105 /* /////////////////////////////////////////////////////////////////////////
00106  * Includes
00107  */
00108 
00109 #include <stddef.h>
00110 #include <stdio.h>
00111 
00112 /* /////////////////////////////////////////////////////////////////////////
00113  * Documentation
00114  */
00115 
00123 /* /////////////////////////////////////////////////////////////////////////
00124  * Storage class
00125  */
00126 
00127 #ifdef __cplusplus
00128 # define CSTRING_EXTERN_C       extern "C"
00129 #else /* ? __cplusplus */
00130 # define CSTRING_EXTERN_C       extern
00131 #endif /* ? __cplusplus */
00132 
00133 /* /////////////////////////////////////////////////////////////////////////
00134  * Constants & definitions
00135  */
00136 
00140 enum CSTRING_RC
00141 {
00142         CSTRING_RC_SUCCESS               =   0  
00143     ,   CSTRING_RC_OUTOFMEMORY                  
00144     ,   CSTRING_RC_FIXED                        
00145     ,   CSTRING_RC_BORROWED                     
00146     ,   CSTRING_RC_READONLY                     
00147     ,   CSTRING_RC_INVALIDARENA                 
00148     ,   CSTRING_RC_CUSTOMARENANOTSUPPORTED      
00149     ,   CSTRING_RC_EXCEEDFIXEDCAPACITY          
00150     ,   CSTRING_RC_EXCEEDBORROWEDCAPACITY       
00151     ,   CSTRING_RC_CANNOTYIELDFROMSO            
00152     ,   CSTRING_RC_ARENAOVERLOADED              
00153     /* cstring 3.5+ */
00154     ,   CSTRING_RC_INVALIDSTREAM                
00155     ,   CSTRING_RC_EOF                          
00156     ,   CSTRING_RC_INVALIDSECTION               
00157     ,   CSTRING_RC_IOERROR                      
00158 };
00159 #ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
00160 typedef enum CSTRING_RC     CSTRING_RC;
00161 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
00162 
00163 /* /////////////////////////////////////////////////////////////////////////
00164  * Typedefs
00165  */
00166 
00170 typedef size_t              cstring_flags_t;
00171 
00179 struct cstring_t
00180 {
00181     size_t          len;        
00182     char*           ptr;        
00184     size_t          capacity;   
00185     cstring_flags_t flags;      
00187 };
00188 #ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
00189 typedef struct cstring_t    cstring_t;
00190 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
00191 
00196 #define cstring_t_DEFAULT  { 0, NULL, 0, 0 }
00197 
00198 /* /////////////////////////////////////////////////////////////////////////
00199  * Custom settings
00200  */
00201 
00202 #ifndef CSTRING_NO_USE_SYNESIS_APIS
00203 # if defined(_SYNSOFT_INCL_H_MLMEMORY)
00204 #  define CSTRING_USE_SYNESIS_APIS
00205 # endif /* _SYNSOFT_INCL_H_MLMEMORY */
00206 #endif /* !CSTRING_NO_USE_SYNESIS_APIS */
00207 
00208 /* /////////////////////////////////////////////////////////////////////////
00209  * Macros
00210  */
00211 
00222 #define CSTRING_FROM_END(x)     (-1 - (int)(x))
00223 
00224 /* /////////////////////////////////////////////////////////////////////////
00225  * Flags
00226  */
00227 
00236 #define CSTRING_F_TYPE_MASK                     (0x003f)
00237 #define CSTRING_F_MEMORY_IS_INTERNAL_HEAP       (0x0000)    
00239 #define CSTRING_F_MEMORY_IS_BORROWED            (0x0001)    
00242 #define CSTRING_F_MEMORY_IS_FIXED               (0x0002)    
00244 #define CSTRING_F_MEMORY_IS_READONLY            (0x0004)    
00245 #define CSTRING_F_MEMORY_IS_CONST               CSTRING_F_MEMORY_IS_READONLY 
00247 #define CSTRING_F_MEMORY_IS_OFFSET              (0x0040)    
00250 #define CSTRING_F_ARENA_MASK                    (0xff00)
00251 #define CSTRING_F_USE_REALLOC                   (0x0000)    
00253 #if defined(WIN32) || \
00254     defined(WIN64)
00255 # define CSTRING_F_USE_WINDOWS_GLOBAL_MEMORY    (0x0100)    
00258 # define CSTRING_F_USE_WINDOWS_PROCESSHEAP_MEMORY (0x0200)  
00261 # define CSTRING_F_USE_WINDOWS_COM_TASK_MEMORY  (0x0400)    
00264 #endif /* WIN32 || WIN64 */
00265 #if defined(CSTRING_USE_SYNESIS_APIS)
00266 # define CSTRING_F_USE_SYNESIS_HATOR            (0x1000)    
00268 #endif /* CSTRING_USE_SYNESIS_APIS */
00269 #define CSTRING_F_USE_CUSTOMARENAFUNCTIONS      (0x2000)    
00272 #define CSTRING_F_CUSTOMARENA_CC_CDECL          (0x0000)    
00275 #define CSTRING_F_CUSTOMARENA_CC_STDCALL        (0x0040)    
00281 /* /////////////////////////////////////////////////////////////////////////
00282  * API functions
00283  */
00284 
00293 CSTRING_EXTERN_C char const* cstring_error(
00294     CSTRING_RC  rc
00295 );
00296 
00304 CSTRING_EXTERN_C CSTRING_RC cstring_init(
00305     struct cstring_t*       pcs
00306 );
00307 
00319 CSTRING_EXTERN_C CSTRING_RC cstring_create(
00320     struct cstring_t*   pcs
00321 ,   char const*         s
00322 );
00323 
00337 CSTRING_EXTERN_C CSTRING_RC cstring_createLen(
00338     struct cstring_t*       pcs
00339 ,   char const*             s
00340 ,   size_t                  cch
00341 );
00342 
00356 CSTRING_EXTERN_C CSTRING_RC cstring_createN(
00357     struct cstring_t*       pcs
00358 ,   char                    ch
00359 ,   size_t                  n
00360 );
00361 
00362 
00383 CSTRING_EXTERN_C CSTRING_RC cstring_createEx(
00384     struct cstring_t*       pcs
00385 ,   char const*             s
00386 ,   cstring_flags_t         flags
00387 ,   void*                   arena
00388 ,   size_t                  capacity
00389 );
00390 
00413 CSTRING_EXTERN_C CSTRING_RC cstring_createLenEx(
00414     struct cstring_t*       pcs
00415 ,   char const*             s
00416 ,   size_t                  cch
00417 ,   cstring_flags_t         flags
00418 ,   void*                   arena
00419 ,   size_t                  capacity
00420 );
00421 
00432 CSTRING_EXTERN_C CSTRING_RC cstring_destroy(
00433     struct cstring_t*       pcs
00434 );
00435 
00436 
00455 CSTRING_EXTERN_C CSTRING_RC cstring_yield2(
00456     struct cstring_t*       pcs
00457 ,   char**                  pPayload
00458 ,   void**                  pRaw
00459 );
00460 
00461 #ifdef CSTRING_OBSOLETE
00462 CSTRING_EXTERN_C CSTRING_RC cstring_yield(
00463     struct cstring_t*       pcs
00464 ,   char**                  ppBuff
00465 );
00466 #endif /* CSTRING_OBSOLETE */
00467 
00484 CSTRING_EXTERN_C CSTRING_RC cstring_setCapacity(
00485     struct cstring_t*       pcs
00486 ,   size_t                  capacity
00487 );
00488 
00489 
00506 CSTRING_EXTERN_C CSTRING_RC cstring_assign(
00507     struct cstring_t*       pcs
00508 ,   char const*             s
00509 );
00510 
00529 CSTRING_EXTERN_C CSTRING_RC cstring_assignLen(
00530     struct cstring_t*       pcs
00531 ,   char const*             s
00532 ,   size_t                  cch
00533 );
00534 
00547 CSTRING_EXTERN_C CSTRING_RC cstring_copy(
00548     struct cstring_t*       pcs
00549 ,   struct cstring_t const* pcsSrc
00550 );
00551 
00564 CSTRING_EXTERN_C CSTRING_RC cstring_append(
00565     struct cstring_t*       pcs
00566 ,   char const*             s
00567 );
00568 
00587 CSTRING_EXTERN_C CSTRING_RC cstring_appendLen(
00588     struct cstring_t*       pcs
00589 ,   char const*             s
00590 ,   size_t                  cch
00591 );
00592 
00604 CSTRING_EXTERN_C CSTRING_RC cstring_truncate(
00605     struct cstring_t*       pcs
00606 ,   size_t                  len
00607 );
00608 
00621 CSTRING_EXTERN_C CSTRING_RC cstring_swap(
00622     struct cstring_t*       pcs1
00623 ,   struct cstring_t*       pcs2
00624 );
00625 
00626 
00644 CSTRING_EXTERN_C CSTRING_RC cstring_readline(
00645     FILE*               stm
00646 ,   struct cstring_t*   pcs
00647 ,   size_t*             numRead /* = NULL */
00648 );
00649 
00666 CSTRING_EXTERN_C CSTRING_RC cstring_writeline(
00667     FILE*                   stm
00668 ,   struct cstring_t const* pcs
00669 ,   size_t*                 numWritten /* = NULL */
00670 );
00671 
00672 
00678 CSTRING_EXTERN_C CSTRING_RC cstring_insert(
00679     struct cstring_t*       pcs
00680 ,   int                     index
00681 ,   char const*             s
00682 );
00683 
00689 CSTRING_EXTERN_C CSTRING_RC cstring_insertLen(
00690     struct cstring_t*       pcs
00691 ,   int                     index
00692 ,   char const*             s
00693 ,   size_t                  cch
00694 );
00695 
00710 CSTRING_EXTERN_C CSTRING_RC cstring_replace(
00711     struct cstring_t*       pcs
00712 ,   int                     index
00713 ,   size_t                  len
00714 ,   char const*             s
00715 );
00716 
00732 CSTRING_EXTERN_C CSTRING_RC cstring_replaceLen(
00733     struct cstring_t*       pcs
00734 ,   int                     index
00735 ,   size_t                  len
00736 ,   char const*             s
00737 ,   size_t                  cch
00738 );
00739 
00753 CSTRING_EXTERN_C CSTRING_RC cstring_replaceAll(
00754     struct cstring_t*       pcs
00755 ,   char const*             f
00756 ,   char const*             t
00757 ,   size_t*                 numReplaced /* = NULL */
00758 );
00759 
00760 /* ////////////////////////////////////////////////////////////////////// */
00761 
00762 #ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
00763 typedef int (*cstring_allocFailHandler)(void* pv, size_t cb, cstring_flags_t flags, void* param);
00764 
00765 
00767 CSTRING_EXTERN_C CSTRING_RC cstring_createLenFn(
00768     struct cstring_t*           pcs
00769 ,   char const*                 s
00770 ,   size_t                      cch
00771 ,   cstring_flags_t             flags
00772 ,   void*                       arena
00773 ,   size_t                      capacity
00774 ,   cstring_allocFailHandler    pfnAllocFailHandler
00775 ,   void*                       param
00776 );
00777 
00779 CSTRING_EXTERN_C CSTRING_RC cstring_setCapacityFn(
00780     struct cstring_t*           pcs
00781 ,   size_t                      capacity
00782 ,   cstring_allocFailHandler    pfnAllocFailHandler
00783 ,   void*                       param
00784 );
00785 
00787 CSTRING_EXTERN_C CSTRING_RC cstring_assignFn(
00788     struct cstring_t*           pcs
00789 ,   char const*                 s
00790 ,   cstring_allocFailHandler    pfnAllocFailHandler
00791 ,   void*                       param
00792 );
00794 CSTRING_EXTERN_C CSTRING_RC cstring_assignLenFn(
00795     struct cstring_t*           pcs
00796 ,   char const*                 s
00797 ,   size_t                      cch
00798 ,   cstring_allocFailHandler    pfnAllocFailHandler
00799 ,   void*                       param
00800 );
00801 
00803 CSTRING_EXTERN_C CSTRING_RC cstring_appendFn(
00804     struct cstring_t*           pcs
00805 ,   char const*                 s
00806 ,   cstring_allocFailHandler    pfnAllocFailHandler
00807 ,   void*                       param
00808 );
00809 
00811 CSTRING_EXTERN_C CSTRING_RC cstring_appendLenFn(
00812     struct cstring_t*           pcs
00813 ,   char const*                 s
00814 ,   size_t                      cch
00815 ,   cstring_allocFailHandler    pfnAllocFailHandler
00816 ,   void*                       param
00817 );
00818 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
00819 
00820 /* /////////////////////////////////////////////////////////////////////////
00821  * Compiler warnings
00822  */
00823 
00824 #if defined(_MSC_VER)
00825 # if _MSC_VER >= 1200
00826 #  pragma warning(push)
00827 # endif /* compiler */
00828 # pragma warning(disable : 4514) /* unreferenced inline function has been removed */
00829 #endif /* compiler */
00830 
00831 /* /////////////////////////////////////////////////////////////////////////
00832  * String Access Shims
00833  */
00834 
00835 #ifdef __cplusplus
00836 
00837 inline char const* c_str_data_a(struct cstring_t const* pcs)
00838 {
00839     return (NULL == pcs || 0u == pcs->len) ? "" : pcs->ptr;
00840 }
00841 inline char const* c_str_data(struct cstring_t const* pcs)
00842 {
00843     return c_str_data_a(pcs);
00844 }
00845 inline size_t c_str_len_a(struct cstring_t const* pcs)
00846 {
00847     return (NULL == pcs) ? 0u : pcs->len;
00848 }
00849 inline size_t c_str_len(struct cstring_t const* pcs)
00850 {
00851     return c_str_len_a(pcs);
00852 }
00853 inline char const* c_str_ptr_a(struct cstring_t const* pcs)
00854 {
00855     return c_str_data_a(pcs);
00856 }
00857 inline char const* c_str_ptr(struct cstring_t const* pcs)
00858 {
00859     return c_str_data_a(pcs);
00860 }
00861 
00862 inline char const* c_str_data_a(struct cstring_t const& cs)
00863 {
00864     return (0u == cs.len) ? "" : cs.ptr;
00865 }
00866 inline char const* c_str_data(struct cstring_t const& cs)
00867 {
00868     return c_str_data_a(cs);
00869 }
00870 inline size_t c_str_len_a(struct cstring_t const& cs)
00871 {
00872     return cs.len;
00873 }
00874 inline size_t c_str_len(struct cstring_t const& cs)
00875 {
00876     return c_str_len_a(cs);
00877 }
00878 inline char const* c_str_ptr_a(struct cstring_t const& cs)
00879 {
00880     return c_str_data_a(cs);
00881 }
00882 inline char const* c_str_ptr(struct cstring_t const& cs)
00883 {
00884     return c_str_data_a(cs);
00885 }
00886 
00887 # ifndef _STLSOFT_NO_NAMESPACE
00888 namespace stlsoft
00889 {
00890     using ::c_str_data_a;
00891     using ::c_str_len_a;
00892     using ::c_str_ptr_a;
00893     using ::c_str_data;
00894     using ::c_str_len;
00895     using ::c_str_ptr;
00896 
00897 } /* namespace stlsoft */
00898 # endif /* !_STLSOFT_NO_NAMESPACE */
00899 
00900 #endif /* __cplusplus */
00901 
00902 /* /////////////////////////////////////////////////////////////////////////
00903  * Compiler warnings
00904  */
00905 
00906 #if defined(_MSC_VER)
00907 # if _MSC_VER >= 1200
00908 /* #  pragma warning(pop) */
00909 # endif /* compiler */
00910 #endif /* compiler */
00911 
00912 /* /////////////////////////////////////////////////////////////////////////
00913  * Obsolete
00914  */
00915 
00916 #ifdef CSTRING_F_USE_WINDOWS_GLOBAL_MEMORY
00917 # define CSTRING_F_USE_WIN32_GLOBAL_MEMORY      CSTRING_F_USE_WINDOWS_GLOBAL_MEMORY
00918 #endif
00919 
00920 #ifdef CSTRING_F_USE_WINDOWS_PROCESSHEAP_MEMORY
00921 # define CSTRING_F_USE_WIN32_PROCESSHEAP_MEMORY CSTRING_F_USE_WINDOWS_PROCESSHEAP_MEMORY
00922 #endif
00923 
00924 #ifdef CSTRING_F_USE_WINDOWS_COM_TASK_MEMORY
00925 # define CSTRING_F_USE_WIN32_COM_TASK_MEMORY    CSTRING_F_USE_WINDOWS_COM_TASK_MEMORY
00926 #endif
00927 
00928 /* ////////////////////////////////////////////////////////////////////// */
00929 
00930 #endif /* CSTRING_INCL_CSTRING_H_CSTRING */
00931 
00932 /* ////////////////////////////////////////////////////////////////////// */

cstring Library documentation (c) Matthew Wilson and Synesis Software Pty Ltd, 1994-2012