/*
*    C Interface: SPString
*
*    Description: simple String structure and manipulation
*
*    This class provides a safe and convenient, albeit slower, alternative
*    to C character chains.
*
*    There are two types of strings:
*    1. String is a fully dynamic string, that is be resized automatically
*    at runtime when calling stringcpy and similar functions.
*    One doesn't have to worry about buffer length.
*    2. LString (Local String) has a fixed buffer size.
*    lstringcpy and the like will check that the buffer size is respected
*    and raise an error if it's not the case.
*
*    One can easily create a String from a C string with
*    newString(const char *).
*    String.str always returns a null-terminated C chain, and String.len
*    returns its length.
*    One should always avoid to manipulate the String structure members
*    directly in order to prevent corruption (i.e mainly incorrect sz and
*    len values).
*
*    Most functions mirror standard C functions.
*/

#ifndef SPSTRING_H
#define SPSTRING_H

#include <stddef.h>

/* ---- Allocation on the stack (non dynamic)
   The size sz is fixed once and for all at creation and must be the maximum
   size of the buffer holding the string, not the length of the C character
   string passed as parameter at initialization.

    Example Usage:
    {
      #define SIZE 40   /* the LString cannot never grow longer than 39 chars */
      const char buff[SIZE] = "Hello";
      LString *hello = localString(buff, SIZE);
      ...
      lstringchcat(hello, " World !");
    } /* automatic deallocation at end of scope */

   Warning: The following does not work (because localString does
            not allocate memory):
    LString *hello = localString("Hello World", SIZE);
*/

/* Definition of a local String */
typedef struct {
    size_t sz;  /* max buffer size, fixed, always > len */
    size_t len; /*length (final '\0' excluded)            */
    char *str;  /* null terminated character chain        */
} LString;

/* Create a local String */
LString localString ( char *chars, size_t szMax );

size_t lstringcpy ( LString *dst, const LString *src );
size_t lstringchcpy ( LString *dst, const char *src );
size_t lstringcat ( LString *dst, const LString *src );
size_t lstringchcat ( LString *dst, const char *src );
LString lstringdup ( const LString *src );


/* --- Dynamic allocation
   The size is automatically adjusted at any time.

   Usage example:
      LString *hello = newString("Hello ");
      ...
      stringchcat(hello, " world !");
      ...
      delString(myString);
*/

typedef struct{
    size_t sz;  /* max buffer size, dynamic(always > len) */
    size_t len; /* length (final '\0' excluded)          */
    char *str;  /* null terminated character chain       */
} String;

/* Allocate a new String object.
 * The source buffer passed as parameter is copied so it must be
 * deallocated manually. */
String * newString(const char *);
void delString(String *);

size_t stringcpy(String *dst, const String *src);
size_t stringchcpy(String *dst, const char *src);
size_t stringcat(String *dst, const String *src);
size_t stringchcat(String *dst, const char *src);
String * stringdup(const String *);

/* --- The following functions apply both on String and LString */

size_t stringlen(const String *);
int stringcmp(const String *st1, const String *st2);
int stringchcmp(const String *st1, const char *st2);
/* Truncation of length to Nth character */
String * stringtrunc(String *string, size_t N);
void stringprintf ( String *dst, const char * format, ... );
/* Verification of internal consistency of a String/LString
   Can be useful in a debugging session */
int stringcheck(const String *string, char *file, int line);

/* Use this function to get the error code     */
/* if (get_stringerr() != ST_NO_ERR) --> error */
int get_stringerr();

/* Possible errors */
#define ST_NO_ERR                   -1000
#define ST_OVERWRITE_ERR            -1001
#define ST_ALLOC_ERR                -1002
#define ST_NULLPARAM_ERR            -1003
#define ST_NULLSTR_ERR              -1004
#define ST_INCONSISTENTSZ_ERR       -1005
#define ST_INCONSISTENTLEN_ERR      -1006

#endif