cstring/cstring.h

Go to the documentation of this file.

/* /////////////////////////////////////////////////////////////////////////
 * File:    cstring/cstring.h
 *
 * Purpose: Definition of the cstring API.
 *
 * Created: 16th June 1994
 * Updated: 28th July 2011
 *
 * Home:    http://synesis.com.au/software/
 *
 * Copyright (c) 1994-2011, Matthew Wilson and Synesis Software
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * - Redistributions of source code must retain the above copyright notice, this
 *   list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 * - Neither the names of Matthew Wilson and Synesis Software nor the names of
 *   any contributors may be used to endorse or promote products derived from
 *   this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * ////////////////////////////////////////////////////////////////////// */


#ifndef CSTRING_INCL_CSTRING_H_CSTRING
#define CSTRING_INCL_CSTRING_H_CSTRING

/* /////////////////////////////////////////////////////////////////////////
 * Version
 */

#ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
# define CSTRING_VER_CSTRING_H_CSTRING_MAJOR    3
# define CSTRING_VER_CSTRING_H_CSTRING_MINOR    8
# define CSTRING_VER_CSTRING_H_CSTRING_REVISION 1
# define CSTRING_VER_CSTRING_H_CSTRING_EDIT     60
#endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */

#ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
# define CSTRING_VER_1_0_1      0x01000100
# define CSTRING_VER_1_0_2      0x01000200
# define CSTRING_VER_2_0_1      0x02000100
# define CSTRING_VER_2_1_1      0x02010100
# define CSTRING_VER_2_2_1      0x02020100
# define CSTRING_VER_3_0_1      0x03000100
# define CSTRING_VER_3_1_1      0x03010100
# define CSTRING_VER_3_1_2      0x03010200
# define CSTRING_VER_3_1_3      0x03010300
# define CSTRING_VER_3_2_1      0x03020100
# define CSTRING_VER_3_3_1      0x03030100
# define CSTRING_VER_3_3_2      0x03030200
# define CSTRING_VER_3_4_1      0x03040100
# define CSTRING_VER_3_4_2      0x03040200
# define CSTRING_VER_3_4_3      0x03040300
# define CSTRING_VER_3_4_4      0x03040400
# define CSTRING_VER_3_5_1      0x03050100
# define CSTRING_VER_3_5_2      0x03050200
# define CSTRING_VER_3_5_3      0x03050300
# define CSTRING_VER_3_5_4      0x03050400
# define CSTRING_VER_3_6_1      0x03060100

# define CSTRING_VER            CSTRING_VER_3_6_1
#else /* ? CSTRING_DOCUMENTATION_SKIP_SECTION */
# define CSTRING_VER            0x03060100
#endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */

#define CSTRING_VER_MAJOR       3
#define CSTRING_VER_MINOR       6
#define CSTRING_VER_REVISION    1

/* /////////////////////////////////////////////////////////////////////////
 * Includes
 */

#include <stddef.h>
#include <stdio.h>

/* /////////////////////////////////////////////////////////////////////////
 * Documentation
 */

/* /////////////////////////////////////////////////////////////////////////
 * Storage class
 */

#ifdef __cplusplus
# define CSTRING_EXTERN_C       extern "C"
#else /* ? __cplusplus */
# define CSTRING_EXTERN_C       extern
#endif /* ? __cplusplus */

/* /////////////////////////////////////////////////////////////////////////
 * Constants & definitions
 */

enum CSTRING_RC
{
        CSTRING_RC_SUCCESS               =   0  
    ,   CSTRING_RC_OUTOFMEMORY                  
    ,   CSTRING_RC_FIXED                        
    ,   CSTRING_RC_BORROWED                     
    ,   CSTRING_RC_READONLY                     
    ,   CSTRING_RC_INVALIDARENA                 
    ,   CSTRING_RC_CUSTOMARENANOTSUPPORTED      
    ,   CSTRING_RC_EXCEEDFIXEDCAPACITY          
    ,   CSTRING_RC_EXCEEDBORROWEDCAPACITY       
    ,   CSTRING_RC_CANNOTYIELDFROMSO            
    ,   CSTRING_RC_ARENAOVERLOADED              
    /* cstring 3.5+ */
    ,   CSTRING_RC_INVALIDSTREAM                
    ,   CSTRING_RC_EOF                          
    ,   CSTRING_RC_INVALIDSECTION               
    ,   CSTRING_RC_IOERROR                      
};
#ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
typedef enum CSTRING_RC     CSTRING_RC;
#endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////
 * Typedefs
 */

