/****
 *
 * Class String is an abstract data type for character strings, providing
 * typical operations for string manipulation.  The operations include
 * construction, destruction, copy, length, various forms of comparison,
 * concatenation, substring, and conversion to char*.
 *
 * Class String is designed to follow the conventions of the C+- subset of C++,
 * documented fully in http://www.csc.calpoly.edu/~gfisher/projects/alpha/
 * support/documentation/conventions/design-imple.{html,ps,txt}.  This means,
 * among other things, that String objects must always be declared as pointers
 * and allocated with new.  The protected copy constructor and assignment
 * operator ensure that non-pointer usage of Strings will cause compilation
 * errors.
 *
 * Pointer-only allocation of Strings means that expressions using overloaded
 * operators look a bit awkward, because explicit pointer dereference is
 * required.  E.g., if s1 and s2 are objects of type String*, they can be
 * concatenated using the expression
 *
 *	*s1 + *s2
 *
 * not the more natural-looking expression
 *
 *	s1 + s2
 *
 * Such slightly awkward notation is considered a small price to pay for the
 * otherwise splendid benifits of the C+- conventions.
 *
 */

#ifndef strIncluded
#define strIncluded


class String {
  public:
    String(const char* s);
    /*
     * Return a pointer to a new string containing the chars of s.  If s is
     * null, a null string is created.  Hence, null is never returned and
     * String(null) and String("") represent the same object, even though null
     * and "" are different values in C.
     */

    String(int i);
    /*
     * Construct a string as above, containing the characters of the ASCII
     * represenation of the given integer.
     */

    ~String();
    /*
     * Deallocate an existing string.
     */

    String* Copy();
    /*
     * Return a new string that is a copy of this.
     */

    int Len();
    /*
     * Return the length of this.
     */

    int Compare(String* s);
    /*
     * Lexically compare this and s per the convention of C strcmp.  Viz.,
     * return <0 if this lexically preceeds s, 0 if this and s are lexically
     * equal, and >0 if this lexically succeeds s.  Return 1 if s is null.  The
     * precise semantics of lexical comparison are those of strcmp.  I.e.,
     * comparison is done in "ASCIIbetic" order, which means in particular that
     * comparisons are case and puncutation sensitive.
     */

    int Compare(char* s);
    /*
     * Char* overload of Compare.  Specs are the same.
     */

    bool operator==(String& s);
    bool operator==(char* cs);
    bool operator<(String& s);
    bool operator<(char* cs);
    bool operator>(String& s);
    bool operator>(char* cs);
    bool operator<=(String& s);
    bool operator<=(char* cs);
    bool operator>=(String& s);
    bool operator>=(char* cs);
    /*
     * Lexically compare this and s (or cs) per the sense of the specified
     * operator.  Return true if the comparison succeeds, false if not.
     */ 

    String* Concat(String* s);
    /*
     * Return a new string that is the concatentation of this and s.  The new
     * string is an entirely new object, the representatoion of which refers to
     * neither this nor s.  If s is null, return this->Copy().
     */

    String* Concat(char* cs);
    /*
     * Char* overload of Concat.  Specs are the same.
     */

    String* operator+(String& s);
    String* operator+(char* cs);
    /*
     * Syntactic sugaring of Concat.  Specs are the same.
     */

    String* Prepend(String* s);
    /*
     * Return a new string that is the concatentation of s and this, i.e., the
     * ordering of the result is the reverse of Concat.  Otherwise, specs are
     * the same as Concat.
     */

    String* Prepend(char* s);
    /*
     * Char* overload of Prepend.  Specs are the same.
     */

    String* Substring(int startpos, int endpos);
    /*
     * Return a substring of this between character positions startpos and
     * endpos, inclusive.  Character positions start at 1, NOT 0 as in C
     * char*'s.  If startpos < 1, or endpos > this->Len(), or startpos >
     * endpos, return a null string (not null).  The return value is a new
     * object.
     */

    char GetNthChar(int n);
    /*
     * Return the nth char in this.  Return the null char if n < 1, or n >
     * this->Len().  Character positions start at 1, NOT 0 as in C char*'s.
     */

    char operator[](int n);
    /*
     * Syntactic sugaring of GetNth.  Specs are the same.
     */

    char* Convert();
    /*
     * Return a copy of this as a char*.  The returned pointer does not
     * reference the internal representation of this, so any subsequent changes
     * made through the returned pointer will not affect this.  Given the
     * behavior of the constructor, Convert will never return null.  I.e.,
     * Convert(String(null)) returns "", not null.
     */

    const char* ConstConvert();
    /*
     * Return a read-only pointer to the internal representation of this.
     * ConstConvert is particularly useful for printing with cout or printf,
     * since it converts to char* without copy overhead.  It is also useful for
     * any other functions that take const char* parameters.
     *
     * This function is safer than EvilConvert, but not totally safe because
     * only a warning occurs on misuse in many C++ compilers.
     */

    char* EvilConvert();
    /*
     * Return a mutable pointer to the internal rep of this.  User beware.
     */

  protected:
    void Init(const char* s);
    /*
     * Workdoer for the overloaded constructors.
     */


    /*
     * The current representation is simply a char*, with an int len for slight
     * efficiency.  A more efficient hashed and referenced counted
     * representation is planned for the future.
     */
    char* data;		// Internal data representation
    int len;		// Stored value of strlen(data)
    String();		// Implementation-level constructor
    String(String&);	// Standard noop copy constructor
    bool operator=(String&);	// Standard noop assignment overload
};

String* operator+(char* cs, String& s);
bool operator==(char* cs, String& s);
bool operator<(char* cs, String& s);
bool operator>(char* cs, String& s);
bool operator<=(char* cs, String& s);
bool operator>=(char* cs, String& s);
/*
 * Syntactic sugarings of Prepend and Compare.  Note that per C++ semantics,
 * these cannot be member functions of String, since the first argument is not
 * the distinguished type of the class.
 */

#endif