1 // -*- Mode: C++; tab-width: 2; -*- 2 // vi: set ts=2: 3 // 4 // $Id: string.h,v 1.56 2005/12/23 17:01:43 amoll Exp $ 5 // 6 7 #ifndef BALL_DATATYPE_STRING_H 8 #define BALL_DATATYPE_STRING_H 9 10 #ifndef BALL_CONFIG_CONFIG_H 11 # include <BALL/CONFIG/config.h> 12 #endif 13 #ifndef BALL_COMMON_GLOBAL_H 14 # include <BALL/COMMON/global.h> 15 #endif 16 #ifndef BALL_COMMON_CREATE_H 17 # include <BALL/COMMON/create.h> 18 #endif 19 #ifndef BALL_COMMON_MACROS_H 20 # include <BALL/COMMON/macros.h> 21 #endif 22 #ifndef BALL_COMMON_EXCEPTION_H 23 # include <BALL/COMMON/exception.h> 24 #endif 25 #ifndef BALL_COMMON_DEBUG_H 26 # include <BALL/COMMON/debug.h> 27 #endif 28 29 #include <string> 30 #include <cctype> 31 #include <cerrno> 32 #include <cstdlib> 33 #include <cstring> 34 #include <iostream> 35 #include <vector> 36 37 #ifdef BALL_HAS_SSTREAM 38 # include <sstream> 39 #else 40 # include <strstream> 41 #endif 42 43 using std::string; 44 45 class QString; 46 class QByteArray; 47 48 namespace BALL 49 { 50 // forward declaration 51 class Substring; 52 53 /** \defgroup String String 54 An improved version of STL string. 55 56 \ingroup DatatypeMiscellaneous 57 */ 58 //@{ 59 60 /** Extended String class. 61 \ingroup String 62 */ 63 class BALL_EXPORT String 64 : public string 65 { 66 /// 67 friend class Substring; 68 69 public: 70 71 // String has no copy constructor taking String&, bool as arguments. 72 // the compiler would confuse it with another copy constructor, 73 // cast true to 1 and copy only the string from the second character 74 // on! We could use BALL_CREATE_NODEEP, but this leads to trouble with 75 // inline constructors, so we code it by hand (here and in string.C) 76 virtual void* create(bool /* deep */ = true, bool empty = false) const; 77 78 /** @name Enums and Constants */ 79 //@{ 80 81 /** Constants to set the compare mode. 82 Use one of these constants to set the mode you need. 83 These modes affect all \link compare compare \endlink methods. As these 84 methods are also used in the implementation of comparison operators, 85 all comparison operations will get affected from a change. \par 86 You may change the comparison mode by invoking setCompareMode. \par 87 */ 88 enum CompareMode 89 { 90 /// Constant to set to case sensitive comparisons (default) 91 CASE_SENSITIVE = 0, 92 93 /// Constant to set to case insensitive comparisons 94 CASE_INSENSITIVE = 1 95 }; 96 97 /** Constant indicating the end of the string. 98 Use this constant instead of <tt>string::npos</tt> to indicate an invalid 99 position inside the string or the end of the string in those methods 100 requiring indices. 101 */ 102 static const Size EndPos; 103 104 //@} 105 /** @name Predefined character classes 106 There exist several predefined character classes, that may 107 be used in several functions (e.g. trim methods) to represent 108 a set of characters. 109 */ 110 //@{ 111 112 /// Character class containing all letters (lower and upper case) 113 static const char* CHARACTER_CLASS__ASCII_ALPHA; 114 115 /// Character class containing all letters and digits 116 static const char* CHARACTER_CLASS__ASCII_ALPHANUMERIC; 117 118 /// Character class containing all lower case letters 119 static const char* CHARACTER_CLASS__ASCII_LOWER; 120 121 /// Character class containing all upper case letters 122 static const char* CHARACTER_CLASS__ASCII_UPPER; 123 124 /// Character class containing the digits from 0 to 9 125 static const char* CHARACTER_CLASS__ASCII_NUMERIC; 126 127 /// Character class containing the digits from 0 to 9 and a dot 128 static const char* CHARACTER_CLASS__ASCII_FLOAT; 129 130 /** Character class containing all whitespace characters. 131 Whitespace characters are: \par 132 133 - blank " " 134 - horizontal tab $ "\backslash t" $ 135 - new-line $ "\backslash n" $ 136 - line-feed $ "\backslash r" $ 137 - vertical tab $ "\backslash v" $ 138 - form-feed $ "\backslash f" $ 139 140 */ 141 static const char* CHARACTER_CLASS__WHITESPACE; 142 143 /** Character class containing double quotes. 144 */ 145 static const char* CHARACTER_CLASS__QUOTES; 146 147 //@} 148 /** @name Constructors and Destructors 149 */ 150 //@{ 151 152 /// Default Constructor 153 String(); 154 155 /// STL string copy constructor 156 String(const string& string); 157 158 /// Copy constructor 159 String(const String& s); 160 161 #ifdef BALL_STD_STRING_HAS_RVALUE_REFERENCES 162 /// Move constructor 163 String(String&& s); 164 165 /// Move constructor for STL string 166 String(string&& s); 167 168 /// Move assigment operator 169 String& operator=(String&& s); 170 171 /// Move assignment operator for STL string 172 String& operator=(string&& s); 173 #endif 174 175 /// QString copy constructor 176 explicit String(const QString& string); 177 178 /// QByteArray copy constructor 179 explicit String(const QByteArray& string); 180 181 /** Creates a new string from a given range of another string. 182 @see String:Indices 183 @exception Exception::IndexUnderflow if <tt>from < 0</tt> 184 @exception Exception::IndexOverflow if <tt>from >= size()</tt> 185 */ 186 String(const String& s, Index from, Size len = EndPos); 187 188 /** Creates a new string from a C type string. 189 The new string contains the contents of <b>s</b> until 190 it has reached a length of <b>len</b> or contains a zero character 191 (whichever comes first). Default value for <b>len</b> is <b>EndPos</b>, 192 meaning as long as possible. 193 @exception Exception::IndexUnderflow if <tt>from < 0</tt> 194 @exception Exception::IndexOverflow if <tt>from >= size()</tt> 195 @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 196 */ 197 String(const char* char_ptr, Index from = 0, Size len = EndPos); 198 199 /** Creates a string using <b>sprintf</b>. 200 This constructor creates a new string and sets its content 201 to the result of a call to <b>sprintf</b> using <b>format</b> as a 202 format string and all additional parameters as arguments. \par 203 The result of the sprintf call is intermediately written to a buffer 204 of a maximum size of <b>buffer_size</b> characters, so choose an 205 appropriate size for this variables. \par 206 @exception IndexUnderflow, if the buffer size specified is not larger than 0 207 @exception NullPointer, if <tt>format == 0</tt> 208 */ 209 String(Size buffer_size, const char* format, ... ); 210 211 /** Create a new string from the contents of a <b>stringstream</b>. 212 The contents of the <tt>stringstream</tt> are not modified, i.e. 213 successive construction of multiple strings from the same <tt>stringstream</tt> 214 object leads to identical copies. 215 */ 216 #ifdef BALL_HAS_SSTREAM 217 String(std::stringstream& s); 218 #else 219 String(std::strstream& s); 220 #endif 221 222 /** Creates a new string from len copies of c. 223 */ 224 String(const char c, Size len = 1); 225 226 /// Creates a string just containing an unsigned character 227 String(const unsigned char uc); 228 229 /// Construct a String from a short 230 String(short s); 231 232 /// Construct a String from an unsigned short 233 String(unsigned short us); 234 235 /// Construct a String from an int 236 String(int i); 237 238 /// Construct a String from an unsigned int 239 String(unsigned int ui); 240 241 /// Construct a String from a long 242 String(long l); 243 244 /// Construct a String from an unsigned long 245 String(unsigned long); 246 247 #ifdef BALL_ALLOW_LONG64_TYPE_OVERLOADS 248 /// Construct a String from a signed 64 bit integer 249 String(LongIndex l); 250 251 /// Construct a String from an unsigned 64 bit integer 252 String(LongSize); 253 #endif 254 255 /// Construct a String from a float value 256 String(float f); 257 258 /// Construct a String from a double value 259 String(double d); 260 261 /// Destructor 262 virtual ~String(); 263 264 /// Clear the string (reset to the empty string) 265 void destroy(); 266 267 /// Clears the string (same as destroy) 268 virtual void clear(); 269 //@} 270 271 /** @name Assignment methods 272 */ 273 //@{ 274 275 /** Assign a string */ 276 void set(const String& s); 277 278 /** Assign a String from a range of another string 279 @exception Exception::IndexOverflow if <tt>from < 0</tt> 280 @exception Exception::IndexUnderflow if <tt>from >= size()</tt> 281 */ 282 void set(const String& string, Index from, Size len = EndPos); 283 284 /** Assign a String from a C type string 285 @exception Exception::IndexUnderflow if <tt>from < 0</tt> 286 @exception Exception::IndexOverflow if <tt>from >= size()</tt> 287 @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 288 */ 289 void set(const char* char_ptr, Index from = 0, Size len = EndPos); 290 291 /** Assign a string to the result of a <b>sprintf</b> call 292 @exception Exception::IndexUnderflow, if the buffer size is zero 293 @exception Exception::NullPointer, <tt>format</tt> is a NULL pointer 294 */ 295 void set(Size buffer_size, const char *format, ...); 296 297 /** Assign a String from a <b>stringstream</b>. 298 The contents of the <tt>stringstream</tt> object are not modified. 299 */ 300 #ifdef BALL_HAS_SSTREAM 301 void set(std::stringstream& s); 302 #else 303 void set(std::strstream& s); 304 #endif 305 306 /// Assign a String from the result of repeating <b>c</b> <b>len</b> times 307 void set(char c, Size len = 1); 308 309 /// Assign a String from an unsigned char 310 void set(unsigned char uc); 311 312 /// Assign a String from a short 313 void set(short s); 314 315 /// Assign a String from an unsigned short 316 void set(unsigned short us); 317 318 /// Assign a String from an int 319 void set(int i); 320 321 /// Assign a String from an unsigned int 322 void set(unsigned int ui); 323 324 /// Assign a String from a long 325 void set(long l); 326 327 /// Assign a String from an unsigned long 328 void set(unsigned long ul); 329 330 #ifdef BALL_ALLOW_LONG64_TYPE_OVERLOADS 331 /// Assign a String from a 64 bit integer 332 void set(LongIndex l); 333 334 /// Assign a String from an unsigned 64 bit integer 335 void set(LongSize ul); 336 #endif 337 338 /// Assign a String from a float value 339 void set(float f); 340 341 /// Assign a String from a double value 342 void set(double d); 343 344 /** Assign to a C type string 345 The resulting string contains the contents of <b>this</b> until 346 it has reached a length of <b>len</b> or contains a zero character 347 (whichever comes first). Default value for <b>len</b> is <b>EndPos</b>, 348 meaning as long as possible. 349 @exception Exception::IndexUnderflow if <tt>from < 0</tt> 350 @exception Exception::IndexOverflow if <tt>from >= size()</tt> 351 @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 352 */ 353 void get(char* char_ptr, Index from = 0, Size len = EndPos) const; 354 355 /// Assign a String from another String 356 const String& operator = (const String& s); 357 358 /** Assign a String from a C type string 359 @exception Exception::NullPointer if <tt>pc == NULL</tt> 360 */ 361 const String& operator = (const char* pc); 362 363 /** Assign a string from a <b>stringstream</b>. 364 The contents of the <tt>stringstream</tt> object are not modified. 365 */ 366 #ifdef BALL_HAS_SSTREAM 367 const String& operator = (std::stringstream& s); 368 #else 369 const String& operator = (std::strstream& s); 370 #endif 371 372 /// Assign a String from a single char 373 const String& operator = (char c); 374 375 /// Assign a String from an unsigned char 376 const String& operator = (unsigned char uc); 377 378 /// Assign a String from a short 379 const String& operator = (short s); 380 381 /// Assign a String from an unsigned short 382 const String& operator = (unsigned short us); 383 384 /// Assign a String from an int 385 const String& operator = (int i); 386 387 /// Assign a String from an unsigned int 388 const String& operator = (unsigned int ui); 389 390 /// Assign a String from a long 391 const String& operator = (long l); 392 393 /// Assign a String from an unsigned long 394 const String& operator = (unsigned long ul); 395 396 #ifdef BALL_ALLOW_LONG64_TYPE_OVERLOADS 397 /// Assign a String from a 64 bit integer 398 const String& operator = (LongIndex l); 399 400 /// Assign a String from an unsigned 64 bit integer 401 const String& operator = (LongSize ul); 402 #endif 403 404 /// Assign a String from a float 405 const String& operator = (float f); 406 407 /// Assign a String from a double 408 const String& operator = (double d); 409 //@} 410 411 /** @name Compare mode-related methods. 412 All string comparisons can be made case-sensitive or 413 case insensitive. The behavior can be toggled globally 414 for all strings. 415 */ 416 //@{ 417 /// Set the compareison mode for all string comparisons 418 static void setCompareMode(CompareMode compare_mode); 419 420 /// Return the current comparison mode 421 static CompareMode getCompareMode(); 422 //@} 423 424 /** @name Converters 425 */ 426 //@{ 427 428 /** Converts the string to a bool value. 429 This method returns <b>false</b>, if the string contains the string <tt>false</tt> 430 (may be surrounded by whitespaces), or <b>true</b> otherwise. 431 */ 432 bool toBool() const; 433 434 /// Return the first character of the string 435 char toChar() const; 436 437 /// Return the first character of the string converted to an unsigned char 438 unsigned char toUnsignedChar() const; 439 440 /** Convert the string to a short 441 * @exception Exception::InvalidFormat 442 */ 443 short toShort() const; 444 445 /** Convert the string to an unsigned short 446 * @exception Exception::InvalidFormat 447 */ 448 unsigned short toUnsignedShort() const; 449 450 /** Convert the string to an int 451 * @exception Exception::InvalidFormat 452 */ 453 int toInt() const; 454 455 /** Convert the string to an unsigned int 456 * @exception Exception::InvalidFormat 457 */ 458 unsigned int toUnsignedInt() const; 459 460 /** Convert the string to a long 461 * @exception Exception::InvalidFormat 462 */ 463 long toLong() const; 464 465 /** Convert the string to an unsigned long 466 * @exception Exception::InvalidFormat 467 */ 468 unsigned long toUnsignedLong() const; 469 470 /** Convert the string to a float 471 * @exception Exception::InvalidFormat 472 */ 473 float toFloat() const; 474 475 /** Convert the string to a double 476 * @exception Exception::InvalidFormat 477 */ 478 double toDouble() const; 479 //@} 480 481 482 /** @name Case Conversion 483 */ 484 //@{ 485 486 /** Convert all characters in the given range to lower case 487 * @exception Exception::IndexUnderflow if <tt>from < 0</tt> 488 * @exception Exception::IndexOverflow if <tt>from || len >= size()</tt> 489 */ 490 void toLower(Index from = 0, Size len = EndPos); 491 492 /** Convert all characters in the given range to upper case 493 * @exception Exception::IndexUnderflow if <tt>from < 0</tt> 494 * @exception Exception::IndexOverflow if <tt>from || len >= size()</tt> 495 */ 496 void toUpper(Index from = 0, Size len = EndPos); 497 498 //@} 499 /** @name Substring Definition 500 */ 501 //@{ 502 503 /** Return a substring 504 * @exception Exception::IndexUnderflow if <tt>from < 0</tt> 505 * @exception Exception::IndexOverflow if <tt>from >= size()</tt> 506 */ 507 Substring getSubstring(Index from = 0, Size len = EndPos) const; 508 509 /** Return a substring 510 * @exception Exception::IndexUnderflow if <tt>from < 0</tt> 511 * @exception Exception::IndexOverflow if <tt>from >= size()</tt> 512 */ 513 Substring operator () (Index from, Size len = EndPos) const; 514 515 /** Return a substring containing the string before the first occurence of <b>s</b> 516 */ 517 Substring before(const String& s, Index from = 0) const; 518 519 /** Return a substring containing the beginning of the string including the first occurence of <b>s</b> 520 */ 521 Substring through(const String& s, Index from = 0) const; 522 523 /** Return a substring containing the string from the first occurence of <b>s</b> on 524 */ 525 Substring from(const String& s, Index from = 0) const; 526 527 /** Return a substring containing the string after the first occurence of <b>s</b>. 528 */ 529 Substring after(const String& s, Index from = 0) const; 530 531 //@} 532 /** @name AWK style field operations 533 */ 534 //@{ 535 536 /** Count the fields that are separated by a defined set of delimiters 537 * @exception Exception::NullPointer if <tt>delimiters == NULL</tt> 538 */ 539 Size countFields(const char* delimiters = CHARACTER_CLASS__WHITESPACE) const; 540 541 /** Count the fields and respect quote characters. 542 * @exception Exception::NullPointer if <tt>delimiters == NULL</tt> or <tt>quotes == NULL</tt> 543 */ 544 Size countFieldsQuoted(const char* delimiters = CHARACTER_CLASS__WHITESPACE, 545 const char* quotes = CHARACTER_CLASS__QUOTES) const; 546 547 /** Return a given field as a substring 548 * @exception Exception::IndexUnderflow if <tt>from < 0</tt> 549 * @exception Exception::NullPointer if <tt>delimiters == NULL</tt> 550 */ 551 String getField(Index index, const char* delimiters = CHARACTER_CLASS__WHITESPACE, Index* from = 0) const; 552 553 /** Return a given field and respect quote characters. 554 * @exception Exception::IndexUnderflow if <tt>from < 0</tt> 555 * @exception Exception::NullPointer if <tt>delimiters == NULL</tt> 556 */ 557 String getFieldQuoted(Index index, const char* delimiters = CHARACTER_CLASS__WHITESPACE, 558 const char* quotes = CHARACTER_CLASS__QUOTES, Index* from = 0) const; 559 560 /** Split the string into fields and assign these field to an array of strings 561 * @exception Exception::IndexUnderflow if <tt>from < 0</tt> 562 * @exception Exception::NullPointer if <tt>delimiters == NULL</tt> 563 */ 564 Size split(String string_array[], Size array_size, const char* delimiters = CHARACTER_CLASS__WHITESPACE, Index from = 0) const; 565 566 /** Split the string into fields and assign these field to a vector of strings. 567 The vector of strings is cleared in any case. Its final size is returned. 568 @exception IndexOverflow if <tt>from < 0</tt> 569 @exception NullPointer if <tt>delimiters == 0</tt> 570 */ 571 Size split(std::vector<String>& strings, const char* delimiters = CHARACTER_CLASS__WHITESPACE, Index from = 0) const; 572 573 /** Split the string into fields and respect quote characters. 574 Similar to \link split split \endlink , but delimiters that are inside quote characters (default is \link CHARACTER_CLASS__QUOTES CHARACTER_CLASS__QUOTES \endlink ) 575 are not considered to split the string. 576 The vector of strings is cleared in any case. Its final size is returned. 577 @exception IndexOverflow if <tt>from < 0</tt> 578 @exception NullPointer if <tt>delimiters == 0</tt> 579 */ 580 Size splitQuoted(std::vector<String>& strings, const char* delimiters = CHARACTER_CLASS__WHITESPACE, 581 const char* quotes = CHARACTER_CLASS__QUOTES, Index from = 0) const; 582 583 //@} 584 /** @name BASIC style string operations 585 */ 586 //@{ 587 588 /** Strips all characters in <b>trimmed</b> from the left of the string. 589 trimLeft stops at the first character encountered that is not in <b>trimmed</b>. 590 Using its default parameter CHARACTER_CLASS__WHITESPACE, it is usually handy to 591 remove blanks from the beginning of a string. 592 Strings consisting of character from <tt>trimmed</tt> only yield an empty string. 593 */ 594 String& trimLeft(const char* trimmed = CHARACTER_CLASS__WHITESPACE); 595 596 /** Strips all characters in <b>trimmed</b> from the right of the string. 597 trimRight stops at the first character encountered that is not in <b>trimmed</b>. 598 Using its default parameter CHARACTER_CLASS__WHITESPACE, it is usually handy to 599 remove blanks from the end of a string. 600 Strings consisting of character from <tt>trimmed</tt> only yield an empty string. 601 */ 602 String& trimRight(const char* trimmed = CHARACTER_CLASS__WHITESPACE); 603 604 /** Strips all characters in <b>trimmed</b> from both sides of the string. 605 trim calls <tt>trimRight(trimmed).trimLeft(trimmed)</tt>. 606 */ 607 String& trim(const char* trimmed = CHARACTER_CLASS__WHITESPACE); 608 609 // ????? 610 /** Strips all characters in <b>trimmed</b> from both sides of the string. 611 trim calls <tt>trimRight(trimmed).trimLeft(trimmed)</tt>. 612 */ 613 String trim(const char* trimmed = CHARACTER_CLASS__WHITESPACE) const; 614 615 /// Truncate the string to length <b>size</b> 616 String& truncate(Size size); 617 618 /// Return a substring containing the <b>len</b> leftmost characters of the string 619 Substring left(Size len) const; 620 621 /// Return a substring containing the <b>len</b> rightmost characters of the string 622 Substring right(Size len) const; 623 624 /** Return a substring containing the first occurence of <b>pattern</b> in the string. 625 If the pattern is not contained in the string, an empty Substring is returned. 626 The search for the pattern may also start from an index different from zero, allowing 627 incremental search. 628 @return Substring containing the search pattern, empty if not found 629 @param pattern the search pattern 630 @param from the index in the string to start the search from 631 */ 632 Substring instr(const String& pattern, Index from = 0) const; 633 634 //@} 635 /** @name String Operations 636 */ 637 //@{ 638 639 // NOTE: please, please, pretty please, only try to optimize away operator+ definitions 640 // if you *really* know what you are doing. We didn't, and we definitely don't want 641 // to touch this stinking heap of C++ garbage ever again! 642 // (dstoeckel & anhi) 643 /// Concatenates two strings 644 BALL_EXPORT 645 friend String operator + (const String& s1, const string& s2); 646 647 /// Concatenates two strings 648 BALL_EXPORT 649 friend String operator + (const string& s1, const String& s2); 650 651 /// Concatenates two strings 652 BALL_EXPORT 653 friend String operator + (const String& s1, const String& s2); 654 655 /// Concatenates a string and a C type string 656 BALL_EXPORT 657 friend String operator + (const String& s1, const char* char_ptr); 658 659 /// Concatenates a C type string and a string 660 BALL_EXPORT 661 friend String operator + (const char* char_ptr, const String& s); 662 663 /// Concatenates a string and a character 664 BALL_EXPORT 665 friend String operator + (const String& s, char c); 666 667 /// Concatenates a character and a string 668 BALL_EXPORT 669 friend String operator + (char c, const String& s); 670 671 #ifdef BALL_STD_STRING_HAS_RVALUE_REFERENCES 672 /// Concatenates two strings 673 BALL_EXPORT 674 friend String operator + (String&& s1, const string& s2); 675 676 /// Concatenates two strings 677 BALL_EXPORT 678 friend String operator + (String&& s1, const String& s2); 679 680 /// Concatenates two strings 681 BALL_EXPORT 682 friend String operator + (String&& s1, String&& s2); 683 684 BALL_EXPORT 685 friend String operator + (const String& s1, string&& s2); 686 687 BALL_EXPORT 688 friend String operator + (string&& s1, const String& s2); 689 690 BALL_EXPORT 691 friend String operator + (const string& s1, String&& s2); 692 693 /// Concatenates two strings 694 BALL_EXPORT 695 friend String operator + (const String& s1, String&& s2); 696 697 /// Concatenates a string and a C type string 698 BALL_EXPORT 699 friend String operator + (String&& s1, const char* char_ptr); 700 701 /// Concatenates a C type string and a string 702 BALL_EXPORT 703 friend String operator + (const char* char_ptr, String&& s); 704 705 /// Concatenates a string and a character 706 BALL_EXPORT 707 friend String operator + (String&& s, char c); 708 709 /// Concatenates a character and a string 710 BALL_EXPORT 711 friend String operator + (char c, String&& s); 712 #endif 713 714 /// Swaps the contents with another String 715 void swap(String& s); 716 717 /** Reverses the string. 718 If called without arguments, this method simply reverses the character sequence of the string. 719 By giving arguments for the indices, only a subsequence of the string may be reversed. 720 @param from first index of the sequence to be reversed 721 @param to last index of the sequence to be reversed 722 @see String:Indices 723 @exception Exception::IndexUnderflow if <tt>from < 0</tt> 724 @exception Exception::IndexOverflow if <tt>from >= size()</tt> 725 */ 726 String& reverse(Index from = 0, Size len = EndPos); 727 728 /** Substitute the first occurence of <b>to_replace</b> by the content of <b>replacing</b>. 729 @return the first position of the substitution or \link EndPos EndPos \endlink if <b>to_replace</b> is not found 730 */ 731 Size substitute(const String& to_replace, const String& replacing); 732 733 //@} 734 735 /** @name Predicates 736 */ 737 //@{ 738 739 /// True, if the string contains character <b>c</b> 740 bool has(char c) const; 741 742 /// True, if the string contains the substring <b>s</b> after index <b>from</b> 743 bool hasSubstring(const String& s, Index from = 0) const; 744 745 /// True, if the string starts with <b>s</b> 746 bool hasPrefix(const String& s) const; 747 748 /// True, if the string ends with <b>s</b> 749 bool hasSuffix(const String& s) const; 750 751 /// True, if the string has size 0 752 bool isEmpty() const; 753 754 /** True, if the string only contains letters (any case). 755 It returns also <b>true</b>, if called for an empty string. 756 */ 757 bool isAlpha() const; 758 759 /** True, if the string only contains letters and digits. 760 It returns also <b>true</b>, if called for an empty string. 761 */ 762 bool isAlnum() const; 763 764 /** True, if the string only contains digits. 765 It returns also <b>true</b>, if called for an empty string. 766 */ 767 bool isDigit() const; 768 769 /** True, if the string is a floating number. 770 (It contains only numbers and maybe a dot). 771 It returns also <b>true</b>, if called for an empty string. 772 */ 773 bool isFloat() const; 774 775 /** True, if the string only contains spaces. 776 It returns also <b>true</b>, if called for an empty string. 777 */ 778 bool isSpace() const; 779 780 /** True, if the string only contains whitespace characters. 781 Whitespaces are defined in CHARACTER_CLASS__WHITESPACE. 782 It returns also <b>true</b>, if called for an empty string. 783 */ 784 bool isWhitespace() const; 785 786 /// True, if the character is a letter (any case) 787 static bool isAlpha(char c); 788 789 /// True, if the character is a letter or a digit 790 static bool isAlnum(char c); 791 792 /// True, if the character is a digit 793 static bool isDigit(char c); 794 795 /// True, if the character is a space 796 static bool isSpace(char c); 797 798 /** True, if the character is any whitespace character. 799 Whitespaces are defined in CHARACTER_CLASS__WHITESPACE 800 */ 801 static bool isWhitespace(char c); 802 803 //@} 804 /** @name Base64 String methods 805 */ 806 //@{ 807 808 /// Convert a string to a base 64 string 809 String encodeBase64(); 810 811 /** Decode a base 64 string. 812 Return an empty string, if base64 string is not right encoded. 813 */ 814 String decodeBase64(); 815 816 //@} 817 /** @name Comparators 818 */ 819 //@{ 820 821 /** compare to a string. 822 * @exception Exception::IndexUnderflow if <tt>from < 0</tt> 823 * @exception Exception::IndexOverflow if <tt>from >= size()</tt> 824 */ 825 int compare(const String& string, Index from = 0) const; 826 827 /** compare to a string. 828 * @exception Exception::IndexUnderflow if <tt>from < 0</tt> 829 * @exception Exception::IndexOverflow if <tt>from >= size()</tt> 830 */ 831 int compare(const String& string, Index from, Size len) const; 832 833 834 /** compare to c-style string. 835 * @exception Exception::IndexUnderflow if <tt>from < 0</tt> 836 * @exception Exception::IndexOverflow if <tt>from >= size()</tt> 837 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 838 */ 839 int compare(const char* char_ptr, Index from = 0) const; 840 841 /** compare to c-style string. 842 * @exception Exception::IndexUnderflow if <tt>from < 0</tt> 843 * @exception Exception::IndexOverflow if <tt>from >= size()</tt> 844 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 845 */ 846 int compare(const char* char_ptr, Index from, Size len) const; 847 848 /** compare to character 849 * @exception Exception::IndexUnderflow if <tt>from < 0</tt> 850 * @exception Exception::IndexOverflow if <tt>from >= size()</tt> 851 */ 852 int compare(char c, Index from = 0) const; 853 854 /// 855 bool operator == (const String& string) const; 856 857 /// 858 bool operator != (const String& string) const; 859 860 /// 861 bool operator < (const String& string) const; 862 863 /// 864 bool operator <= (const String& string) const; 865 866 /// 867 bool operator >= (const String& string) const; 868 869 /// 870 bool operator > (const String& string) const; 871 872 /** Equality operator. 873 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 874 */ 875 BALL_EXPORT 876 friend bool operator == (const char* char_ptr, const String& string); 877 878 /** Inequality operator. 879 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 880 */ 881 BALL_EXPORT 882 friend bool operator != (const char* char_ptr, const String& string); 883 884 /** Less than comparison 885 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 886 */ 887 BALL_EXPORT 888 friend bool operator < (const char* char_ptr, const String& string); 889 890 /** Less than or equal comparison 891 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 892 */ 893 BALL_EXPORT 894 friend bool operator <= (const char* char_ptr, const String& string); 895 896 /** Greater than comparison 897 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 898 */ 899 BALL_EXPORT 900 friend bool operator > (const char* char_ptr, const String& string); 901 902 /** Greater than or equal comparison 903 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 904 */ 905 BALL_EXPORT 906 friend bool operator >= (const char* char_ptr, const String& string); 907 908 /** Equality operator. 909 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 910 */ 911 bool operator == (const char* char_ptr) const; 912 913 /** Inequality operator. 914 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 915 */ 916 bool operator != (const char* char_ptr) const; 917 918 /** Less than comparison 919 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 920 */ 921 bool operator < (const char* char_ptr) const; 922 923 /** Less than or equal comparison 924 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 925 */ 926 bool operator <= (const char* char_ptr) const; 927 928 /** Greater than comparison 929 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 930 */ 931 bool operator > (const char* char_ptr) const; 932 933 /** Greater than or equal comparison 934 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 935 */ 936 bool operator >= (const char* char_ptr) const; 937 938 /// 939 BALL_EXPORT 940 friend bool operator == (char c, const String& string); 941 942 /// 943 BALL_EXPORT 944 friend bool operator != (char c, const String& string); 945 946 /// 947 BALL_EXPORT 948 friend bool operator < (char c, const String& string); 949 950 /// 951 BALL_EXPORT 952 friend bool operator <= (char c, const String& string); 953 954 /// 955 BALL_EXPORT 956 friend bool operator > (char c, const String& string); 957 958 /// 959 friend bool operator >= (char c, const String& string); 960 961 /// 962 bool operator == (char c) const; 963 964 /// 965 bool operator != (char c) const; 966 967 /// 968 bool operator < (char c) const; 969 970 /// 971 bool operator <= (char c) const; 972 973 /// 974 bool operator > (char c) const; 975 976 /// 977 bool operator >= (char c) const; 978 979 //@} 980 /** @name Debugging and Diagnostics 981 */ 982 //@{ 983 984 /// 985 bool isValid() const; 986 987 /// 988 void dump(std::ostream& s = std::cout, Size depth = 0) const; 989 990 //@} 991 /** @name Stream Operations 992 */ 993 //@{ 994 995 /// 996 std::istream& getline(std::istream& s = std::cin, char delimiter = '\n'); 997 998 /// 999 BALL_EXPORT 1000 friend std::istream& getline(std::istream& s, String& string, char delimiter); 1001 1002 //@} 1003 1004 /// Constant empty string. 1005 static const String EMPTY; 1006 1007 protected: 1008 1009 // the validate... methods check perform a thorough 1010 // index checking and an index translation 1011 // Indices below zero are interpreted as indices 1012 // relative to the end of the string 1013 // All methods throw IndexUnder|Overflow exceptions 1014 // 1015 void validateIndex_(Index& index) const; 1016 1017 void validateRange_(Index& from, Size& len) const; 1018 1019 static void validateCharPtrRange_(Index& from, Size& len, const char* char_ptr); 1020 1021 static void valudateCharPtrIndex_(Index& index); 1022 1023 private: 1024 1025 static int compareAscendingly_(const char* a, const char* b); 1026 1027 static int compareDescendingly_(const char* a, const char* b); 1028 1029 static CompareMode compare_mode_; 1030 1031 static char B64Chars_[64]; 1032 1033 static int Index_64_[128]; 1034 }; 1035 1036 /** A substring class. 1037 The Substring class represents an efficient way to deal with substrings 1038 of \link String String \endlink . Each Substring is bound to an instance of String and 1039 is defined by a start and end index. It can be used like a String (with several 1040 restrictions) but only affects the given range of the string it is bount to. \par 1041 1042 \ingroup String 1043 */ 1044 class BALL_EXPORT Substring 1045 { 1046 friend class String; 1047 1048 public: 1049 BALL_CREATE_DEEP(Substring)1050 BALL_CREATE_DEEP(Substring) 1051 1052 /** @name Exceptions 1053 */ 1054 //@{ 1055 1056 /** Exception thrown if an unbound substring is accessed. 1057 This exception is thrown by most accessors and predicates of 1058 Substring if the substring is not bound to a string. 1059 */ 1060 class BALL_EXPORT UnboundSubstring 1061 : public Exception::GeneralException 1062 { 1063 public: 1064 UnboundSubstring(const char* file, int line); 1065 }; 1066 1067 /** Exception thrown if an invalid substring is accessed. 1068 This exception is thrown if an invalid substring 1069 is to be used. 1070 @see isValid 1071 */ 1072 class BALL_EXPORT InvalidSubstring 1073 : public Exception::GeneralException 1074 { 1075 public: 1076 InvalidSubstring(const char* file, int line); 1077 }; 1078 1079 //@} 1080 /** @name Constructors and Destructors 1081 */ 1082 //@{ 1083 1084 /** Default constructor. 1085 Create an empty string. 1086 */ 1087 Substring(); 1088 1089 /** Copy constructor. 1090 Create a substring from another substring. 1091 @param substring the substring to be copied 1092 @param deep ignored 1093 */ 1094 Substring(const Substring& substring, bool deep = true); 1095 1096 /** Create a substring from a string and two indices. 1097 @param string the string the substring is bound to. 1098 @param from the start index of the substring 1099 @param len the length of the substring (default <tt>EndPos</tt>: to the end of the string) 1100 @exception Exception::IndexUnderflow if <tt>from < 0</tt> 1101 @exception Exception::IndexOverflow if <tt>from || len >= size()</tt> 1102 */ 1103 Substring(const String& string, Index from = 0, Size len = String::EndPos); 1104 1105 /** Destructor. 1106 Destruct the substring. 1107 */ 1108 virtual ~Substring(); 1109 1110 /** Clear the substrings contents. 1111 Unbind the substring from its string and set the 1112 start and the end position to 0. 1113 */ 1114 void destroy(); 1115 1116 /** Clear the substrings contents. 1117 Unbind the substring from its string and set the 1118 start and the end position to 0. 1119 */ 1120 virtual void clear(); 1121 1122 //@} 1123 /** @name Converters 1124 */ 1125 //@{ 1126 1127 /** Convert a substring to a string. 1128 * Return a copy of the substring's contents. 1129 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1130 */ 1131 operator String() const; 1132 1133 /** Convert a substring to a string. 1134 * Return a copy of the substring's contents. 1135 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1136 */ 1137 String toString() const; 1138 1139 //@} 1140 /** @name Binding and Unbinding Substrings 1141 */ 1142 //@{ 1143 1144 /** Bind the substring to a string. 1145 @param string the string to bind to 1146 @param from the start position in the string (default is the beginning of the string) 1147 @param len the substring's length (default is to the end of the string) 1148 1149 @exception Exception::IndexUnderflow if <tt>index < 0</tt> 1150 @exception Exception::IndexOverflow if <tt>index >= size()</tt> 1151 */ 1152 Substring& bind(const String& string, Index from = 0, Size len = String::EndPos); 1153 1154 /** Bind the substring to the same string another substring is bound to. 1155 * @param substring the substring that is bound to a string 1156 * @exception Exception::IndexUnderflow if <tt>index < 0</tt> 1157 * @exception Exception::IndexOverflow if <tt>index >= size()</tt> 1158 */ 1159 Substring& bind(const Substring& substring, Index from = 0, Size len = String::EndPos); 1160 1161 /// unbinds the substring from the string it is bound to 1162 void unbind(); 1163 1164 /// Return a pointer to the bound String 1165 String* getBoundString(); 1166 1167 /// Retunrs a const pointer to the bound String 1168 const String* getBoundString() const 1169 ; 1170 1171 //@} 1172 /** @name Assignment 1173 */ 1174 //@{ 1175 1176 /** Sets the substring to a certain string 1177 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1178 */ 1179 void set(const String& string); 1180 1181 /** Copies a substring from another substring 1182 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1183 */ 1184 void set(const Substring& s); 1185 1186 /** Assigns a substring from a char pointer 1187 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1188 * @exception Exception::IndexUnderflow 1189 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 1190 */ 1191 void set(const char* char_ptr, Size size = String::EndPos); 1192 1193 /** String assignment operator 1194 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1195 */ 1196 const Substring& operator = (const String& string); 1197 1198 /** Substring assignment operator 1199 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1200 */ 1201 const Substring& operator = (const Substring& substring); 1202 1203 /** char pointer assignment operator 1204 * @exception Exception::NullPointer if <tt>char_ptr == NULL</tt> 1205 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1206 */ 1207 const Substring& operator = (const char* char_ptr); 1208 1209 //@} 1210 /** @name Accessors and Mutators 1211 */ 1212 //@{ 1213 1214 /** Return a pointer to the substring's contents 1215 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1216 */ 1217 char* c_str(); 1218 1219 /** Return a const pointer to the substring's contents 1220 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1221 */ 1222 const char* c_str() const; 1223 1224 /** Return the first index of the substring. 1225 * This means the starting point in the bound string. 1226 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1227 */ 1228 Index getFirstIndex() const; 1229 1230 /** Return the last index of the substring 1231 * This means the end point in the bound string. 1232 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1233 */ 1234 Index getLastIndex() const; 1235 1236 /// Return the substring size 1237 Size size() const; 1238 1239 /** Mutable random access to a character of the substring 1240 * @exception Exception::IndexUnderflow if <tt>index < 0</tt> 1241 * @exception Exception::IndexOverflow if <tt>index >= size()</tt> 1242 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1243 */ 1244 char& operator [] (Index index); 1245 1246 /** Random access to a character of the substring (const method). 1247 * @exception Exception::IndexUnderflow if <tt>index < 0</tt> 1248 * @exception Exception::IndexOverflow if <tt>index >= size()</tt> 1249 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1250 */ 1251 char operator [] (Index index) const; 1252 1253 /** Converts the substring to lower case characters 1254 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1255 */ 1256 Substring& toLower(); 1257 1258 /** Converts the substring to lower case characters 1259 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1260 */ 1261 Substring& toUpper(); 1262 1263 //@} 1264 /** @name Predicates 1265 */ 1266 //@{ 1267 1268 /// Return true, if the substring is bound to a String 1269 bool isBound() const; 1270 1271 /// Return true, if the substring is empty or unbound 1272 bool isEmpty() const; 1273 1274 //@} 1275 /** @name Comparison Operators 1276 */ 1277 //@{ 1278 1279 /** returns true, if the contents of the two substrings are equal 1280 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1281 */ 1282 bool operator == (const Substring& substring) const; 1283 1284 /** Return true, if the contents of the two substrings are not equal 1285 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1286 */ 1287 bool operator != (const Substring& substring) const; 1288 1289 /** Return true, if the contents of the substring and the string are equal 1290 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1291 */ 1292 bool operator == (const String& string) const; 1293 1294 /** Return true, if the contents of the substring and the string are not equal 1295 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1296 */ 1297 bool operator != (const String& string) const; 1298 1299 /** Return true, if the contents of the substring and the string are equal 1300 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1301 */ 1302 BALL_EXPORT 1303 friend bool operator == (const String& string, const Substring& substring); 1304 1305 /** Return true, if the contents of the substring and the string are not equal 1306 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1307 */ 1308 BALL_EXPORT 1309 friend bool operator != (const String& string, const Substring& substring); 1310 1311 /** Return true, if the contents of the substring are equal to the contents of the C-string 1312 * @exception Exception::NullPointer if <tt>delimiters == NULL</tt> 1313 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1314 */ 1315 bool operator == (const char* char_ptr) const; 1316 1317 /** Return true, if the contents of the substring are not equal to the contents of the C-string 1318 * @exception Exception::NullPointer if <tt>delimiters == NULL</tt> 1319 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1320 */ 1321 bool operator != (const char* char_ptr) const; 1322 1323 /** Return true, if the substring has length 1 and contains the given char 1324 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1325 */ 1326 bool operator == (char c) const; 1327 1328 /** Return true, if the substring is differnet from the given char 1329 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1330 */ 1331 bool operator != (char c) const; 1332 1333 //@} 1334 /** @name Stream I/O 1335 */ 1336 //@{ 1337 1338 /// Writes the substring to a stream 1339 BALL_EXPORT 1340 friend std::ostream& operator << (std::ostream& s, const Substring& substring); 1341 1342 //@} 1343 /** @name Debugging and Diagnostics 1344 */ 1345 //@{ 1346 1347 /** Return true, if the string is bound to a string and its indices are valid. 1348 Valid indices means that the first index is not greater than the last index, 1349 both indices are non-negative and lesser than the size of the bound string. 1350 */ 1351 bool isValid() const; 1352 1353 /** Dumps the substring object (including the values of its private members) 1354 * @exception Substring::UnboundSubstring if this Substring is not correctly bound 1355 */ 1356 void dump(std::ostream& s = std::cout, Size depth = 0) const; 1357 1358 //@} 1359 1360 protected: 1361 1362 // throws IndexUnderflow|IndexOverflow 1363 void validateRange_(Index& from, Size& len) const; 1364 1365 private: 1366 1367 /*_ @name Attributes 1368 */ 1369 //_@{ 1370 1371 //_ pointer to the bound String 1372 String* bound_; 1373 1374 //_ start index in the bound String 1375 Index from_; 1376 1377 //_ end index in the bound String 1378 Index to_; 1379 //_@} 1380 }; 1381 1382 //@} 1383 1384 # ifndef BALL_NO_INLINE_FUNCTIONS 1385 # include <BALL/DATATYPE/string.iC> 1386 # endif 1387 } // namespace BALL 1388 1389 #endif // BALL_DATATYPE_STRING_H 1390