typedef int cstring_flags_t;

struct cstring_t
{
    size_t          len;        
    char*           ptr;        
    size_t          capacity;   
    cstring_flags_t flags;      
};
#ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
typedef struct cstring_t    cstring_t;
#endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */

#define cstring_t_DEFAULT  { 0, NULL, 0, 0 }

/* /////////////////////////////////////////////////////////////////////////
 * Custom settings
 */

#ifndef CSTRING_NO_USE_SYNESIS_APIS
# if defined(_SYNSOFT_INCL_H_MLMEMORY)
#  define CSTRING_USE_SYNESIS_APIS
# endif /* _SYNSOFT_INCL_H_MLMEMORY */
#endif /* !CSTRING_NO_USE_SYNESIS_APIS */

/* /////////////////////////////////////////////////////////////////////////
 * Macros
 */

#define CSTRING_FROM_END(x)     (-1 - (int)(x))

/* /////////////////////////////////////////////////////////////////////////
 * Flags
 */

#define CSTRING_F_TYPE_MASK                     (0x003f)
#define CSTRING_F_MEMORY_IS_INTERNAL_HEAP       (0x0000)    
#define CSTRING_F_MEMORY_IS_BORROWED            (0x0001)    
#define CSTRING_F_MEMORY_IS_FIXED               (0x0002)    
#define CSTRING_F_MEMORY_IS_READONLY            (0x0004)    
#define CSTRING_F_MEMORY_IS_CONST               CSTRING_F_MEMORY_IS_READONLY 
#define CSTRING_F_MEMORY_IS_OFFSET              (0x0040)    
#define CSTRING_F_MEMORY_CAN_GROW_TO_HEAP       (0x0080)    
#define CSTRING_F_ARENA_MASK                    (0xff00)
#define CSTRING_F_USE_REALLOC                   (0x0000)    
#if defined(WIN32) || \
    defined(WIN64)
# define CSTRING_F_USE_WINDOWS_GLOBAL_MEMORY    (0x0100)    
# define CSTRING_F_USE_WINDOWS_PROCESSHEAP_MEMORY (0x0200)  
# define CSTRING_F_USE_WINDOWS_COM_TASK_MEMORY  (0x0400)    
#endif /* WIN32 || WIN64 */
#if defined(CSTRING_USE_SYNESIS_APIS)
# define CSTRING_F_USE_SYNESIS_HATOR            (0x1000)    
#endif /* CSTRING_USE_SYNESIS_APIS */
#define CSTRING_F_USE_CUSTOMARENAFUNCTIONS      (0x2000)    
#define CSTRING_F_CUSTOMARENA_CC_CDECL          (0x0000)    
#define CSTRING_F_CUSTOMARENA_CC_STDCALL        (0x0040)    
/* /////////////////////////////////////////////////////////////////////////
 * API functions
 */

CSTRING_EXTERN_C char const* cstring_getStatusCodeString(
    CSTRING_RC  rc
);

CSTRING_EXTERN_C size_t cstring_getStatusCodeStringLength(
    CSTRING_RC  rc
);

#if defined(_MSC_VER) && \
    _MSC_VER >= 1400
__declspec(deprecated("cstring_error() is deprecated, and may be removed in a future version: instead use cstring_getStatusCodeString()"))
#endif /* compiler */
CSTRING_EXTERN_C char const* cstring_error(
    CSTRING_RC  rc
);

CSTRING_EXTERN_C CSTRING_RC cstring_init(
    struct cstring_t*       pcs
);

CSTRING_EXTERN_C CSTRING_RC cstring_create(
    struct cstring_t*   pcs
,   char const*         s
);

CSTRING_EXTERN_C CSTRING_RC cstring_createLen(
    struct cstring_t*       pcs
,   char const*             s
,   size_t                  cch
);

CSTRING_EXTERN_C CSTRING_RC cstring_createN(
    struct cstring_t*       pcs
,   char                    ch
,   size_t                  n
);


CSTRING_EXTERN_C CSTRING_RC cstring_createEx(
    struct cstring_t*       pcs
,   char const*             s
,   cstring_flags_t         flags
,   void*                   arena
,   size_t                  capacity
);

CSTRING_EXTERN_C CSTRING_RC cstring_createLenEx(
    struct cstring_t*       pcs
,   char const*             s
,   size_t                  cch
,   cstring_flags_t         flags
,   void*                   arena
,   size_t                  capacity
);

