/*
 * String is an efficient and safe string datatype.  An object of type String*
 * points to a structure containing a sequence of zero or more chars.  It may
 * NOT be assumed that the representation of String is char*.  In particular,
 * casting String* objects to char*, and vice versa, will not produce
 * meaningful results.  To pass String* objects to C functions that expect
 * arguments of type char*, use the functions ConstStringConvert or
 * StringConvert.  To covert char* objects to String*, use the function
 * NewString.
 *
 * For convenience, typical string operations are provided.  Hence, Strings
 * may be used in place of char* if standard C string handling is not to your
 * liking.
 *
 * Note that the String type has been designed with certain usages in mind, in
 * particular the use of Strings as keys in a hash table.  If such usage is of
 * interest, read carefully the documentation for ConstStringConvert given at
 * its definition below.
 */

#ifndef strIncluded
#define strIncluded

#include "std-macros.h"


/**
 * Public Types.
 */
typedef struct StringStruct {
    char* data;
    int len;
} String;


/**
 * Public Operations.
 */
#ifdef USEWITHCPP
extern "C"
#endif
String* NewString();
/*
 * Return a pointer to a new string containing the chars of s.
 */

#ifdef USEWITHCPP
extern "C"
#endif
String* NewString1(char* s);
/*
 * Return a pointer to a new string containing the chars of s.  If s is null, a
 * null string is created.  Hence, NewString(null) and NewString("") represent
 * the same object, even though null and "" are different values.
 */

#ifdef USEWITHCPP
extern "C"
#endif
String* NewStringQuotes(char* s);
/*
 * Return a pointer to a new string containing the chars of s, except it pulls
 * off the first and last chars assuming that they're quotes.  If s is null, a
 * null string is created.  Hence, NewString(null) and NewString("") represent
 * the same object, even though null and "" are different values.
 */


#ifdef USEWITHCPP
extern "C"
#endif
void DelString(String* s);
/*
 * Deallocate an existing string.
 */

#ifdef USEWITHCPP
extern "C"
#endif
int StringLen(String* s);
/*
 * Return the length of s.
 */

#ifdef USEWITHCPP
extern "C"
#endif
int StringCompare(String* s1, String* s2);
/*
 * Lexically compare two strings per the convention of C strcmp.  Viz., return
 * <0 if s1 lexically preceeds s2, 0 if s1 and s2 are lexically equal, and >0
 * if s lexically succeeds s.  If s1 and s2 are both null, 0 is returned.  If
 * s1 only is null, <0 is returned.  If s2 only is null, >0 is returned.
 */

#ifdef USEWITHCPP
extern "C"
#endif
int StringCompareCS(String* s1, char* s2);
/*
 * Obvious overload of StringCompare.  Specs are the same.
 */

#ifdef USEWITHCPP
extern "C"
#endif
bool StringEqual(String* s1, String* s2);
/*
 * Return true if s1 lexically equals s2.
 */

#ifdef USEWITHCPP
extern "C"
#endif
bool StringEqualCS(String* s1, char* s2);
/*
 * Obvious overload of StringEqual.
 */

#ifdef USEWITHCPP
extern "C"
#endif
bool StringContains(String* s1, String* s2);
/*
 * Returns true if there's at least one occurrence of s2 within s1. else, false.
 */

#ifdef USEWITHCPP
extern "C"
#endif
String* StringConcat(String* s1, String* s2);
/*
 * Return a new string that is the concatentation of s1 and s2.  The new string
 * is an entirely new object, the representation of which refers to neither s1
 * nor s2.  If s1 and s2 are both null, NewString("") is returned.  If s1 only
 * is null, StringCopy(s2) is returned.  If s2 only is null, StringCopy(s1) is
 * returned.
 */

#ifdef USEWITHCPP
extern "C"
#endif
String* StringConcatCS(String* s1, char* s2);
/*
 * Obvious overload of StringConcat.  Specs are the same.
 */

#ifdef USEWITHCPP
extern "C"
#endif
String* StringCopy(String* s);
/*
 * Return a new string that is a copy of s.  If s is null, NewString("") is
 * returned.
 */

#ifdef USEWITHCPP
extern "C"
#endif
String* SubString(String* s, int startpos, int endpos);
/*
 * Return a substring of s between character positions startpos and endpos,
 * inclusive.  Character positions start at 1 (NOT 0 as in char*'s).  If
 * startpos < 1 or endpos > StringLen(s) or startpos > endpos, a null string is
 * returned (NOT null).
 */

#ifdef USEWITHCPP
extern "C"
#endif
char GetNthStringChar(String* s, int n);
/*
 * Return the nth char in s.  Character positions start at 1 (NOT 0 as in
 * char*'s).  If n < 1 or n > StringLen(s), the null char is returned.
 */

#ifdef USEWITHCPP
extern "C"
#endif
String* GetNthStringCharAsString(String* s, int n);
/*
 * Return the nth char in s.  Character positions start at 1 (NOT 0 as in
 * char*'s).  If n < 1 or n > StringLen(s), the null char is returned.
 */

#ifdef USEWITHCPP
extern "C"
#endif
String* Stringify(int i);
/*
 * Convert the given integer to a string and return it.
 */


#ifdef USEWITHCPP
extern "C"
#endif
char* StringConvert(String* s);
/*
 * Return a copy of s as a char*.  Note that the returned pointer does NOT
 * reference the representation of s, so any subsequent changes made through
 * the returned pointer will not affect s.  Given the behavior of NewString,
 * StringConvert will never return null.  I.e., StringConvert(String(null))
 * returns "", not null.
 */

#ifdef USEWITHCPP
extern "C"
#endif
const char* ConstStringConvert(String* s);

#endif