string.h

Go to the documentation of this file.

// -*- Mode: C++; tab-width: 2; -*-
// vi: set ts=2:
//
// $Id: string.h,v 1.56 2005/12/23 17:01:43 amoll Exp $
//

#ifndef BALL_DATATYPE_STRING_H
#define BALL_DATATYPE_STRING_H

#ifndef BALL_CONFIG_CONFIG_H
# include <BALL/CONFIG/config.h>
#endif
#ifndef BALL_COMMON_GLOBAL_H
# include <BALL/COMMON/global.h>
#endif
#ifndef BALL_COMMON_CREATE_H
# include <BALL/COMMON/create.h>
#endif
#ifndef BALL_COMMON_MACROS_H
# include <BALL/COMMON/macros.h>
#endif
#ifndef BALL_COMMON_EXCEPTION_H
# include <BALL/COMMON/exception.h>
#endif
#ifndef BALL_COMMON_DEBUG_H
# include <BALL/COMMON/debug.h>
#endif

#include <string>
#include <ctype.h>
#include <errno.h>
#include <stdlib.h>
#include <string.h>
#include <iostream>
#include <vector>

#ifdef BALL_HAS_SSTREAM
# include <sstream>
#else
# include <strstream>
#endif

using std::string;

namespace BALL 
{
  // forward declaration
  class Substring;

        
  class BALL_EXPORT String
    : public string
  {
    friend class Substring;

    public:
        
    // String has no copy constructor taking String&, bool as arguments.
    // the compiler would confuse it with another copy constructor,
    // cast true to 1 and copy only the string from the second character
    // on! We could use BALL_CREATE_NODEEP, but this leads to trouble with
    // inline constructors, so we code it by hand (here and in string.C)
    virtual void* create(bool /* deep */ = true, bool empty = false) const;
  

    enum CompareMode
    { 
      CASE_SENSITIVE   = 0, 

      CASE_INSENSITIVE = 1 
    };

    static const Size EndPos;



    static const char* CHARACTER_CLASS__ASCII_ALPHA;

    static const char* CHARACTER_CLASS__ASCII_ALPHANUMERIC;

    static const char* CHARACTER_CLASS__ASCII_LOWER;

    static const char* CHARACTER_CLASS__ASCII_UPPER;

    static const char* CHARACTER_CLASS__ASCII_NUMERIC;

    static const char* CHARACTER_CLASS__ASCII_FLOAT;

    static const char* CHARACTER_CLASS__WHITESPACE;

    static const char* CHARACTER_CLASS__QUOTES;



    String();

    String(const String& string);

    String(const string& string);

    String(const String& s, Index from, Size len = EndPos)
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);
  
    String(const char* char_ptr, Index from = 0, Size len = EndPos)
      throw(Exception::NullPointer, Exception::IndexUnderflow, Exception::IndexOverflow);

    String(Size buffer_size, const char* format, ... )
      throw(Exception::IndexUnderflow, Exception::NullPointer);

#ifdef BALL_HAS_SSTREAM
    String(std::stringstream& s);
#else
    String(std::strstream& s);
#endif

    String(const char c, Size len = 1);

    String(const unsigned char uc);

    String(short s);

    String(unsigned short us);

    String(int i);

    String(unsigned int ui);

    String(long l);

    String(unsigned long);

    String(float f);

    String(double d);

    virtual ~String();

    void destroy();

    virtual void clear();


    void set(const String& s);

    void set(const String& string, Index from, Size len = EndPos)
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);

    void set(const char* char_ptr, Index from = 0, Size len = EndPos)
      throw(Exception::NullPointer, Exception::IndexUnderflow, Exception::IndexOverflow);
  
    void set(Size buffer_size, const char *format, ...)
      throw(Exception::IndexUnderflow, Exception::NullPointer);

#ifdef BALL_HAS_SSTREAM
    void set(std::stringstream& s);
#else
    void set(std::strstream& s);
#endif

    void set(char c, Size len = 1);

    void set(unsigned char uc);

    void set(short s);

    void set(unsigned short us);

    void set(int i);

    void set(unsigned int ui);

    void set(long l);

    void set(unsigned long ul);

    void set(float f);

    void set(double d);

    void get(char* char_ptr, Index from = 0, Size len = EndPos) const
      throw(Exception::NullPointer, Exception::IndexUnderflow, Exception::IndexOverflow);

    const String& operator = (const String& s);

    const String& operator = (const char* pc)
      throw(Exception::NullPointer);