CSTRING_EXTERN_C CSTRING_RC cstring_destroy(
    struct cstring_t*       pcs
);


CSTRING_EXTERN_C CSTRING_RC cstring_yield2(
    struct cstring_t*       pcs
,   char**                  pPayload
,   void**                  pRaw
);

#ifdef CSTRING_OBSOLETE
CSTRING_EXTERN_C CSTRING_RC cstring_yield(
    struct cstring_t*       pcs
,   char**                  ppBuff
);
#endif /* CSTRING_OBSOLETE */

CSTRING_EXTERN_C CSTRING_RC cstring_setCapacity(
    struct cstring_t*       pcs
,   size_t                  capacity
);


CSTRING_EXTERN_C CSTRING_RC cstring_assign(
    struct cstring_t*       pcs
,   char const*             s
);

CSTRING_EXTERN_C CSTRING_RC cstring_assignLen(
    struct cstring_t*       pcs
,   char const*             s
,   size_t                  cch
);

CSTRING_EXTERN_C CSTRING_RC cstring_copy(
    struct cstring_t*       pcs
,   struct cstring_t const* pcsSrc
);

CSTRING_EXTERN_C CSTRING_RC cstring_append(
    struct cstring_t*       pcs
,   char const*             s
);

CSTRING_EXTERN_C CSTRING_RC cstring_appendLen(
    struct cstring_t*       pcs
,   char const*             s
,   size_t                  cch
);

CSTRING_EXTERN_C CSTRING_RC cstring_truncate(
    struct cstring_t*       pcs
,   size_t                  len
);

CSTRING_EXTERN_C CSTRING_RC cstring_swap(
    struct cstring_t*       pcs1
,   struct cstring_t*       pcs2
);


CSTRING_EXTERN_C CSTRING_RC cstring_readline(
    FILE*               stm
,   struct cstring_t*   pcs
,   size_t*             numRead /* = NULL */
);

CSTRING_EXTERN_C CSTRING_RC cstring_writeline(
    FILE*                   stm
,   struct cstring_t const* pcs
,   size_t*                 numWritten /* = NULL */
);


CSTRING_EXTERN_C CSTRING_RC cstring_insert(
    struct cstring_t*       pcs
,   int                     index
,   char const*             s
);

CSTRING_EXTERN_C CSTRING_RC cstring_insertLen(
    struct cstring_t*       pcs
,   int                     index
,   char const*             s
,   size_t                  cch
);

CSTRING_EXTERN_C CSTRING_RC cstring_replace(
    struct cstring_t*       pcs
,   int                     index
,   size_t                  len
,   char const*             s
);

CSTRING_EXTERN_C CSTRING_RC cstring_replaceLen(
    struct cstring_t*       pcs
,   int                     index
,   size_t                  len
,   char const*             s
,   size_t                  cch
);

CSTRING_EXTERN_C CSTRING_RC cstring_replaceAll(
    struct cstring_t*       pcs
,   char const*             f
,   char const*             t
,   size_t*                 numReplaced /* = NULL */
);

/* ////////////////////////////////////////////////////////////////////// */

#ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
typedef int (*cstring_allocFailHandler)(void* pv, size_t cb, cstring_flags_t flags, void* param);


CSTRING_EXTERN_C CSTRING_RC cstring_createLenFn(
    struct cstring_t*           pcs
,   char const*                 s
,   size_t                      cch
,   cstring_flags_t             flags
,   void*                       arena
,   size_t                      capacity
,   cstring_allocFailHandler    pfnAllocFailHandler
,   void*                       param
);

CSTRING_EXTERN_C CSTRING_RC cstring_setCapacityFn(
    struct cstring_t*           pcs
,   size_t                      capacity
,   cstring_allocFailHandler    pfnAllocFailHandler
,   void*                       param
);

CSTRING_EXTERN_C CSTRING_RC cstring_assignFn(
    struct cstring_t*           pcs
,   char const*                 s
,   cstring_allocFailHandler    pfnAllocFailHandler
,   void*                       param
);
CSTRING_EXTERN_C CSTRING_RC cstring_assignLenFn(
    struct cstring_t*           pcs
,   char const*                 s
,   size_t                      cch
,   cstring_allocFailHandler    pfnAllocFailHandler
,   void*                       param
);

CSTRING_EXTERN_C CSTRING_RC cstring_appendFn(
    struct cstring_t*           pcs
,   char const*                 s
,   cstring_allocFailHandler    pfnAllocFailHandler
,   void*                       param
);

