BALL: string.h Source File

00001 // -*- Mode: C++; tab-width: 2; -*-
00002 // vi: set ts=2:
00003 //
00004 // $Id: string.h,v 1.56 2005/12/23 17:01:43 amoll Exp $
00005 //
00006 
00007 #ifndef BALL_DATATYPE_STRING_H
00008 #define BALL_DATATYPE_STRING_H
00009 
00010 #ifndef BALL_CONFIG_CONFIG_H
00011 # include <BALL/CONFIG/config.h>
00012 #endif
00013 #ifndef BALL_COMMON_GLOBAL_H
00014 # include <BALL/COMMON/global.h>
00015 #endif
00016 #ifndef BALL_COMMON_CREATE_H
00017 # include <BALL/COMMON/create.h>
00018 #endif
00019 #ifndef BALL_COMMON_MACROS_H
00020 # include <BALL/COMMON/macros.h>
00021 #endif
00022 #ifndef BALL_COMMON_EXCEPTION_H
00023 # include <BALL/COMMON/exception.h>
00024 #endif
00025 #ifndef BALL_COMMON_DEBUG_H
00026 # include <BALL/COMMON/debug.h>
00027 #endif
00028 
00029 #include <string>
00030 #include <ctype.h>
00031 #include <errno.h>
00032 #include <stdlib.h>
00033 #include <string.h>
00034 #include <iostream>
00035 #include <vector>
00036 
00037 #ifdef BALL_HAS_SSTREAM
00038 # include <sstream>
00039 #else
00040 # include <strstream>
00041 #endif
00042 
00043 using std::string;
00044 
00045 class QString;
00046 class QByteArray;
00047 
00048 namespace BALL 
00049 {
00050   // forward declaration
00051   class Substring;
00052 
00059         
00063   class BALL_EXPORT String
00064     : public string
00065   {
00067     friend class Substring;
00068 
00069     public:
00070         
00071     // String has no copy constructor taking String&, bool as arguments.
00072     // the compiler would confuse it with another copy constructor,
00073     // cast true to 1 and copy only the string from the second character
00074     // on! We could use BALL_CREATE_NODEEP, but this leads to trouble with
00075     // inline constructors, so we code it by hand (here and in string.C)
00076     virtual void* create(bool /* deep */ = true, bool empty = false) const;
00077   
00080 
00088     enum CompareMode
00089     { 
00091       CASE_SENSITIVE   = 0, 
00092 
00094       CASE_INSENSITIVE = 1 
00095     };
00096 
00102     static const Size EndPos;
00103 
00105 
00111 
00113     static const char* CHARACTER_CLASS__ASCII_ALPHA;
00114 
00116     static const char* CHARACTER_CLASS__ASCII_ALPHANUMERIC;
00117 
00119     static const char* CHARACTER_CLASS__ASCII_LOWER;
00120 
00122     static const char* CHARACTER_CLASS__ASCII_UPPER;
00123 
00125     static const char* CHARACTER_CLASS__ASCII_NUMERIC;
00126 
00128     static const char* CHARACTER_CLASS__ASCII_FLOAT;
00129 
00141     static const char* CHARACTER_CLASS__WHITESPACE;
00142 
00145     static const char* CHARACTER_CLASS__QUOTES;
00146 
00148 
00151 
00153     String();
00154 
00156     String(const string& string);
00157 
00158 #ifdef BALL_STD_STRING_HAS_RVALUE_REFERENCES
00159 
00160     String(String&& s);
00161 
00163     String(string&& s);
00164 
00166     String& operator=(String&& s);
00167 
00169     String& operator=(string&& s);
00170 #endif
00171 
00173     explicit String(const QString& string);
00174 
00176     explicit String(const QByteArray& string);
00177 
00183     String(const String& s, Index from, Size len = EndPos)
00184       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
00185   
00192     String(const char* char_ptr, Index from = 0, Size len = EndPos)
00193       throw(Exception::NullPointer, Exception::IndexUnderflow, Exception::IndexOverflow);
00194 
00205     String(Size buffer_size, const char* format, ... )
00206       throw(Exception::IndexUnderflow, Exception::NullPointer);
00207 
00213 #ifdef BALL_HAS_SSTREAM
00214     String(std::stringstream& s);
00215 #else
00216     String(std::strstream& s);
00217 #endif
00218 
00221     String(const char c, Size len = 1);
00222 
00224     String(const unsigned char uc);
00225 
00227     String(short s);
00228 
00230     String(unsigned short us);
00231 
00233     String(int i);
00234 
00236     String(unsigned int ui);
00237 
00239     String(long l);
00240 
00242     String(unsigned long);
00243 
00245     String(float f);
00246 
00248     String(double d);
00249 
00251     virtual ~String();
00252 
00254     void destroy();
00255 
00257     virtual void clear();
00259 
00263 
00265     void set(const String& s);
00266 
00271     void set(const String& string, Index from, Size len = EndPos)
00272       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
00273 
00278     void set(const char* char_ptr, Index from = 0, Size len = EndPos)
00279       throw(Exception::NullPointer, Exception::IndexUnderflow, Exception::IndexOverflow);
00280   
00285     void set(Size buffer_size, const char *format, ...)
00286       throw(Exception::IndexUnderflow, Exception::NullPointer);
00287 
00291 #ifdef BALL_HAS_SSTREAM
00292     void set(std::stringstream& s);
00293 #else
00294     void set(std::strstream& s);
00295 #endif
00296 
00298     void set(char c, Size len = 1);
00299 
00301     void set(unsigned char uc);
00302 
00304     void set(short s);
00305 
00307     void set(unsigned short us);
00308 
00310     void set(int i);
00311 
00313     void set(unsigned int ui);
00314 
00316     void set(long l);
00317 
00319     void set(unsigned long ul);
00320 
00322     void set(float f);
00323 
00325     void set(double d);
00326 
00328     void get(char* char_ptr, Index from = 0, Size len = EndPos) const
00329       throw(Exception::NullPointer, Exception::IndexUnderflow, Exception::IndexOverflow);
00330 
00332     const String& operator = (const String& s);
00333 
00335     const String& operator = (const char* pc)
00336       throw(Exception::NullPointer);
00337 
00341 #ifdef BALL_HAS_SSTREAM
00342     const String& operator = (std::stringstream& s);
00343 #else
00344     const String& operator = (std::strstream& s);
00345 #endif
00346 
00348     const String& operator = (char c);
00349 
00351     const String& operator = (unsigned char uc);
00352 
00354     const String& operator = (short s);
00355 
00357     const String& operator = (unsigned short us);
00358 
00360     const String& operator = (int i);
00361 
00363     const String& operator = (unsigned int ui);
00364 
00366     const String& operator = (long l);
00367 
00369     const String& operator = (unsigned long ul);
00370 
00372     const String& operator = (float f);
00373 
00375     const String& operator = (double d);
00377 
00384 
00385     static void setCompareMode(CompareMode compare_mode);
00386 
00388     static CompareMode getCompareMode();
00390 
00394 
00399     bool toBool() const;
00400 
00402     char toChar() const;
00403 
00405     unsigned char toUnsignedChar() const;
00406 
00408     short toShort() const throw(Exception::InvalidFormat);
00409 
00411     unsigned short toUnsignedShort() const throw(Exception::InvalidFormat);
00412 
00414     int toInt() const throw(Exception::InvalidFormat);
00415 
00417     unsigned int toUnsignedInt() const throw(Exception::InvalidFormat);
00418 
00420     long toLong() const throw(Exception::InvalidFormat);
00421 
00423     unsigned long toUnsignedLong() const throw(Exception::InvalidFormat);
00424 
00426     float toFloat() const throw(Exception::InvalidFormat);
00427 
00429     double toDouble() const throw(Exception::InvalidFormat);
00431 
00432 
00436 
00438     void toLower(Index from = 0, Size len = EndPos)
00439       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
00440       
00442     void toUpper(Index from = 0, Size len = EndPos)
00443       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
00444 
00446 
00449 
00451     Substring getSubstring(Index from = 0, Size len = EndPos) const
00452       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
00453 
00455     Substring operator () (Index from, Size len = EndPos) const
00456       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
00457 
00460     Substring before(const String& s, Index from = 0) const;
00461  
00464     Substring through(const String& s, Index from = 0) const;
00465  
00468     Substring from(const String& s, Index from = 0) const;
00469 
00472     Substring after(const String& s, Index from = 0) const;
00473 
00475 
00478 
00480     Size countFields(const char* delimiters = CHARACTER_CLASS__WHITESPACE) const
00481       throw(Exception::NullPointer);
00482 
00484     Size countFieldsQuoted(const char* delimiters = CHARACTER_CLASS__WHITESPACE, 
00485                            const char* quotes = CHARACTER_CLASS__QUOTES) const
00486       throw(Exception::NullPointer);
00487 
00489     String getField(Index index, const char* delimiters = CHARACTER_CLASS__WHITESPACE, Index* from = 0) const
00490       throw(Exception::IndexUnderflow, Exception::NullPointer);
00491 
00493     String getFieldQuoted(Index index, const char* delimiters = CHARACTER_CLASS__WHITESPACE, 
00494                           const char* quotes = CHARACTER_CLASS__QUOTES, Index* from = 0) const
00495       throw(Exception::IndexUnderflow, Exception::NullPointer);
00496 
00499     Size split(String string_array[], Size array_size, const char* delimiters = CHARACTER_CLASS__WHITESPACE, Index from = 0) const
00500       throw(Exception::IndexUnderflow, Exception::NullPointer);
00501 
00507     Size split(std::vector<String>& strings, const char* delimiters = CHARACTER_CLASS__WHITESPACE, Index from = 0) const
00508       throw(Exception::IndexUnderflow, Exception::NullPointer);
00509 
00517     Size splitQuoted(std::vector<String>& strings, const char* delimiters = CHARACTER_CLASS__WHITESPACE, 
00518                const char* quotes = CHARACTER_CLASS__QUOTES, Index from = 0) const
00519       throw(Exception::IndexUnderflow, Exception::NullPointer);
00520 
00522 
00525 
00532     String& trimLeft(const char* trimmed = CHARACTER_CLASS__WHITESPACE);
00533 
00540     String& trimRight(const char* trimmed = CHARACTER_CLASS__WHITESPACE);
00541 
00545     String& trim(const char* trimmed = CHARACTER_CLASS__WHITESPACE);
00546 
00547     // ?????
00551     String trim(const char* trimmed = CHARACTER_CLASS__WHITESPACE) const;
00552 
00554     String& truncate(Size size);
00555 
00557     Substring left(Size len) const;
00558 
00560     Substring right(Size len) const;
00561 
00570     Substring instr(const String& pattern, Index from = 0) const;
00571 
00573 
00576     
00577     // NOTE: please, please, pretty please, only try to optimize away operator+ definitions
00578     //       if you *really* know what you are doing. We didn't, and we definitely don't want
00579     //       to touch this stinking heap of C++ garbage ever again!
00580     //       (dstoeckel & anhi)
00582     BALL_EXPORT
00583     friend String operator + (const String& s1, const string& s2);
00584     
00586     BALL_EXPORT
00587     friend String operator + (const string& s1, const String& s2);
00588 
00590     BALL_EXPORT
00591     friend String operator + (const String& s1, const String& s2);
00592     
00594     BALL_EXPORT
00595     friend String operator + (const String& s1, const char* char_ptr);
00596 
00598     BALL_EXPORT
00599     friend String operator + (const char* char_ptr, const String& s);
00600 
00602     BALL_EXPORT
00603     friend String operator + (const String& s, char c);
00604     
00606     BALL_EXPORT
00607     friend String operator + (char c, const String& s);
00608 
00609 #ifdef BALL_STD_STRING_HAS_RVALUE_REFERENCES
00610 
00611     BALL_EXPORT
00612     friend String operator + (String&& s1, const string& s2);
00613   
00615     BALL_EXPORT
00616     friend String operator + (String&& s1, const String& s2);
00617   
00619     BALL_EXPORT
00620     friend String operator + (String&& s1, String&& s2);
00621 
00622     BALL_EXPORT
00623     friend String operator + (const String& s1, string&& s2);
00624 
00625     BALL_EXPORT
00626     friend String operator + (string&& s1, const String& s2);
00627 
00628     BALL_EXPORT
00629     friend String operator + (const string& s1, String&& s2);
00630 
00632     BALL_EXPORT
00633     friend String operator + (const String& s1, String&& s2);
00634 
00636     BALL_EXPORT
00637     friend String operator + (String&& s1, const char* char_ptr);
00638 
00640     BALL_EXPORT
00641     friend String operator + (const char* char_ptr, String&& s);
00642 
00644     BALL_EXPORT
00645     friend String operator + (String&& s, char c);
00646     
00648     BALL_EXPORT
00649     friend String operator + (char c, String&& s);
00650 #endif
00651 
00653     void swap(String& s);
00654 
00662     String& reverse(Index from = 0, Size len = EndPos)
00663       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
00664 
00668     Size substitute(const String& to_replace, const String& replacing);
00669 
00671 
00675 
00677     bool has(char c) const;
00678 
00680     bool hasSubstring(const String& s, Index from = 0) const;
00681 
00683     bool hasPrefix(const String& s) const;
00684 
00686     bool hasSuffix(const String& s) const;
00687 
00689     bool isEmpty() const;
00690 
00694     bool isAlpha() const;
00695 
00699     bool isAlnum() const;
00700 
00704     bool isDigit() const;
00705 
00710     bool isFloat() const;
00711 
00715     bool isSpace() const;
00716 
00721     bool isWhitespace() const;
00722 
00724     static bool isAlpha(char c);
00725   
00727     static bool isAlnum(char c);
00728 
00730     static bool isDigit(char c);
00731 
00733     static bool isSpace(char c);
00734 
00738     static bool isWhitespace(char c);
00739     
00741 
00744     
00746     String encodeBase64();
00747 
00751     String decodeBase64();
00752     
00754 
00757 
00759     int compare(const String& string, Index from = 0) const
00760       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
00761 
00763     int compare(const String& string, Index from, Size len) const
00764       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
00765 
00766 
00768     int compare(const char* char_ptr, Index from = 0) const
00769       throw(Exception::NullPointer, Exception::IndexUnderflow, Exception::IndexOverflow);
00770 
00772     int compare(const char* char_ptr, Index from, Size len) const
00773         throw(Exception::NullPointer, Exception::IndexUnderflow, Exception::IndexOverflow);
00774 
00776     int compare(char c, Index from = 0) const
00777       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
00778 
00780     bool operator == (const String& string) const;
00781 
00783     bool operator != (const String& string) const;
00784 
00786     bool operator < (const String& string) const;
00787 
00789     bool operator <= (const String& string) const;
00790 
00792     bool operator >= (const String& string) const;
00793 
00795     bool operator > (const String& string) const;
00796 
00798     BALL_EXPORT
00799     friend bool operator == (const char* char_ptr, const String& string)
00800       throw(Exception::NullPointer);
00801 
00803     BALL_EXPORT
00804     friend bool operator != (const char* char_ptr, const String& string)
00805       throw(Exception::NullPointer);
00806 
00808     BALL_EXPORT
00809     friend bool operator < (const char* char_ptr, const String& string)
00810       throw(Exception::NullPointer);
00811 
00813     BALL_EXPORT
00814     friend bool operator <= (const char* char_ptr, const String& string)
00815       throw(Exception::NullPointer);
00816     
00818     BALL_EXPORT
00819     friend bool operator > (const char* char_ptr, const String& string)
00820       throw(Exception::NullPointer);
00821 
00823     BALL_EXPORT
00824     friend bool operator >= (const char* char_ptr, const String& string)
00825       throw(Exception::NullPointer);
00826 
00828     bool operator == (const char* char_ptr) const
00829       throw(Exception::NullPointer);
00830 
00832     bool operator != (const char* char_ptr) const
00833       throw(Exception::NullPointer);
00834 
00836     bool operator < (const char* char_ptr) const
00837       throw(Exception::NullPointer);
00838 
00840     bool operator <= (const char* char_ptr) const
00841       throw(Exception::NullPointer);
00842 
00844     bool operator > (const char* char_ptr) const
00845       throw(Exception::NullPointer);
00846 
00848     bool operator >= (const char* char_ptr) const
00849       throw(Exception::NullPointer);
00850 
00852     BALL_EXPORT
00853     friend bool operator == (char c, const String& string);
00854 
00856     BALL_EXPORT
00857     friend bool operator != (char c, const String& string);
00858 
00860     BALL_EXPORT
00861     friend bool operator < (char c, const String& string);
00862 
00864     BALL_EXPORT
00865     friend bool operator <= (char c, const String& string);
00866     
00868     BALL_EXPORT
00869     friend bool operator > (char c, const String& string);
00870 
00872     friend bool operator >= (char c, const String& string);
00873 
00875     bool operator == (char c) const;
00876 
00878     bool operator != (char c) const;
00879 
00881     bool operator < (char c) const;
00882 
00884     bool operator <= (char c) const;
00885 
00887     bool operator > (char c) const;
00888 
00890     bool operator >= (char c) const;
00891 
00893 
00896 
00898     bool isValid() const;
00899 
00901     void dump(std::ostream& s = std::cout, Size depth = 0) const;
00902 
00904 
00907 
00909     std::istream& getline(std::istream& s = std::cin, char delimiter = '\n');
00910 
00912     BALL_EXPORT
00913     friend std::istream& getline(std::istream& s,  String& string,  char delimiter = '\n');
00914 
00916 
00918     static const String EMPTY;
00919 
00920     protected:
00921   
00922     // the validate...  methods check perform a thorough
00923     // index checking and an index translation
00924     // Indices below zero are interpreted as indices
00925     // relative to the end of the string
00926     // All methods throw IndexUnder|Overflow exceptions
00927     //
00928     void validateIndex_(Index& index) const
00929       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
00930   
00931     void validateRange_(Index& from, Size& len) const
00932       throw(Exception::IndexUnderflow, Exception::IndexOverflow); 
00933 
00934     static void validateCharPtrRange_(Index& from, Size& len, const char* char_ptr)
00935       throw(Exception::NullPointer, Exception::IndexUnderflow, Exception::IndexOverflow);
00936     
00937     static void valudateCharPtrIndex_(Index& index);
00938     
00939     private:
00940 
00941     static int compareAscendingly_(const char* a,  const char* b);
00942 
00943     static int compareDescendingly_(const char* a,  const char* b);
00944 
00945     static CompareMode compare_mode_;
00946 
00947     static char B64Chars_[64];
00948 
00949     static int Index_64_[128];
00950   };
00951 
00960   class BALL_EXPORT Substring
00961   {
00962     friend class String;
00963 
00964     public:
00965 
00966     BALL_CREATE_DEEP(Substring)
00967 
00968     
00971 
00976     class BALL_EXPORT UnboundSubstring
00977       : public Exception::GeneralException
00978     {
00979       public:
00980       UnboundSubstring(const char* file, int line); 
00981     };
00982 
00988     class BALL_EXPORT InvalidSubstring
00989       : public Exception::GeneralException
00990     {
00991       public:
00992       InvalidSubstring(const char* file, int line); 
00993     };
00994 
00996 
00999 
01003     Substring();
01004 
01010     Substring(const Substring& substring, bool deep = true);
01011 
01017     Substring(const String& string, Index from = 0, Size len = String::EndPos)
01018       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
01019 
01023     virtual ~Substring();
01024 
01029     void destroy();
01030 
01035     virtual void clear();
01036 
01038 
01041 
01045     operator String() const
01046       throw(Substring::UnboundSubstring);
01047 
01051     String toString() const
01052       throw(Substring::UnboundSubstring);
01053 
01055 
01058     
01064     Substring& bind(const String& string, Index from = 0, Size len = String::EndPos)
01065       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
01066 
01070     Substring& bind(const Substring& substring, Index from = 0, Size len = String::EndPos)
01071       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
01072 
01074     void unbind();
01075 
01077     String* getBoundString();
01078 
01080     const String* getBoundString() const
01081 ;
01082 
01084 
01087   
01090     void set(const String& string)
01091       throw(Substring::UnboundSubstring);
01092 
01095     void set(const Substring& s)
01096       throw(Substring::UnboundSubstring);
01097 
01099     void set(const char* char_ptr, Size size = String::EndPos)
01100       throw(Substring::UnboundSubstring, Exception::NullPointer, Exception::SizeUnderflow);
01101 
01103     const Substring& operator = (const String& string)
01104       throw(Substring::UnboundSubstring);
01105 
01107     const Substring& operator = (const Substring& substring)
01108       throw(Substring::UnboundSubstring);
01109 
01111     const Substring& operator = (const char* char_ptr)
01112       throw(Substring::UnboundSubstring, Exception::NullPointer);
01113 
01115 
01118     
01120     char* c_str()
01121       throw(Substring::UnboundSubstring);
01122 
01124     const char* c_str() const
01125       throw(Substring::UnboundSubstring);
01126 
01130     Index getFirstIndex() const
01131       throw(Substring::UnboundSubstring);
01132 
01136     Index getLastIndex() const
01137       throw(Substring::UnboundSubstring);
01138 
01140     Size size() const;
01141 
01143     char& operator [] (Index index)
01144       throw(Substring::UnboundSubstring, Exception::IndexUnderflow, Exception::IndexOverflow);
01145 
01147     char operator [] (Index index) const
01148       throw(Substring::UnboundSubstring, Exception::IndexUnderflow, Exception::IndexOverflow);
01149 
01151     Substring& toLower()  
01152       throw(Substring::UnboundSubstring);
01153 
01155     Substring& toUpper()  
01156       throw(Substring::UnboundSubstring);
01157       
01159 
01162 
01164     bool isBound() const;
01165     
01167     bool isEmpty() const;
01168 
01170 
01173 
01175     bool operator == (const Substring& substring) const
01176       throw(Substring::UnboundSubstring);
01177 
01179     bool operator != (const Substring& substring) const
01180       throw(Substring::UnboundSubstring);
01181 
01183     bool operator == (const String& string) const
01184       throw(Substring::UnboundSubstring);
01185 
01187     bool operator != (const String& string) const
01188       throw(Substring::UnboundSubstring);
01189 
01191     BALL_EXPORT
01192     friend bool operator == (const String& string, const Substring& substring)
01193       throw(Substring::UnboundSubstring);
01194 
01196     BALL_EXPORT
01197     friend bool operator != (const String& string, const Substring& substring)
01198       throw(Substring::UnboundSubstring);
01199 
01201     bool operator == (const char* char_ptr) const
01202       throw(Substring::UnboundSubstring, Exception::NullPointer);
01203 
01205     bool operator != (const char* char_ptr) const
01206       throw(Substring::UnboundSubstring, Exception::NullPointer);
01207 
01209     bool operator == (char c) const
01210       throw(Substring::UnboundSubstring);
01211 
01213     bool operator != (char c) const
01214       throw(Substring::UnboundSubstring);
01215 
01217 
01220 
01222     BALL_EXPORT
01223     friend std::ostream& operator << (std::ostream& s, const Substring& substring);
01224 
01226 
01229 
01234     bool isValid() const;
01235 
01237     void dump(std::ostream& s = std::cout, Size depth = 0) const 
01238       throw(Substring::UnboundSubstring);
01239 
01241     
01242     protected:
01243       
01244     void validateRange_(Index& from, Size& len) const
01245       throw(Exception::IndexUnderflow, Exception::IndexOverflow);
01246 
01247     private:
01248     
01249     /*_ @name Attributes
01250     */
01251     //_@{
01252 
01253     //_ pointer to the bound String
01254     String*   bound_;
01255 
01256     //_ start index in the bound String
01257     Index     from_;
01258 
01259     //_ end index in the bound String
01260     Index     to_;
01261     //_@}
01262   };
01263   
01265 
01266 # ifndef BALL_NO_INLINE_FUNCTIONS
01267 #   include <BALL/DATATYPE/string.iC>
01268 # endif
01269 } // namespace BALL
01270 
01271 #endif // BALL_DATATYPE_STRING_H