BALL  1.4.79
string.h
Go to the documentation of this file.
1 // -*- Mode: C++; tab-width: 2; -*-
2 // vi: set ts=2:
3 //
4 
5 #ifndef BALL_DATATYPE_STRING_H
6 #define BALL_DATATYPE_STRING_H
7 
8 #ifndef BALL_CONFIG_CONFIG_H
9 # include <BALL/CONFIG/config.h>
10 #endif
11 #ifndef BALL_COMMON_GLOBAL_H
12 # include <BALL/COMMON/global.h>
13 #endif
14 #ifndef BALL_COMMON_CREATE_H
15 # include <BALL/COMMON/create.h>
16 #endif
17 #ifndef BALL_COMMON_MACROS_H
18 # include <BALL/COMMON/macros.h>
19 #endif
20 #ifndef BALL_COMMON_EXCEPTION_H
21 # include <BALL/COMMON/exception.h>
22 #endif
23 #ifndef BALL_COMMON_DEBUG_H
24 # include <BALL/COMMON/debug.h>
25 #endif
26 
27 #include <string>
28 #include <cctype>
29 #include <cerrno>
30 #include <cstdlib>
31 #include <cstring>
32 #include <iostream>
33 #include <vector>
34 
35 #ifdef BALL_HAS_SSTREAM
36 # include <sstream>
37 #else
38 # include <strstream>
39 #endif
40 
41 using std::string;
42 
43 class QString;
44 class QByteArray;
45 
46 namespace BALL
47 {
48  // forward declaration
49  class Substring;
50  class String;
52  std::istream& getline(std::istream& s, String& string, char delimiter = '\n');
53 
60 
65  : public string
66  {
68  friend class Substring;
69 
70  public:
71 
72  // String has no copy constructor taking String&, bool as arguments.
73  // the compiler would confuse it with another copy constructor,
74  // cast true to 1 and copy only the string from the second character
75  // on! We could use BALL_CREATE_NODEEP, but this leads to trouble with
76  // inline constructors, so we code it by hand (here and in string.C)
77  virtual void* create(bool /* deep */ = true, bool empty = false) const;
78 
81 
90  {
92  CASE_SENSITIVE = 0,
93 
95  CASE_INSENSITIVE = 1
96  };
97 
103  static const Size EndPos;
104 
106 
112 
114  static const char* CHARACTER_CLASS__ASCII_ALPHA;
115 
118 
120  static const char* CHARACTER_CLASS__ASCII_LOWER;
121 
123  static const char* CHARACTER_CLASS__ASCII_UPPER;
124 
126  static const char* CHARACTER_CLASS__ASCII_NUMERIC;
127 
129  static const char* CHARACTER_CLASS__ASCII_FLOAT;
130 
142  static const char* CHARACTER_CLASS__WHITESPACE;
143 
146  static const char* CHARACTER_CLASS__QUOTES;
147 
149 
152 
154  String();
155 
157  String(const string& string);
158 
160  String(const String& s);
161 
162 #ifdef BALL_STD_STRING_HAS_RVALUE_REFERENCES
163  String(String&& s);
165 
167  String(string&& s);
168 
170  String& operator=(String&& s);
171 
173  String& operator=(string&& s);
174 #endif
175 
177  explicit String(const QString& string);
178 
180  explicit String(const QByteArray& string);
181 
187  String(const String& s, Index from, Size len = EndPos);
188 
198  String(const char* char_ptr, Index from = 0, Size len = EndPos);
199 
210  String(Size buffer_size, const char* format, ... );
211 
217 #ifdef BALL_HAS_SSTREAM
218  String(std::stringstream& s);
219 #else
220  String(std::strstream& s);
221 #endif
222 
225  String(const char c, Size len = 1);
226 
228  String(const unsigned char uc);
229 
231  String(short s);
232 
234  String(unsigned short us);
235 
237  String(int i);
238 
240  String(unsigned int ui);
241 
243  String(long l);
244 
246  String(unsigned long);
247 
248 #ifdef BALL_ALLOW_LONG64_TYPE_OVERLOADS
249  String(LongIndex l);
251 
253  String(LongSize);
254 #endif
255 
257  String(float f);
258 
260  String(double d);
261 
263  virtual ~String();
264 
266  void destroy();
267 
269  virtual void clear();
271 
275 
277  void set(const String& s);
278 
283  void set(const String& string, Index from, Size len = EndPos);
284 
290  void set(const char* char_ptr, Index from = 0, Size len = EndPos);
291 
296  void set(Size buffer_size, const char *format, ...);
297 
301 #ifdef BALL_HAS_SSTREAM
302  void set(std::stringstream& s);
303 #else
304  void set(std::strstream& s);
305 #endif
306 
308  void set(char c, Size len = 1);
309 
311  void set(unsigned char uc);
312 
314  void set(short s);
315 
317  void set(unsigned short us);
318 
320  void set(int i);
321 
323  void set(unsigned int ui);
324 
326  void set(long l);
327 
329  void set(unsigned long ul);
330 
331 #ifdef BALL_ALLOW_LONG64_TYPE_OVERLOADS
332  void set(LongIndex l);
334 
336  void set(LongSize ul);
337 #endif
338 
340  void set(float f);
341 
343  void set(double d);
344 
354  void get(char* char_ptr, Index from = 0, Size len = EndPos) const;
355 
357  const String& operator = (const String& s);
358 
362  const String& operator = (const char* pc);
363 
367 #ifdef BALL_HAS_SSTREAM
368  const String& operator = (std::stringstream& s);
369 #else
370  const String& operator = (std::strstream& s);
371 #endif
372 
374  const String& operator = (char c);
375 
377  const String& operator = (unsigned char uc);
378 
380  const String& operator = (short s);
381 
383  const String& operator = (unsigned short us);
384 
386  const String& operator = (int i);
387 
389  const String& operator = (unsigned int ui);
390 
392  const String& operator = (long l);
393 
395  const String& operator = (unsigned long ul);
396 
397 #ifdef BALL_ALLOW_LONG64_TYPE_OVERLOADS
398  const String& operator = (LongIndex l);
400 
402  const String& operator = (LongSize ul);
403 #endif
404 
406  const String& operator = (float f);
407 
409  const String& operator = (double d);
411 
418  static void setCompareMode(CompareMode compare_mode);
420 
422  static CompareMode getCompareMode();
424 
428 
433  bool toBool() const;
434 
436  char toChar() const;
437 
439  unsigned char toUnsignedChar() const;
440 
444  short toShort() const;
445 
449  unsigned short toUnsignedShort() const;
450 
454  int toInt() const;
455 
459  unsigned int toUnsignedInt() const;
460 
464  long toLong() const;
465 
469  unsigned long toUnsignedLong() const;
470 
474  float toFloat() const;
475 
479  double toDouble() const;
481 
482 
486 
491  void toLower(Index from = 0, Size len = EndPos);
492 
497  void toUpper(Index from = 0, Size len = EndPos);
498 
500 
503 
508  Substring getSubstring(Index from = 0, Size len = EndPos) const;
509 
514  Substring operator () (Index from, Size len = EndPos) const;
515 
518  Substring before(const String& s, Index from = 0) const;
519 
522  Substring through(const String& s, Index from = 0) const;
523 
526  Substring from(const String& s, Index from = 0) const;
527 
530  Substring after(const String& s, Index from = 0) const;
531 
533 
536 
540  Size countFields(const char* delimiters = CHARACTER_CLASS__WHITESPACE) const;
541 
545  Size countFieldsQuoted(const char* delimiters = CHARACTER_CLASS__WHITESPACE,
546  const char* quotes = CHARACTER_CLASS__QUOTES) const;
547 
552  String getField(Index index, const char* delimiters = CHARACTER_CLASS__WHITESPACE, Index* from = 0) const;
553 
558  String getFieldQuoted(Index index, const char* delimiters = CHARACTER_CLASS__WHITESPACE,
559  const char* quotes = CHARACTER_CLASS__QUOTES, Index* from = 0) const;
560 
565  Size split(String string_array[], Size array_size, const char* delimiters = CHARACTER_CLASS__WHITESPACE, Index from = 0) const;
566 
572  Size split(std::vector<String>& strings, const char* delimiters = CHARACTER_CLASS__WHITESPACE, Index from = 0) const;
573 
581  Size splitQuoted(std::vector<String>& strings, const char* delimiters = CHARACTER_CLASS__WHITESPACE,
582  const char* quotes = CHARACTER_CLASS__QUOTES, Index from = 0) const;
583 
585 
588 
595  String& trimLeft(const char* trimmed = CHARACTER_CLASS__WHITESPACE);
596 
603  String& trimRight(const char* trimmed = CHARACTER_CLASS__WHITESPACE);
604 
608  String& trim(const char* trimmed = CHARACTER_CLASS__WHITESPACE);
609 
610  // ?????
614  String trim(const char* trimmed = CHARACTER_CLASS__WHITESPACE) const;
615 
617  String& truncate(Size size);
618 
620  Substring left(Size len) const;
621 
623  Substring right(Size len) const;
624 
633  Substring instr(const String& pattern, Index from = 0) const;
634 
636 
639 
640  // NOTE: please, please, pretty please, only try to optimize away operator+ definitions
641  // if you *really* know what you are doing. We didn't, and we definitely don't want
642  // to touch this stinking heap of C++ garbage ever again!
643  // (dstoeckel & anhi)
646  friend String operator + (const String& s1, const string& s2);
647 
650  friend String operator + (const string& s1, const String& s2);
651 
654  friend String operator + (const String& s1, const String& s2);
655 
658  friend String operator + (const String& s1, const char* char_ptr);
659 
662  friend String operator + (const char* char_ptr, const String& s);
663 
666  friend String operator + (const String& s, char c);
667 
670  friend String operator + (char c, const String& s);
671 
672 #ifdef BALL_STD_STRING_HAS_RVALUE_REFERENCES
675  friend String operator + (String&& s1, const string& s2);
676 
679  friend String operator + (String&& s1, const String& s2);
680 
683  friend String operator + (String&& s1, String&& s2);
684 
686  friend String operator + (const String& s1, string&& s2);
687 
689  friend String operator + (string&& s1, const String& s2);
690 
692  friend String operator + (const string& s1, String&& s2);
693 
696  friend String operator + (const String& s1, String&& s2);
697 
700  friend String operator + (String&& s1, const char* char_ptr);
701 
704  friend String operator + (const char* char_ptr, String&& s);
705 
708  friend String operator + (String&& s, char c);
709 
712  friend String operator + (char c, String&& s);
713 #endif
714 
716  void swap(String& s);
717 
727  String& reverse(Index from = 0, Size len = EndPos);
728 
732  Size substitute(const String& to_replace, const String& replacing);
733 
735  void substituteAll(const String& to_replace, const String& replacing);
736 
738 
742 
744  bool has(char c) const;
745 
747  bool hasSubstring(const String& s, Index from = 0) const;
748 
750  bool hasPrefix(const String& s) const;
751 
753  bool hasSuffix(const String& s) const;
754 
756  bool isEmpty() const;
757 
761  bool isAlpha() const;
762 
766  bool isAlnum() const;
767 
771  bool isDigit() const;
772 
777  bool isFloat() const;
778 
782  bool isSpace() const;
783 
788  bool isWhitespace() const;
789 
791  static bool isAlpha(char c);
792 
794  static bool isAlnum(char c);
795 
797  static bool isDigit(char c);
798 
800  static bool isSpace(char c);
801 
805  static bool isWhitespace(char c);
806 
808 
811 
813  String encodeBase64();
814 
818  String decodeBase64();
819 
821 
824 
829  int compare(const String& string, Index from = 0) const;
830 
835  int compare(const String& string, Index from, Size len) const;
836 
837 
843  int compare(const char* char_ptr, Index from = 0) const;
844 
850  int compare(const char* char_ptr, Index from, Size len) const;
851 
856  int compare(char c, Index from = 0) const;
857 
859  bool operator == (const String& string) const;
860 
862  bool operator != (const String& string) const;
863 
865  bool operator < (const String& string) const;
866 
868  bool operator <= (const String& string) const;
869 
871  bool operator >= (const String& string) const;
872 
874  bool operator > (const String& string) const;
875 
880  friend bool operator == (const char* char_ptr, const String& string);
881 
886  friend bool operator != (const char* char_ptr, const String& string);
887 
892  friend bool operator < (const char* char_ptr, const String& string);
893 
898  friend bool operator <= (const char* char_ptr, const String& string);
899 
904  friend bool operator > (const char* char_ptr, const String& string);
905 
910  friend bool operator >= (const char* char_ptr, const String& string);
911 
915  bool operator == (const char* char_ptr) const;
916 
920  bool operator != (const char* char_ptr) const;
921 
925  bool operator < (const char* char_ptr) const;
926 
930  bool operator <= (const char* char_ptr) const;
931 
935  bool operator > (const char* char_ptr) const;
936 
940  bool operator >= (const char* char_ptr) const;
941 
944  friend bool operator == (char c, const String& string);
945 
948  friend bool operator != (char c, const String& string);
949 
952  friend bool operator < (char c, const String& string);
953 
956  friend bool operator <= (char c, const String& string);
957 
960  friend bool operator > (char c, const String& string);
961 
963  friend bool operator >= (char c, const String& string);
964 
966  bool operator == (char c) const;
967 
969  bool operator != (char c) const;
970 
972  bool operator < (char c) const;
973 
975  bool operator <= (char c) const;
976 
978  bool operator > (char c) const;
979 
981  bool operator >= (char c) const;
982 
984 
987 
989  bool isValid() const;
990 
992  void dump(std::ostream& s = std::cout, Size depth = 0) const;
993 
995 
998 
1000  std::istream& getline(std::istream& s = std::cin, char delimiter = '\n');
1001 
1003  BALL_EXPORT
1004  friend std::istream& getline(std::istream& s, String& string, char delimiter);
1005 
1007 
1009  static const String EMPTY;
1010 
1011  protected:
1012 
1013  // the validate... methods check perform a thorough
1014  // index checking and an index translation
1015  // Indices below zero are interpreted as indices
1016  // relative to the end of the string
1017  // All methods throw IndexUnder|Overflow exceptions
1018  //
1019  void validateIndex_(Index& index) const;
1020 
1021  void validateRange_(Index& from, Size& len) const;
1022 
1023  static void validateCharPtrRange_(Index& from, Size& len, const char* char_ptr);
1024 
1025  static void valudateCharPtrIndex_(Index& index);
1026 
1027  private:
1028 
1029  static int compareAscendingly_(const char* a, const char* b);
1030 
1031  static int compareDescendingly_(const char* a, const char* b);
1032 
1033  static CompareMode compare_mode_;
1034 
1035  static char B64Chars_[64];
1036 
1037  static int Index_64_[128];
1038  };
1039 
1049  {
1050  friend class String;
1051 
1052  public:
1053 
1055 
1056 
1059 
1065  : public Exception::GeneralException
1066  {
1067  public:
1068  UnboundSubstring(const char* file, int line);
1069  };
1070 
1078  {
1079  public:
1080  InvalidSubstring(const char* file, int line);
1081  };
1082 
1084 
1087 
1091  Substring();
1092 
1098  Substring(const Substring& substring, bool deep = true);
1099 
1107  Substring(const String& string, Index from = 0, Size len = String::EndPos);
1108 
1112  virtual ~Substring();
1113 
1118  void destroy();
1119 
1124  virtual void clear();
1125 
1127 
1130 
1135  operator String() const;
1136 
1141  String toString() const;
1142 
1144 
1147 
1156  Substring& bind(const String& string, Index from = 0, Size len = String::EndPos);
1157 
1163  Substring& bind(const Substring& substring, Index from = 0, Size len = String::EndPos);
1164 
1166  void unbind();
1167 
1169  String* getBoundString();
1170 
1172  const String* getBoundString() const
1173 ;
1174 
1176 
1179 
1183  void set(const String& string);
1184 
1188  void set(const Substring& s);
1189 
1195  void set(const char* char_ptr, Size size = String::EndPos);
1196 
1200  const Substring& operator = (const String& string);
1201 
1205  const Substring& operator = (const Substring& substring);
1206 
1211  const Substring& operator = (const char* char_ptr);
1212 
1214 
1217 
1221  char* c_str();
1222 
1226  const char* c_str() const;
1227 
1232  Index getFirstIndex() const;
1233 
1238  Index getLastIndex() const;
1239 
1241  Size size() const;
1242 
1248  char& operator [] (Index index);
1249 
1255  char operator [] (Index index) const;
1256 
1260  Substring& toLower();
1261 
1265  Substring& toUpper();
1266 
1268 
1271 
1273  bool isBound() const;
1274 
1276  bool isEmpty() const;
1277 
1279 
1282 
1286  bool operator == (const Substring& substring) const;
1287 
1291  bool operator != (const Substring& substring) const;
1292 
1296  bool operator == (const String& string) const;
1297 
1301  bool operator != (const String& string) const;
1302 
1306  BALL_EXPORT
1307  friend bool operator == (const String& string, const Substring& substring);
1308 
1312  BALL_EXPORT
1313  friend bool operator != (const String& string, const Substring& substring);
1314 
1319  bool operator == (const char* char_ptr) const;
1320 
1325  bool operator != (const char* char_ptr) const;
1326 
1330  bool operator == (char c) const;
1331 
1335  bool operator != (char c) const;
1336 
1338 
1341 
1343  BALL_EXPORT
1344  friend std::ostream& operator << (std::ostream& s, const Substring& substring);
1345 
1347 
1350 
1355  bool isValid() const;
1356 
1360  void dump(std::ostream& s = std::cout, Size depth = 0) const;
1361 
1363 
1364  protected:
1365 
1366  // throws IndexUnderflow|IndexOverflow
1367  void validateRange_(Index& from, Size& len) const;
1368 
1369  private:
1370 
1371  /*_ @name Attributes
1372  */
1373  //_@{
1374 
1375  //_ pointer to the bound String
1376  String* bound_;
1377 
1378  //_ start index in the bound String
1379  Index from_;
1380 
1381  //_ end index in the bound String
1382  Index to_;
1383  //_@}
1384  };
1385 
1387 
1388 # ifndef BALL_NO_INLINE_FUNCTIONS
1389 # include <BALL/DATATYPE/string.iC>
1390 # endif
1391 } // namespace BALL
1392 
1393 #endif // BALL_DATATYPE_STRING_H
static const char * CHARACTER_CLASS__ASCII_UPPER
Character class containing all upper case letters.
Definition: string.h:123
static const char * CHARACTER_CLASS__ASCII_FLOAT
Character class containing the digits from 0 to 9 and a dot.
Definition: string.h:129
BALL_EXPORT std::ostream & operator<<(std::ostream &os, const Exception::GeneralException &e)
BALL_EXTERN_VARIABLE const double c
Definition: constants.h:149
static const char * CHARACTER_CLASS__ASCII_ALPHA
Character class containing all letters (lower and upper case)
Definition: string.h:114
static const String EMPTY
Constant empty string.
Definition: string.h:1009
#define BALL_CREATE_DEEP(name)
Definition: create.h:26
static const Size EndPos
Definition: string.h:103
BALL_ULONG64_TYPE LongSize
BALL_LONG64_TYPE LongIndex
static const char * CHARACTER_CLASS__WHITESPACE
Definition: string.h:142
static const char * CHARACTER_CLASS__QUOTES
Definition: string.h:146
-*- Mode: C++; tab-width: 2; -*-
Definition: constants.h:12
BALL_EXPORT std::istream & getline(std::istream &s, String &string, char delimiter= '\n')
static const char * CHARACTER_CLASS__ASCII_ALPHANUMERIC
Character class containing all letters and digits.
Definition: string.h:117
ConstRandomAccessIterator< Container, DataType, Position, Traits > operator+(Distance distance, const ConstRandomAccessIterator< Container, DataType, Position, Traits > &iterator)
static const char * CHARACTER_CLASS__ASCII_LOWER
Character class containing all lower case letters.
Definition: string.h:120
static const char * CHARACTER_CLASS__ASCII_NUMERIC
Character class containing the digits from 0 to 9.
Definition: string.h:126
#define BALL_EXPORT
Definition: COMMON/global.h:50
Index compare(const T1 &a, const T2 &b)
Definition: MATHS/common.h:314