#ifdef BALL_HAS_SSTREAM
    const String& operator = (std::stringstream& s);
#else
    const String& operator = (std::strstream& s);
#endif

    const String& operator = (char c);

    const String& operator = (unsigned char uc);

    const String& operator = (short s);

    const String& operator = (unsigned short us);

    const String& operator = (int i);

    const String& operator = (unsigned int ui);

    const String& operator = (long l);

    const String& operator = (unsigned long ul);

    const String& operator = (float f);

    const String& operator = (double d);


    static void setCompareMode(CompareMode compare_mode);

    static CompareMode getCompareMode();


    bool toBool() const;

    char toChar() const;

    unsigned char toUnsignedChar() const;

    short toShort() const throw(Exception::InvalidFormat);

    unsigned short toUnsignedShort() const throw(Exception::InvalidFormat);

    int toInt() const throw(Exception::InvalidFormat);

    unsigned int toUnsignedInt() const throw(Exception::InvalidFormat);

    long toLong() const throw(Exception::InvalidFormat);

    unsigned long toUnsignedLong() const throw(Exception::InvalidFormat);

    float toFloat() const throw(Exception::InvalidFormat);

    double toDouble() const throw(Exception::InvalidFormat);



    void toLower(Index from = 0, Size len = EndPos)
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);
      
    void toUpper(Index from = 0, Size len = EndPos)
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);



    Substring getSubstring(Index from = 0, Size len = EndPos) const
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);

    Substring operator () (Index from, Size len = EndPos) const
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);

    Substring before(const String& s, Index from = 0) const;
 
    Substring through(const String& s, Index from = 0) const;
 
    Substring from(const String& s, Index from = 0) const;

    Substring after(const String& s, Index from = 0) const;



    Size countFields(const char* delimiters = CHARACTER_CLASS__WHITESPACE) const
      throw(Exception::NullPointer);

    Size countFieldsQuoted(const char* delimiters = CHARACTER_CLASS__WHITESPACE, 
                           const char* quotes = CHARACTER_CLASS__QUOTES) const
      throw(Exception::NullPointer);

    String getField(Index index, const char* delimiters = CHARACTER_CLASS__WHITESPACE, Index* from = 0) const
      throw(Exception::IndexUnderflow, Exception::NullPointer);

    String getFieldQuoted(Index index, const char* delimiters = CHARACTER_CLASS__WHITESPACE, 
                          const char* quotes = CHARACTER_CLASS__QUOTES, Index* from = 0) const
      throw(Exception::IndexUnderflow, Exception::NullPointer);

    Size split(String string_array[], Size array_size, const char* delimiters = CHARACTER_CLASS__WHITESPACE, Index from = 0) const
      throw(Exception::IndexUnderflow, Exception::NullPointer);

    Size split(std::vector<String>& strings, const char* delimiters = CHARACTER_CLASS__WHITESPACE, Index from = 0) const
      throw(Exception::IndexUnderflow, Exception::NullPointer);

    Size splitQuoted(std::vector<String>& strings, const char* delimiters = CHARACTER_CLASS__WHITESPACE, 
               const char* quotes = CHARACTER_CLASS__QUOTES, Index from = 0) const
      throw(Exception::IndexUnderflow, Exception::NullPointer);



    String& trimLeft(const char* trimmed = CHARACTER_CLASS__WHITESPACE);

    String& trimRight(const char* trimmed = CHARACTER_CLASS__WHITESPACE);

    String& trim(const char* trimmed = CHARACTER_CLASS__WHITESPACE);

    // ?????
    String trim(const char* trimmed = CHARACTER_CLASS__WHITESPACE) const;

    String& truncate(Size size);

    Substring left(Size len) const;

    Substring right(Size len) const;

    Substring instr(const String& pattern, Index from = 0) const;



    String operator + (const string& string) const;

    String operator + (const char* char_ptr) const;

    String operator + (char c) const;

    BALL_EXPORT
    friend String operator + (const char* char_ptr, const String& s);

    BALL_EXPORT
    friend String operator + (char c, const String& s);

    void swap(String& s);

    String& reverse(Index from = 0, Size len = EndPos)
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);

    Size substitute(const String& to_replace, const String& replacing);



    bool has(char c) const;

    bool hasSubstring(const String& s, Index from = 0) const;

    bool hasPrefix(const String& s) const;

    bool hasSuffix(const String& s) const;

    bool isEmpty() const;

    bool isAlpha() const;

    bool isAlnum() const;

    bool isDigit() const;

    bool isFloat() const;

    bool isSpace() const;

    bool isWhitespace() const;

    static bool isAlpha(char c);
  
    static bool isAlnum(char c);

    static bool isDigit(char c);

    static bool isSpace(char c);

    static bool isWhitespace(char c);
    

    
    String encodeBase64();

    String decodeBase64();
    


    int compare(const String& string, Index from = 0) const
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);

    int compare(const String& string, Index from, Size len) const
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);


    int compare(const char* char_ptr, Index from = 0) const
      throw(Exception::NullPointer, Exception::IndexUnderflow, Exception::IndexOverflow);

    int compare(const char* char_ptr, Index from, Size len) const
        throw(Exception::NullPointer, Exception::IndexUnderflow, Exception::IndexOverflow);

    int compare(char c, Index from = 0) const
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);

    bool operator == (const String& string) const;

    bool operator != (const String& string) const;

    bool operator < (const String& string) const;

    bool operator <= (const String& string) const;

    bool operator >= (const String& string) const;

    bool operator > (const String& string) const;

    BALL_EXPORT
    friend bool operator == (const char* char_ptr, const String& string)
      throw(Exception::NullPointer);

    BALL_EXPORT
    friend bool operator != (const char* char_ptr, const String& string)
      throw(Exception::NullPointer);

    BALL_EXPORT
    friend bool operator < (const char* char_ptr, const String& string)
      throw(Exception::NullPointer);

    BALL_EXPORT
    friend bool operator <= (const char* char_ptr, const String& string)
      throw(Exception::NullPointer);
    
    BALL_EXPORT
    friend bool operator > (const char* char_ptr, const String& string)
      throw(Exception::NullPointer);

    BALL_EXPORT
    friend bool operator >= (const char* char_ptr, const String& string)
      throw(Exception::NullPointer);

    bool operator == (const char* char_ptr) const
      throw(Exception::NullPointer);

    bool operator != (const char* char_ptr) const
      throw(Exception::NullPointer);

    bool operator < (const char* char_ptr) const
      throw(Exception::NullPointer);

    bool operator <= (const char* char_ptr) const
      throw(Exception::NullPointer);

    bool operator > (const char* char_ptr) const
      throw(Exception::NullPointer);

    bool operator >= (const char* char_ptr) const
      throw(Exception::NullPointer);

    BALL_EXPORT
    friend bool operator == (char c, const String& string);

    BALL_EXPORT
    friend bool operator != (char c, const String& string);

    BALL_EXPORT
    friend bool operator < (char c, const String& string);

    BALL_EXPORT
    friend bool operator <= (char c, const String& string);
    
    BALL_EXPORT
    friend bool operator > (char c, const String& string);

    friend bool operator >= (char c, const String& string);

    bool operator == (char c) const;

    bool operator != (char c) const;

    bool operator < (char c) const;

    bool operator <= (char c) const;

    bool operator > (char c) const;

    bool operator >= (char c) const;



    bool isValid() const;

    void dump(std::ostream& s = std::cout, Size depth = 0) const;



    std::istream& getline(std::istream& s = std::cin, char delimiter = '\n');

    friend std::istream& getline(std::istream& s,  String& string,  char delimiter = '\n');


    static const String EMPTY;

    protected:
  
    // the validate...  methods check perform a thorough
    // index checking and an index translation
    // Indices below zero are interpreted as indices
    // relative to the end of the string
    // All methods throw IndexUnder|Overflow exceptions
    //
    void validateIndex_(Index& index) const
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);
  
    void validateRange_(Index& from, Size& len) const
      throw(Exception::IndexUnderflow, Exception::IndexOverflow); 

    static void validateCharPtrRange_(Index& from, Size& len, const char* char_ptr)
      throw(Exception::NullPointer, Exception::IndexUnderflow, Exception::IndexOverflow);
    
    static void valudateCharPtrIndex_(Index& index);
    
    private:

    static int compareAscendingly_(const char* a,  const char* b);

    static int compareDescendingly_(const char* a,  const char* b);

    static CompareMode compare_mode_;

    static char B64Chars_[64];

    static int Index_64_[128];
  };

  class BALL_EXPORT Substring
  {
    friend class String;

    public:

    BALL_CREATE_DEEP(Substring)

    

    class BALL_EXPORT UnboundSubstring
      : public Exception::GeneralException
    {
      public:
      UnboundSubstring(const char* file, int line); 
    };

    class BALL_EXPORT InvalidSubstring
      : public Exception::GeneralException
    {
      public:
      InvalidSubstring(const char* file, int line); 
    };



    Substring();

    Substring(const Substring& substring, bool deep = true);

    Substring(const String& string, Index from = 0, Size len = String::EndPos)
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);

    virtual ~Substring();

    void destroy();

    virtual void clear();



    operator String() const
      throw(Substring::UnboundSubstring);

    String toString() const
      throw(Substring::UnboundSubstring);


    
    Substring& bind(const String& string, Index from = 0, Size len = String::EndPos)
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);

    Substring& bind(const Substring& substring, Index from = 0, Size len = String::EndPos)
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);

    void unbind();

    String* getBoundString();

    const String* getBoundString() const
