/*  xstring.h
    Aug 31 1998
    Chris Lacher

    Definition of the String class 
    The 'x' is so compiler won't confuse file names. 

    See also xranxstr.h, xstrcomp.h

    08/31/98
    08/06/00: upgraded treatment of boolean operators and StrCmp()
    10/18/00: added constructor String (size_t sz, char fill)
    12/07/02: removed outdated method Cstr(), made Clear() a public method

    Copyright 1998 - 2003, R.C. Lacher
*/

#ifndef _XSTRING_H
#define _XSTRING_H

#include <iostream>
#include <stdlib.h> // size_t

namespace fsu
{

//--------------------
//    class String
//--------------------

class String
{
  // extraction and insertion operators
  friend std::ostream& operator << (std::ostream& os, const String& S);
  friend std::istream& operator >> (std::istream& is, String& S);

  // String sum (concatenation) operator
  friend const String operator + (const String&, const String&);

  public:
    // constructors
    String           ();                     // construct a null string 
    String           (const char* Cptr);     // construct a string around Cptr
    String           (size_t sz, char fill); // size sz and all characters = fill
    ~String          ();                     // destructor
    String           (const String& S);      // copy constructor
  
    // operators
    String& operator =   (const String& S);  // assignment operator
    char&   operator []  (size_t n) const;   // returns REFERENCE to the character at place n
    operator const char* () const;           // auto conversion of String to const char*
    // this operator safely allows a String to be used for any const char* argument

    // builders
    void  Wrap    (const char* Cptr);        // wrap Cptr up in a String
    void  GetLine (std::istream& in1);       // read/wrap entire line
    int   SetSize (size_t sz, char fill);    // keep old data, fill extra spaces with fill character
    void  Clear   ();                        // make String empty (zero size)

    // data accessors (const)
    size_t Size    ()               const;
    size_t Length  ()               const;   // calls strlen(const char*)
    char         Element (size_t n) const;   // returns VALUE of the character at place n
                                             // (returns '\0' if n is out of range)

    // String comparison function
    static int StrCmp (const String&, const String&);
    // modelled on the classic strcmp() in string.h
    // called by the boolean equality and order operators

    void String::Dump (std::ostream& os) const;
    // displays structural output for development and testing

  private:
    // data
    char *   str;
    size_t   size;

    // methods
    void          Clone   (const String& S);
    static void   Error   (const char*);
    static int    xstrlen (const char*);
    static void   xstrcpy (char*, const char*);
    static char*  newstr  (int n);
}  ;

// equality and order comparison operators
int operator == (const String& S1, const String& S2);
int operator != (const String& S1, const String& S2);
int operator <  (const String& S1, const String& S2);
int operator <= (const String& S1, const String& S2);
int operator >= (const String& S1, const String& S2);
int operator >  (const String& S1, const String& S2);

}   // namespace fsu
#endif