CSTRING_EXTERN_C CSTRING_RC cstring_appendLenFn(
    struct cstring_t*           pcs
,   char const*                 s
,   size_t                      cch
,   cstring_allocFailHandler    pfnAllocFailHandler
,   void*                       param
);
#endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////
 * Compiler warnings
 */

#if defined(_MSC_VER)
# if _MSC_VER >= 1200
#  pragma warning(push)
# endif /* compiler */
# pragma warning(disable : 4514) /* unreferenced inline function has been removed */
#endif /* compiler */

/* /////////////////////////////////////////////////////////////////////////
 * String Access Shims
 */

#ifdef __cplusplus

inline char const* c_str_data_a(struct cstring_t const* pcs)
{
    return (NULL == pcs || 0u == pcs->len) ? "" : pcs->ptr;
}
inline char const* c_str_data(struct cstring_t const* pcs)
{
    return c_str_data_a(pcs);
}
inline size_t c_str_len_a(struct cstring_t const* pcs)
{
    return (NULL == pcs) ? 0u : pcs->len;
}
inline size_t c_str_len(struct cstring_t const* pcs)
{
    return c_str_len_a(pcs);
}
inline char const* c_str_ptr_a(struct cstring_t const* pcs)
{
    return c_str_data_a(pcs);
}
inline char const* c_str_ptr(struct cstring_t const* pcs)
{
    return c_str_data_a(pcs);
}

inline char const* c_str_data_a(struct cstring_t const& cs)
{
    return (0u == cs.len) ? "" : cs.ptr;
}
inline char const* c_str_data(struct cstring_t const& cs)
{
    return c_str_data_a(cs);
}
inline size_t c_str_len_a(struct cstring_t const& cs)
{
    return cs.len;
}
inline size_t c_str_len(struct cstring_t const& cs)
{
    return c_str_len_a(cs);
}
inline char const* c_str_ptr_a(struct cstring_t const& cs)
{
    return c_str_data_a(cs);
}
inline char const* c_str_ptr(struct cstring_t const& cs)
{
    return c_str_data_a(cs);
}

inline char const *c_str_data_a(CSTRING_RC rc)
{
    return cstring_getStatusCodeString(rc);
}
inline char const *c_str_data(CSTRING_RC rc)
{
    return cstring_getStatusCodeString(rc);
}

inline size_t c_str_len_a(CSTRING_RC rc)
{
    return cstring_getStatusCodeStringLength(rc);
}
inline size_t c_str_len(CSTRING_RC rc)
{
    return cstring_getStatusCodeStringLength(rc);
}

inline char const *c_str_ptr_a(CSTRING_RC rc)
{
    return cstring_getStatusCodeString(rc);
}
inline char const *c_str_ptr(CSTRING_RC rc)
{
    return cstring_getStatusCodeString(rc);
}

# ifndef _STLSOFT_NO_NAMESPACE
namespace stlsoft
{
    using ::c_str_data_a;
    using ::c_str_len_a;
    using ::c_str_ptr_a;
    using ::c_str_data;
    using ::c_str_len;
    using ::c_str_ptr;

} /* namespace stlsoft */
# endif /* !_STLSOFT_NO_NAMESPACE */

#endif /* __cplusplus */

/* /////////////////////////////////////////////////////////////////////////
 * Compiler warnings
 */

#if defined(_MSC_VER)
# if _MSC_VER >= 1200
/* #  pragma warning(pop) */
# endif /* compiler */
#endif /* compiler */

/* /////////////////////////////////////////////////////////////////////////
 * Obsolete
 */

#ifdef CSTRING_F_USE_WINDOWS_GLOBAL_MEMORY
# define CSTRING_F_USE_WIN32_GLOBAL_MEMORY      CSTRING_F_USE_WINDOWS_GLOBAL_MEMORY
#endif

#ifdef CSTRING_F_USE_WINDOWS_PROCESSHEAP_MEMORY
# define CSTRING_F_USE_WIN32_PROCESSHEAP_MEMORY CSTRING_F_USE_WINDOWS_PROCESSHEAP_MEMORY
#endif

#ifdef CSTRING_F_USE_WINDOWS_COM_TASK_MEMORY
# define CSTRING_F_USE_WIN32_COM_TASK_MEMORY    CSTRING_F_USE_WINDOWS_COM_TASK_MEMORY
#endif

/* ////////////////////////////////////////////////////////////////////// */

#endif /* CSTRING_INCL_CSTRING_H_CSTRING */

/* ////////////////////////////////////////////////////////////////////// */

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