;


  
    void set(const String& string)
      throw(Substring::UnboundSubstring);

    void set(const Substring& s)
      throw(Substring::UnboundSubstring);

    void set(const char* char_ptr, Size size = String::EndPos)
      throw(Substring::UnboundSubstring, Exception::NullPointer, Exception::SizeUnderflow);

    const Substring& operator = (const String& string)
      throw(Substring::UnboundSubstring);

    const Substring& operator = (const Substring& substring)
      throw(Substring::UnboundSubstring);

    const Substring& operator = (const char* char_ptr)
      throw(Substring::UnboundSubstring, Exception::NullPointer);


    
    char* c_str()
      throw(Substring::UnboundSubstring);

    const char* c_str() const
      throw(Substring::UnboundSubstring);

    Index getFirstIndex() const
      throw(Substring::UnboundSubstring);

    Index getLastIndex() const
      throw(Substring::UnboundSubstring);

    Size size() const;

    char& operator [] (Index index)
      throw(Substring::UnboundSubstring, Exception::IndexUnderflow, Exception::IndexOverflow);

    char operator [] (Index index) const
      throw(Substring::UnboundSubstring, Exception::IndexUnderflow, Exception::IndexOverflow);

    Substring& toLower()  
      throw(Substring::UnboundSubstring);

    Substring& toUpper()  
      throw(Substring::UnboundSubstring);
      


    bool isBound() const;
    
    bool isEmpty() const;



    bool operator == (const Substring& substring) const
      throw(Substring::UnboundSubstring);

    bool operator != (const Substring& substring) const
      throw(Substring::UnboundSubstring);

    bool operator == (const String& string) const
      throw(Substring::UnboundSubstring);

    bool operator != (const String& string) const
      throw(Substring::UnboundSubstring);

    BALL_EXPORT
    friend bool operator == (const String& string, const Substring& substring)
      throw(Substring::UnboundSubstring);

    BALL_EXPORT
    friend bool operator != (const String& string, const Substring& substring)
      throw(Substring::UnboundSubstring);

    bool operator == (const char* char_ptr) const
      throw(Substring::UnboundSubstring, Exception::NullPointer);

    bool operator != (const char* char_ptr) const
      throw(Substring::UnboundSubstring, Exception::NullPointer);

    bool operator == (char c) const
      throw(Substring::UnboundSubstring);

    bool operator != (char c) const
      throw(Substring::UnboundSubstring);



    BALL_EXPORT
    friend std::ostream& operator << (std::ostream& s, const Substring& substring);



    bool isValid() const;

    void dump(std::ostream& s = std::cout, Size depth = 0) const 
      throw(Substring::UnboundSubstring);

    
    protected:
      
    void validateRange_(Index& from, Size& len) const
      throw(Exception::IndexUnderflow, Exception::IndexOverflow);

    private:
    
    /*_ @name Attributes
    */
    //_@{

    //_ pointer to the bound String
    String*   bound_;

    //_ start index in the bound String
    Index     from_;

    //_ end index in the bound String
    Index     to_;
    //_@}
  };
  

# ifndef BALL_NO_INLINE_FUNCTIONS
#   include <BALL/DATATYPE/string.iC>
# endif
} // namespace BALL

#endif // BALL_DATATYPE_STRING_H