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 <cctype>
#include <cerrno>
#include <cstdlib>
#include <cstring>
#include <iostream>
#include <vector>

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

using std::string;

class QString;
class QByteArray;

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& s);

#ifdef BALL_STD_STRING_HAS_RVALUE_REFERENCES

    String(String&& s);

    String(string&& s);

    String& operator=(String&& s);

    String& operator=(string&& s);
#endif

    explicit String(const QString& string);

    explicit String(const QByteArray& string);

    String(const String& s, Index from, Size len = EndPos);
  
    String(const char* char_ptr, Index from = 0, Size len = EndPos);

    String(Size buffer_size, const char* format, ... );

#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);

#ifdef BALL_ALLOW_LONG64_TYPE_OVERLOADS

    String(LongIndex l);

    String(LongSize);
#endif

    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);

    void set(const char* char_ptr, Index from = 0, Size len = EndPos);
  
    void set(Size buffer_size, const char *format, ...);

#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);

#ifdef BALL_ALLOW_LONG64_TYPE_OVERLOADS

    void set(LongIndex l);

    void set(LongSize ul);
#endif

    void set(float f);

    void set(double d);

    void get(char* char_ptr, Index from = 0, Size len = EndPos) const;

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

    const String& operator = (const char* pc);

#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);

#ifdef BALL_ALLOW_LONG64_TYPE_OVERLOADS

    const String& operator = (LongIndex l);

    const String& operator = (LongSize ul);
#endif

    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;

    unsigned short toUnsignedShort() const;

    int toInt() const;

    unsigned int toUnsignedInt() const;

    long toLong() const;

    unsigned long toUnsignedLong() const;

    float toFloat() const;

    double toDouble() const;



    void toLower(Index from = 0, Size len = EndPos);
      
    void toUpper(Index from = 0, Size len = EndPos);



    Substring getSubstring(Index from = 0, Size len = EndPos) const;

    Substring operator () (Index from, Size len = EndPos) const;

    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;

    Size countFieldsQuoted(const char* delimiters = CHARACTER_CLASS__WHITESPACE, 
                           const char* quotes = CHARACTER_CLASS__QUOTES) const;

    String getField(Index index, const char* delimiters = CHARACTER_CLASS__WHITESPACE, Index* from = 0) const;

    String getFieldQuoted(Index index, const char* delimiters = CHARACTER_CLASS__WHITESPACE, 
                          const char* quotes = CHARACTER_CLASS__QUOTES, Index* from = 0) const;

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

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

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



    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;


    
    // NOTE: please, please, pretty please, only try to optimize away operator+ definitions
    //       if you *really* know what you are doing. We didn't, and we definitely don't want
    //       to touch this stinking heap of C++ garbage ever again!
    //       (dstoeckel & anhi)
    BALL_EXPORT
    friend String operator + (const String& s1, const string& s2);
    
    BALL_EXPORT
    friend String operator + (const string& s1, const String& s2);

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

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

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

#ifdef BALL_STD_STRING_HAS_RVALUE_REFERENCES

    BALL_EXPORT
    friend String operator + (String&& s1, const string& s2);
  
    BALL_EXPORT
    friend String operator + (String&& s1, const String& s2);
  
    BALL_EXPORT
    friend String operator + (String&& s1, String&& s2);

    BALL_EXPORT
    friend String operator + (const String& s1, string&& s2);

    BALL_EXPORT
    friend String operator + (string&& s1, const String& s2);

    BALL_EXPORT
    friend String operator + (const string& s1, String&& s2);

    BALL_EXPORT
    friend String operator + (const String& s1, String&& s2);

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

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

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

    void swap(String& s);

    String& reverse(Index from = 0, Size len = EndPos);

    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;

    int compare(const String& string, Index from, Size len) const;


    int compare(const char* char_ptr, Index from = 0) const;

    int compare(const char* char_ptr, Index from, Size len) const;

    int compare(char c, Index from = 0) 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;

    bool operator > (const String& string) const;

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

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

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

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

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

    bool operator == (const char* char_ptr) const;

    bool operator != (const char* char_ptr) const;

    bool operator < (const char* char_ptr) const;

    bool operator <= (const char* char_ptr) const;

    bool operator > (const char* char_ptr) const;

    bool operator >= (const char* char_ptr) const;

    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');

    BALL_EXPORT
    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;
  
    void validateRange_(Index& from, Size& len) const; 

    static void validateCharPtrRange_(Index& from, Size& len, const char* char_ptr);
    
    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);

    virtual ~Substring();

    void destroy();

    virtual void clear();



    operator String() const;

    String toString() const;


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

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

    void unbind();

    String* getBoundString();

    const String* getBoundString() const
;


  
    void set(const String& string);

    void set(const Substring& s);

    void set(const char* char_ptr, Size size = String::EndPos);

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

    const Substring& operator = (const Substring& substring);

    const Substring& operator = (const char* char_ptr);


    
    char* c_str();

    const char* c_str() const;

    Index getFirstIndex() const;

    Index getLastIndex() const;

    Size size() const;

    char& operator [] (Index index);

    char operator [] (Index index) const;

    Substring& toLower();

    Substring& toUpper();
      


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



    bool operator == (const Substring& substring) const;

    bool operator != (const Substring& substring) const;

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

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

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

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

    bool operator == (const char* char_ptr) const;

    bool operator != (const char* char_ptr) const;

    bool operator == (char c) const;

    bool operator != (char c) const;



    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;

    
    protected:
      
    // throws IndexUnderflow|IndexOverflow
    void validateRange_(Index& from, Size& len) const;

    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