#ifndef STRING_H
#define STRING_H

#include <iostream>
#include <stdexcept>

class String {

public: // ctors and dtor

    /** Name: String
     *
     * Description: Constructs a String of a certain size by
     *  dynamically allocating a valid C string.  The C string
     *  should be size + 1 in order to account for the null
     *  character pad.
     *
     *      String s1; 
     *
     * @param   size    the size of the string
     */
    String(int size = 0);

    /** Name: String
     *
     * Description: Constructs a String from a native C string.
     *
     *      String s1("hello");     // s1 = "hello";
     *
     * @param   s       the native c string
     */
    String(const char *s);

    /** Name: String
     *
     * Description: Copy constructs a String from another String.
     *  The C string should be dynamically allocated and copied
     *  from other's C String.
     *
     * @param   s       the native C string
     */
    String(const String& other);

    /** Name: String
     *
     * Description: Destructs a string object and delete's any
     *  dynamic memory associated with the C string.
     */
    ~String();

public: // common string routines

    /** Name: length
     *
     * Description: Get the length of the string.  This routine
     * ignores the null pad character when counting the size of 
     * the internal C string.
     *
     * @return the size of the string
     */
    size_t length() const;

    /** Name: c_str
     *
     * Description: Get the native C string within this String.
     *
     * @return the native C string
     */
    const char* c_str() const;

    /** Name: substring
     *
     * Description: Returns a new String which is a substring of 
     *  the original string.  
     *
     *  String s1("helloworld");
     *  s1.substring(3, 8);     // "lowor"
     *
     * @param   start   the starting index of the substring (inclusive)
     * @param   end     the ending index of the substring (exclusive)
     *
     * @return the substring from start to end-1 indexes
     *
     * @exception a range_error exception is thrown if the ranges
     *  are invalid.
     */
    String substring(int start, int end) const throw(std::range_error);

    /** Name: find
     *
     * Description: Returns the starting index of the other String,
     *  if it is present.  If the other String is not present, it
     *  returns -1.
     *
     *  String s1("helloworldhello");
     *  s1.find("world");       // 5
     *
     * @param   other   the String to find
     *
     * @return  the starting index of the other String, if present,
     *  otherwise -1.
     *
     */
    int find(String other) const;
    
public: // assignment methods

    /** Name: operator[]
     *
     * Description: Returns the character at the specified index
     *  in the String.  If the index is out of range, an
     *  exception is thrown.  This routine can be used
     *  for accessing as well as mutating a character
     *  in the string.
     *
     * @param   index   the index of the character in the String
     *
     * @return the character at the position in the String
     *
     * @exception a range_error exception is thrown if the 
     *  index is invalid
     */
    char& operator[](int index) const throw(std::range_error);

    /** Name: operator=
     *
     * Description: Assigns this String to another String object.
     *
     * @param   other   the other String object to be assigned from.
     *
     * @return a reference to this string object (to support
     *  chained assignment.
     */
    String& operator=(const String &other);

public: // comparison methods

    /** Name: operator==
     *
     * Description: Indicates whether this String is equivalent to
     *  another String object.
     *
     *      String s1("hello");
     *      String s2("world");
     *      s1 == s2;                // false
     *
     * @param   other   the other String object to be compared to.
     *
     * @return 'true' if the String's are equal, and 'false' otherwise.
     */
    bool operator==(const String &other) const;

    /** Name: operator<
     *
     * Description: Indicates whether this String is less than
     *  another String object.
     *      
     *      String s1("hello");
     *      String s2("world");
     *      s1 < s2;                // true
     *
     * @param   other   the other String object to be compared to.
     *
     * @return 'true' if this String is less than the other String,
     *  and 'false' otherwise.
     */
    bool operator<(const String &other) const;

    /**
     * Name: operator>
     *
     * Description: Indicates whether this String is greater than
     *  another String object.
     *      
     *      String s1("hello");
     *      String s2("world");
     *      s1 > s2;                // false
     *
     * @param   other   the other String object to be compared to.
     *
     * @return 'true' if this String is greater than the other String,
     *  and 'false' otherwise.
     */
    bool operator>(const String &other) const;

public: // conctenation and repetition methods

    /** Name: operator+
     * 
     * Description: Concatenates this String with another String.
     *
     *      String s1("hello");
     *      String s2("world");
     *      s1 + s2;    // "helloworld"
     *
     * @param   other   the other String to be concatenated with.
     *
     * @return A new String containing the concatenation.
     */
    String operator+(const String& other) const;

    /** Name: operator*
     *
     * Description: Creates a repetition of this String a certain number
     * of times.
     *
     *      String s1("hello");
     *      s1 * 3;    // "hellohellohello"
     *
     * @param   num     the number of repetitions of this string to make.
     *
     * @return  A new string with the repetition.
     */
    String operator*(int num) const;

    /** Name: operator*
     *
     * Description: Creates a repetition of this String a certain number
     * of times.
     *
     *      String s1("hello");
     *      3 * s1;    // "hellohellohello"
     *
     * @param   num     the number of repetitions of this string to make.
     *
     * @return  A new string with the repetition.
     */
    friend String operator*(int num, String& other);

public: // combo perform/assign methods

    /** Name: operator+=
     *
     * Description: Concatenates this String with another String, and
     *  assigns the result to this String.
     *
     *      String s1("hello");
     *      String s2("world");
     *      s1 += s2;           // s1="helloworld", s2="world"
     *
     * @param   other   the other String object to be concatenated with.
     *
     * @return A reference to this String.
     */
    String& operator+=(const String &other);

    /** Name: operator*=
     *
     * Description: Creates a repetition of this String a certain number
     * of times, and assigns that result to this String.
     *
     *      String s1("hello");
     *      s1 *= 3;    // s1 = "hellohellohello"
     *
     * @param   num     the number of repetitions of this string to make.
     *
     * @return A reference to this String.
     */
    String& operator*=(int num);

public:  // I/O methods

    /** Name: operator>>
     *
     * Description: Reads a string from the input stream into
     *  a String object.  Any pre-existing string is removed
     *  and a new one is created.
     *
     *      String s1;
     *      cin >> s1;    // input="hello", s1="hello
     *
     * @param   is  the input stream
     * @param   s   the String object to be read into
     *
     * @return  A reference to the input stream
     */
    friend std::istream& operator>>(std::istream &is, String &s);

    /** Name: operator<<
     *
     * Description: Print a String object to the output stream
     *
     *      String s1("hello");
     *      cout << s1;    // prints to standard output: hello
     *
     * @param   os  the output stream
     * @param   s   the String object to print
     *
     * @return  A reference to the output stream
     */
    friend std::ostream& operator<<(std::ostream &os, const String &s);

private:
    char *str;                          // the dynmically allocated C string
    int len;   // the maximum number of valid characters in the string
    static const int BUFF_INC = 20;     // the buffer increment value
    static const char* WHITESPACE;      // a string of whitespace characters
};

#endif