00001 /* 00002 * Copyright 2006-2008 The FLWOR Foundation. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef ZORBA_STRING_API_H 00018 #define ZORBA_STRING_API_H 00019 00020 #include <iterator> 00021 #include <memory> 00022 #include <string> 00023 00024 #include <zorba/config.h> 00025 00026 namespace zorba { 00027 00028 /** 00029 * The Zorba string class. 00030 * 00031 * Its API is mostly compatible with that of std::string. 00032 */ 00033 class ZORBA_DLL_PUBLIC String { 00034 public: 00035 typedef char value_type; 00036 typedef std::char_traits<value_type> traits_type; 00037 typedef std::allocator<value_type> allocator_type; 00038 typedef allocator_type::difference_type difference_type; 00039 typedef allocator_type::size_type size_type; 00040 00041 typedef value_type* pointer; 00042 typedef value_type const* const_pointer; 00043 typedef value_type& reference; 00044 typedef value_type const& const_reference; 00045 00046 typedef pointer iterator; 00047 typedef const_pointer const_iterator; 00048 typedef std::reverse_iterator<iterator> reverse_iterator; 00049 typedef std::reverse_iterator<const_iterator> const_reverse_iterator; 00050 00051 /** 00052 * The special value used to denote either (a) the maximum possible number as 00053 * input or (b) "not found" as a result. 00054 */ 00055 static size_type const npos = static_cast<size_type>( -1 ); 00056 00057 ////////// constructors & destructor //////////////////////////////////////// 00058 00059 /** 00060 * Constructs an empty string. 00061 */ 00062 String(); 00063 00064 /** 00065 * Copy constructs a new string from an existing string. 00066 * 00067 * @param s The string to copy from. 00068 */ 00069 String( String const &s ); 00070 00071 /** 00072 * Constructs a new string from an existing std::string. 00073 * 00074 * @param s The string to copy from. 00075 */ 00076 String( std::string const &s ); 00077 00078 /** 00079 * Constructs a string from the given C string. 00080 * 00081 * @param s The null-terminated C string. 00082 */ 00083 String( const_pointer s ); 00084 00085 /** 00086 * Copy constructs a new string from a substring of an existing string. 00087 * 00088 * @param s The string to copy from. 00089 * @param pos The position of the first character to copy. 00090 * @param n The number of characters to copy. 00091 */ 00092 String( String const &s, size_type pos, size_type n = npos ); 00093 00094 /** 00095 * Constructs a new string from a substring of an existing std::string. 00096 * 00097 * @param s The string to copy from. 00098 * @param pos The starting position of the substring. 00099 * @param n The number of characters of the substring. 00100 */ 00101 String( std::string const &s, size_type pos, size_type n = npos ); 00102 00103 /** 00104 * Constructs a string from the given C string. 00105 * 00106 * @param s The C string. 00107 * @param n The number of characters to copy. 00108 */ 00109 String( const_pointer s, size_type n ); 00110 00111 /** 00112 * Constructs a new string as \a n copies of \a c. 00113 * 00114 * @param n The number of times to repeat the character. 00115 * @param c The character to repeat. 00116 */ 00117 String( size_type n, value_type c ); 00118 00119 /** 00120 * Constructs a string from a range of characters [i,j). 00121 * 00122 * @param i The iterator marking the first character of the range. 00123 * @param j The iterator marking one past the last character of the range. 00124 */ 00125 String( const_iterator i, const_iterator j ); 00126 00127 /** 00128 * Destructs this string. 00129 */ 00130 ~String(); 00131 00132 ////////// assignment /////////////////////////////////////////////////////// 00133 00134 /** 00135 * Assigns another string to this string. 00136 * 00137 * @param s The string to assign from. 00138 * @return this string. 00139 */ 00140 String& operator=( String const &s ); 00141 00142 /** 00143 * Assigns a std::string to this string. 00144 * 00145 * @param s The string to assign from. 00146 * @return this string. 00147 */ 00148 String& operator=( std::string const &s ); 00149 00150 /** 00151 * Assigns a C string to this string. 00152 * 00153 * @param s The null-terminated C string to assign from. 00154 * @return this string. 00155 */ 00156 String& operator=( const_pointer s ); 00157 00158 /** 00159 * Assigns a character to this string. 00160 * 00161 * @param c The character to assign. 00162 * @return this string. 00163 */ 00164 String& operator=( value_type c ); 00165 00166 ////////// properties /////////////////////////////////////////////////////// 00167 00168 /** 00169 * Gets the capacity of this string. 00170 * 00171 * @return said capacity. 00172 */ 00173 size_type capacity() const; 00174 00175 /** 00176 * Checks whether the string is empty. 00177 * 00178 * @return True only if it is. 00179 */ 00180 bool empty() const { 00181 return length() == 0; 00182 } 00183 00184 /** 00185 * Gets the number of characters in this string. 00186 * 00187 * @return The number of UTF-8 characters. 00188 */ 00189 size_type length() const; 00190 00191 /** 00192 * Gets the number of characters in this string. 00193 * (This is a synonym for length().) 00194 * 00195 * @return The number of UTF-8 characters. 00196 */ 00197 size_type size() const { 00198 return length(); 00199 } 00200 00201 ////////// character access ///////////////////////////////////////////////// 00202 00203 /** 00204 * References a particular character within the string. 00205 * 00206 * @param pos The index of the character. The index is bounds-checked. 00207 * @return said character as an l-value. 00208 * @throw std::out_of_range if \a pos >= \c size(). 00209 */ 00210 reference at( size_type pos ); 00211 00212 /** 00213 * References a particular character within the string. 00214 * 00215 * @param pos The index of the character. The index is bounds-checked. 00216 * @return said character as an r-value. 00217 */ 00218 value_type at( size_type pos ) const; 00219 00220 /** 00221 * References a particular character within the string. 00222 * 00223 * @param pos The index of the character. The index is not bounds-checked. 00224 * @return said character as an r-value. 00225 */ 00226 const_reference operator[]( size_type pos ) const; 00227 00228 ////////// append /////////////////////////////////////////////////////////// 00229 00230 /** 00231 * Appends the given string to this string. 00232 * 00233 * @param s The string to append. 00234 * @return this string. 00235 */ 00236 String& append( String const &s ); 00237 00238 /** 00239 * Appends a substring of the given string to this string. 00240 * 00241 * @param s The string to append. 00242 * @param s_pos The starting position is \a s. 00243 * @param s_n The number of characters of \a s to append. 00244 * @return this string. 00245 */ 00246 String& append( String const &s, size_type s_pos, size_type s_n ); 00247 00248 /** 00249 * Appends the given string to this string. 00250 * 00251 * @param s The string to append. 00252 * @return this string. 00253 */ 00254 String& append( std::string const &s ); 00255 00256 /** 00257 * Appends a substring of the given string to this string. 00258 * 00259 * @param s The string to append. 00260 * @param s_pos The starting position is \a s. 00261 * @param s_n The number of characters of \a s to append. 00262 * @return this string. 00263 */ 00264 String& append( std::string const &s, size_type s_pos, size_type s_n ); 00265 00266 /** 00267 * Appends the given C string to this string. 00268 * 00269 * @param s The null-terminated C string to append. 00270 * @return this string. 00271 */ 00272 String& append( const_pointer s ); 00273 00274 /** 00275 * Appends the given C string to this string. 00276 * 00277 * @param s The C string to append. 00278 * @param s_n The number of characters of \a s to append. 00279 * @return this string. 00280 */ 00281 String& append( const_pointer s, size_type s_n ); 00282 00283 /** 00284 * Appends \a n copies of \a c to this string. 00285 * 00286 * @param n The numer of copies of \a c to append. 00287 * @param c The character to append. 00288 * @return this string. 00289 */ 00290 String& append( size_type n, value_type c ); 00291 00292 /** 00293 * Appends the given character to this string. 00294 * 00295 * @param c The character to append. 00296 */ 00297 void push_back( value_type c ); 00298 00299 /** 00300 * Appends the given string to this string. 00301 * 00302 * @param s The string to append. 00303 * @return this string. 00304 */ 00305 String& operator+=( String const &s ) { 00306 return append( s ); 00307 } 00308 00309 /** 00310 * Appends the given std::string to this string. 00311 * 00312 * @param s The string to append. 00313 * @return this string. 00314 */ 00315 String& operator+=( std::string const &s ) { 00316 return append( s.data(), s.size() ); 00317 } 00318 00319 /** 00320 * Appends the given C string to this string. 00321 * 00322 * @param s The null-terminated C string to append. 00323 * @return this string. 00324 */ 00325 String& operator+=( const_pointer s ) { 00326 return append( s ); 00327 } 00328 00329 /** 00330 * Appends the given character to this string. 00331 * 00332 * @param c The character to append. 00333 * @return this string. 00334 */ 00335 String& operator+=( value_type c ) { 00336 return append( 1, c ); 00337 } 00338 00339 ////////// assign /////////////////////////////////////////////////////////// 00340 00341 /** 00342 * Assigns another string to this string. 00343 * 00344 * @param s The string to assign from. 00345 * @return this string. 00346 */ 00347 String& assign( String const &s ); 00348 00349 /** 00350 * Assigns a std::string to this string. 00351 * 00352 * @param s The string to assign from. 00353 * @return this string. 00354 */ 00355 String& assign( std::string const &s ); 00356 00357 /** 00358 * Assigns a substring of a string to this string. 00359 * 00360 * @param s The string to assign from. 00361 * @param pos The starting position withing \a s. 00362 * @param n The number of characters to assign. 00363 * @return this string. 00364 */ 00365 String& assign( String const &s, size_type pos, size_type n ); 00366 00367 /** 00368 * Assigns a substring of a std::string to this string. 00369 * 00370 * @param s The string to assign from. 00371 * @param pos The starting position withing \a s. 00372 * @param n The number of characters to assign. 00373 * @return this string. 00374 */ 00375 String& assign( std::string const &s, size_type pos, size_type n ); 00376 00377 /** 00378 * Assigns a C to this string. 00379 * 00380 * @param s The null-terminated C string to assign from. 00381 * @return this string. 00382 */ 00383 String& assign( const_pointer s ); 00384 00385 /** 00386 * Assigns a substring of a C to this string. 00387 * 00388 * @param s The C string to assign from. 00389 * @param n The number of characters to assign. 00390 * @return this string. 00391 */ 00392 String& assign( const_pointer s, size_type n ); 00393 00394 /** 00395 * Assigned \a n copies of a character to this string. 00396 * 00397 * @param n The number of copies of the character. 00398 * @param c The character. 00399 * @return this string. 00400 */ 00401 String& assign( size_type n, value_type c ); 00402 00403 /** 00404 * Assigns characters from a range of characters [i,j). 00405 * 00406 * @param i The iterator marking the first character of the range. 00407 * @param j The iterator marking one past the last character of the range. 00408 */ 00409 String& assign( const_iterator i, const_iterator j ); 00410 00411 ////////// compare ////////////////////////////////////////////////////////// 00412 00413 /** 00414 * Compares this string against another. 00415 * 00416 * @param s The string to compare to. 00417 * @return -1 only if this string < \a s, 00418 * 0 only if this string == \a s, 00419 * or +1 only if this string > \a s. 00420 */ 00421 int compare( String const &s ) const; 00422 00423 /** 00424 * Compares this string against another. 00425 * 00426 * @param s The string to compare to. 00427 * @return -1 only if this string < \a s, 00428 * 0 only if this string == \a s, 00429 * or +1 only if this string > \a s. 00430 */ 00431 int compare( std::string const &s ) const; 00432 00433 /** 00434 * Compares this string against a C string. 00435 * 00436 * @param s The null-terminated C string to compare to. 00437 * @return -1 only if this string < \a s, 00438 * 0 only if this string == \a s, 00439 * or +1 only if this string > \a s. 00440 */ 00441 int compare( const_pointer s ) const; 00442 00443 /** 00444 * Compares a substring of this string against another. 00445 * 00446 * @param pos The starting position within this string. 00447 * @param n The number of characters to compare. 00448 * @param s The string to compare to. 00449 * @return -1 only if this string < \a s, 00450 * 0 only if this string == \a s, 00451 * or +1 only if this string > \a s. 00452 */ 00453 int compare( size_type pos, size_type n, String const &s ) const; 00454 00455 /** 00456 * Compares a substring of this string against another. 00457 * 00458 * @param pos The starting position within this string. 00459 * @param n The number of characters to compare. 00460 * @param s The string to compare to. 00461 * @return -1 only if this string < \a s, 00462 * 0 only if this string == \a s, 00463 * or +1 only if this string > \a s. 00464 */ 00465 int compare( size_type pos, size_type n, std::string const &s ) const; 00466 00467 /** 00468 * Compares a substring of this string against a C string. 00469 * 00470 * @param pos The starting position within this string. 00471 * @param n The number of characters to compare. 00472 * @param s The null-terminated C string to compare to. 00473 * @return -1 only if this string < \a s, 00474 * 0 only if this string == \a s, 00475 * or +1 only if this string > \a s. 00476 */ 00477 int compare( size_type pos, size_type n, const_pointer s ) const; 00478 00479 /** 00480 * Compares a substring of this string against a substring of another. 00481 * 00482 * @param pos The starting position within this string. 00483 * @param n The number of characters to compare. 00484 * @param s The string to compare to. 00485 * @param s_pos The starting position within \a s. 00486 * @param s_n The number of characters of \a s to compare. 00487 * @return -1 only if this string < \a s, 00488 * 0 only if this string == \a s, 00489 * or +1 only if this string > \a s. 00490 */ 00491 int compare( size_type pos, size_type n, String const &s, size_type s_pos, 00492 size_type s_n ) const; 00493 00494 /** 00495 * Compares a substring of this string against a substring of another. 00496 * 00497 * @param pos The starting position within this string. 00498 * @param n The number of characters to compare. 00499 * @param s The string to compare to. 00500 * @param s_pos The starting position within \a s. 00501 * @param s_n The number of characters of \a s to compare. 00502 * @return -1 only if this string < \a s, 00503 * 0 only if this string == \a s, 00504 * or +1 only if this string > \a s. 00505 */ 00506 int compare( size_type pos, size_type n, std::string const &s, 00507 size_type s_pos, size_type s_n ) const; 00508 00509 /** 00510 * Compares a substring of this string against a C string. 00511 * 00512 * @param pos The starting position within this string. 00513 * @param n The number of characters to compare. 00514 * @param s The C string to compare to. 00515 * @param s_n The number of characters of \a s to compare. 00516 * @return -1 only if this string < \a s, 00517 * 0 only if this string == \a s, 00518 * or +1 only if this string > \a s. 00519 */ 00520 int compare( size_type pos, size_type n, const_pointer s, 00521 size_type s_n ) const; 00522 00523 ////////// clear/erase ////////////////////////////////////////////////////// 00524 00525 /** 00526 * Erases the string making it empty. 00527 */ 00528 void clear(); 00529 00530 /** 00531 * Erases the given number of characters starting at the given position. 00532 * 00533 * @param pos The position of the first character to erase. 00534 * @param n The number of characters to erase. 00535 * @return a reference to this string. 00536 * @throw std::out_of_range if \a pos is beyond the end of the string. 00537 */ 00538 String& erase( size_type pos = 0, size_type n = npos ); 00539 00540 /** 00541 * Erases the character at the given iterator's position. 00542 * 00543 * @param i The iterator marking the position of the character to erase. 00544 * @return a new iterator marking the same position (i.e., what becomes the 00545 * next character). 00546 */ 00547 iterator erase( iterator i ); 00548 00549 /** 00550 * Erases a range of characters [i,j). 00551 * 00552 * @param i The iterator marking the first character of the range. 00553 * @param j The iterator marking one past the last character of the range. 00554 * @return a new iterator marking the same position as \a i. 00555 */ 00556 iterator erase( iterator i, iterator j ); 00557 00558 ////////// find ///////////////////////////////////////////////////////////// 00559 00560 /** 00561 * Searches this string for the given string starting at the given position. 00562 * 00563 * @param s The string to search for. 00564 * @param pos The starting position within this string. 00565 * @return the offset of \a s or \c npos if not found. 00566 */ 00567 size_type find( String const &s, size_type pos = 0 ) const; 00568 00569 /** 00570 * Searches this string for the given string starting at the given position. 00571 * 00572 * @param s The string to search for. 00573 * @param pos The starting position within this string. 00574 * @return the offset of \a s or \c npos if not found. 00575 */ 00576 size_type find( std::string const &s, size_type pos = 0 ) const; 00577 00578 /** 00579 * Searches this string for the given string starting at the given position. 00580 * 00581 * @param s The null-terminated C string to search for. 00582 * @param pos The starting position within this string. 00583 * @return the offset of \a s or \c npos if not found. 00584 */ 00585 size_type find( const_pointer s, size_type pos = 0 ) const; 00586 00587 /** 00588 * Searches this string for the given string starting at the given position. 00589 * 00590 * @param s The C string to search for. 00591 * @param pos The starting position within this string. 00592 * @param s_n The number of characters to compare. 00593 * @return the offset of \a s or \c npos if not found. 00594 */ 00595 size_type find( const_pointer s, size_type pos, size_type s_n ) const; 00596 00597 /** 00598 * Searches this string for the given character staring at the given 00599 * position. 00600 * 00601 * @param c The character to search for. 00602 * @param pos The starting position within this string. 00603 * @return the offset of \a c or \c npos if not found. 00604 */ 00605 size_type find( value_type c, size_type pos = 0 ) const; 00606 00607 /** 00608 * Searches this string for any one of the characters in \a s starting at the 00609 * given position. 00610 * 00611 * @param s The set of characters to search for. 00612 * @param pos The starting position within this string. 00613 * @return the offset of a matching character or \c npos if not found. 00614 */ 00615 size_type find_first_of( String const &s, size_type pos = 0 ) const; 00616 00617 /** 00618 * Searches this string for any one of the characters in \a s starting at the 00619 * given position. 00620 * 00621 * @param s The set of characters to search for. 00622 * @param pos The starting position within this string. 00623 * @return the offset of a matching character or \c npos if not found. 00624 */ 00625 size_type find_first_of( std::string const &s, size_type pos = 0 ) const; 00626 00627 /** 00628 * Searches this string for any one of the characters in \a s starting at the 00629 * given position. 00630 * 00631 * @param s The set of characters to search for. 00632 * @param pos The starting position within this string. 00633 * @return the offset of a matching character or \c npos if not found. 00634 */ 00635 size_type find_first_of( const_pointer s, size_type pos = 0 ) const; 00636 00637 /** 00638 * Searches this string for any one of the first \a s_n characters in \a s 00639 * starting at the given position. 00640 * 00641 * @param s The set of characters to search for. 00642 * @param pos The starting position within this string. 00643 * @param s_n The number of characters of \a s to consider. 00644 * @return the offset of a matching character or \c npos if not found. 00645 */ 00646 size_type find_first_of( const_pointer s, size_type pos, 00647 size_type s_n ) const; 00648 00649 /** 00650 * Searches this string for the given character starting at the given 00651 * position. 00652 * 00653 * @param c The character to search for. 00654 * @param pos The starting position within this string. 00655 * @return the offset of \a c or \c npos if not found. 00656 */ 00657 size_type find_first_of( value_type c, size_type pos = 0 ) const; 00658 00659 /** 00660 * Searches this string for any one of the characters not in \a s starting at 00661 * the given position. 00662 * 00663 * @param s The set of characters not to search for. 00664 * @param pos The starting position within this string. 00665 * @return the offset of a non-matching character or \c npos if not found. 00666 */ 00667 size_type find_first_not_of( String const &s, size_type pos = 0 ) const; 00668 00669 /** 00670 * Searches this string for any one of the characters not in \a s starting at 00671 * the given position. 00672 * 00673 * @param s The set of characters not to search for. 00674 * @param pos The starting position within this string. 00675 * @return the offset of a non-matching character or \c npos if not found. 00676 */ 00677 size_type find_first_not_of( std::string const &s, size_type pos = 0 ) const; 00678 00679 /** 00680 * Searches this string for any one of the characters not in \a s starting at 00681 * the given position. 00682 * 00683 * @param s The set of characters not to search for. 00684 * @param pos The starting position within this string. 00685 * @return the offset of a non-matching character or \c npos if not found. 00686 */ 00687 size_type find_first_not_of( const_pointer s, size_type pos = 0 ) const; 00688 00689 /** 00690 * Searches this string for any one of the first \a s_n characters not in \a 00691 * s starting at the given position. 00692 * 00693 * @param s The set of characters not to search for. 00694 * @param pos The starting position within this string. 00695 * @param s_n The number of characters of \a s to consider. 00696 * @return the offset of a non-matching character or \c npos if not found. 00697 */ 00698 size_type find_first_not_of( const_pointer s, size_type pos, 00699 size_type s_n ) const; 00700 00701 /** 00702 * Searches this string for any character except the given character starting 00703 * at the given position. 00704 * 00705 * @param c The character not to search for. 00706 * @param pos The starting position within this string. 00707 * @return the offset of any character except \a c or \c npos if not found. 00708 */ 00709 size_type find_first_not_of( value_type c, size_type pos = 0 ) const; 00710 00711 /** 00712 * Searches this string backwards for any one of the characters in \a s 00713 * starting at the given position. 00714 * 00715 * @param s The set of characters to search for. 00716 * @param pos The starting position within this string. 00717 * @return the offset of a matching character or \c npos if not found. 00718 */ 00719 size_type find_last_of( String const &s, size_type pos = npos ) const; 00720 00721 /** 00722 * Searches this string backwards for any one of the characters in \a s 00723 * starting at the given position. 00724 * 00725 * @param s The set of characters to search for. 00726 * @param pos The starting position within this string. 00727 * @return the offset of a matching character or \c npos if not found. 00728 */ 00729 size_type find_last_of( std::string const &s, size_type pos = npos ) const; 00730 00731 /** 00732 * Searches this string backwards for any one of the characters in \a s 00733 * starting at the given position. 00734 * 00735 * @param s The set of characters to search for. 00736 * @param pos The starting position within this string. 00737 * @return the offset of a matching character or \c npos if not found. 00738 */ 00739 size_type find_last_of( const_pointer s, size_type pos = npos ) const; 00740 00741 /** 00742 * Searches this string backwards for any one of the first \a s_n characters 00743 * in \a s starting at the given position. 00744 * 00745 * @param s The set of characters to search for. 00746 * @param pos The starting position within this string. 00747 * @param s_n The number of characters of \a s to consider. 00748 * @return the offset of a matching character or \c npos if not found. 00749 */ 00750 size_type find_last_of( const_pointer s, size_type pos, size_type s_n ) const; 00751 00752 /** 00753 * Searches this string backwards for the given character starting at the 00754 * given position. 00755 * 00756 * @param c The character to search for. 00757 * @param pos The starting position within this string. 00758 * @return the offset of \a c or \c npos if not found. 00759 */ 00760 size_type find_last_of( value_type c, size_type pos = npos ) const; 00761 00762 /** 00763 * Searches this string backwards for any one of the characters not in \a s 00764 * starting at the given position. 00765 * 00766 * @param s The set of characters to not search for. 00767 * @param pos The starting position within this string. 00768 * @return the offset of a matching character or \c npos if not found. 00769 */ 00770 size_type find_last_not_of( String const &s, size_type pos = npos ) const; 00771 00772 /** 00773 * Searches this string backwards for any one of the characters not in \a s 00774 * starting at the given position. 00775 * 00776 * @param s The set of characters to not search for. 00777 * @param pos The starting position within this string. 00778 * @return the offset of a matching character or \c npos if not found. 00779 */ 00780 size_type find_last_not_of( std::string const &s, size_type pos = npos ) const; 00781 00782 /** 00783 * Searches this string backwards for any one of the characters not in \a s 00784 * starting at the given position. 00785 * 00786 * @param s The set of characters to not search for. 00787 * @param pos The starting position within this string. 00788 * @return the offset of a matching character or \c npos if not found. 00789 */ 00790 size_type find_last_not_of( const_pointer s, size_type pos = npos ) const; 00791 00792 /** 00793 * Searches this string backwards for any one of the first \a s_n characters 00794 * not in \a s starting at the given position. 00795 * 00796 * @param s The set of characters to not search for. 00797 * @param pos The starting position within this string. 00798 * @param s_n The number of characters of \a s to consider. 00799 * @return the offset of a matching character or \c npos if not found. 00800 */ 00801 size_type find_last_not_of( const_pointer s, size_type pos, 00802 size_type s_n ) const; 00803 00804 /** 00805 * Searches this string backwards for any character except the given 00806 * character starting at the given position. 00807 * 00808 * @param c The character to search for. 00809 * @param pos The starting position within this string. 00810 * @return the offset of any character except \a c or \c npos if not found. 00811 */ 00812 size_type find_last_not_of( value_type c, size_type pos = npos ) const; 00813 00814 /** 00815 * Searches this backwards string for the given string starting at the given 00816 * position. 00817 * 00818 * @param s The string to search for. 00819 * @param pos The starting position within this string. 00820 * @return the offset of \a s or \c npos if not found. 00821 */ 00822 size_type rfind( String const &s, size_type pos = npos ) const; 00823 00824 /** 00825 * Searches this backwards string for the given string starting at the given 00826 * position. 00827 * 00828 * @param s The string to search for. 00829 * @param pos The starting position within this string. 00830 * @return the offset of \a s or \c npos if not found. 00831 */ 00832 size_type rfind( std::string const &s, size_type pos = npos ) const; 00833 00834 /** 00835 * Searches this backwards string for the given string starting at the given 00836 * position. 00837 * 00838 * @param s The string to search for. 00839 * @param pos The starting position within this string. 00840 * @return the offset of \a s or \c npos if not found. 00841 */ 00842 size_type rfind( const_pointer s, size_type pos = npos ) const; 00843 00844 /** 00845 * Searches this string backwards for the given string starting at the given 00846 * position. 00847 * 00848 * @param s The C string to search for. 00849 * @param pos The starting position within this string. 00850 * @param s_n The number of characters to compare. 00851 * @return the offset of \a s or \c npos if not found. 00852 */ 00853 size_type rfind( const_pointer s, size_type pos, size_type s_n ) const; 00854 00855 /** 00856 * Searches this string backwards for the given character staring at the 00857 * given position. 00858 * 00859 * @param c The character to search for. 00860 * @param pos The starting position within this string. 00861 * @return the offset of \a c or \c npos if not found. 00862 */ 00863 size_type rfind( value_type c, size_type pos = npos ) const; 00864 00865 ////////// insert /////////////////////////////////////////////////////////// 00866 00867 /** 00868 * Inserts the given string into this string at the given position. 00869 * 00870 * @param pos The position within this string to insert at. 00871 * @param s The string to insert. 00872 * @return this string. 00873 */ 00874 String& insert( size_type pos, String const &s ); 00875 00876 /** 00877 * Inserts the given string into this string at the given position. 00878 * 00879 * @param pos The position within this string to insert at. 00880 * @param s The string to insert. 00881 * @return this string. 00882 */ 00883 String& insert( size_type pos, std::string const &s ); 00884 00885 /** 00886 * Inserts the given string into this string at the given position. 00887 * 00888 * @param pos The position within this string to insert at. 00889 * @param s The null-terminated string to insert. 00890 * @return this string. 00891 */ 00892 String& insert( size_type pos, const_pointer s ); 00893 00894 /** 00895 * Inserts a substring of the given string into this string at the given 00896 * position. 00897 * 00898 * @param pos The position within this string to insert at. 00899 * @param s The null-terminated C string to insert. 00900 * @param s_pos The starting position within \a s. 00901 * @param s_n The numer of characters of \a s to insert. 00902 * @return this string. 00903 */ 00904 String& insert( size_type pos, String const &s, size_type s_pos, 00905 size_type s_n ); 00906 00907 /** 00908 * Inserts a substring of the given string into this string at the given 00909 * position. 00910 * 00911 * @param pos The position within this string to insert at. 00912 * @param s The null-terminated C string to insert. 00913 * @param s_pos The starting position within \a s. 00914 * @param s_n The numer of characters of \a s to insert. 00915 * @return this string. 00916 */ 00917 String& insert( size_type pos, std::string const &s, size_type s_pos, 00918 size_type s_n ); 00919 00920 /** 00921 * Inserts a substring of the given string into this string at the given 00922 * position. 00923 * 00924 * @param pos The position within this string to insert at. 00925 * @param s The C string to insert. 00926 * @param s_n The numer of characters of \a s to insert. 00927 * @return this string. 00928 */ 00929 String& insert( size_type pos, const_pointer s, size_type s_n ); 00930 00931 /** 00932 * Inserts \a n copies of \a c into this string at the given position. 00933 * 00934 * @param pos The position within this string to insert at. 00935 * @param n The number of copies of \a c to insert. 00936 * @param c The character to insert. 00937 * @return this string. 00938 */ 00939 String& insert( size_type pos, size_type n, value_type c ); 00940 00941 /** 00942 * Inserts the given character into this string at the given position. 00943 * 00944 * @param pos The iterator marking the position within this string to insert 00945 * at. 00946 * @param c The character to insert. 00947 * @return Returns an iterator positioned at the newly inserted character. 00948 */ 00949 iterator insert( iterator pos, value_type c ); 00950 00951 /** 00952 * Inserts \a n copies of \a c into this string at the given position. 00953 * 00954 * @param pos The iterator marking the position within this string to insert 00955 * at. 00956 * @param n The number of copies of \a c to insert. 00957 * @param c The character to insert. 00958 */ 00959 void insert( iterator pos, size_type n, value_type c ); 00960 00961 ////////// replace ////////////////////////////////////////////////////////// 00962 00963 /** 00964 * Replaces \a n characters of this string starting at the given position 00965 * with the given string. 00966 * 00967 * @param pos The position within this string to replace at. 00968 * @param n The number of characters to replace. 00969 * @param s The replacement string. 00970 * @return this string. 00971 */ 00972 String& replace( size_type pos, size_type n, String const &s ); 00973 00974 /** 00975 * Replaces \a n characters of this string starting at the given position 00976 * with the given string. 00977 * 00978 * @param pos The position within this string to replace at. 00979 * @param n The number of characters to replace. 00980 * @param s The replacement string. 00981 * @return this string. 00982 */ 00983 String& replace( size_type pos, size_type n, std::string const &s ); 00984 00985 /** 00986 * Replaces \a n characters of this string starting at the given position 00987 * with the given string. 00988 * 00989 * @param pos The position within this string to replace at. 00990 * @param n The number of characters to replace. 00991 * @param s The null-terminated replacement C string. 00992 * @return this string. 00993 */ 00994 String& replace( size_type pos, size_type n, const_pointer s ); 00995 00996 /** 00997 * Replaces \a n characters of this string starting at the given position 00998 * with a substring of the given string. 00999 * 01000 * @param pos The position within this string to replace at. 01001 * @param n The number of characters to replace. 01002 * @param s The replacement string. 01003 * @param s_pos The starting position is \a s. 01004 * @param s_n The number of characters of \a s to use. 01005 * @return this string. 01006 */ 01007 String& replace( size_type pos, size_type n, String const &s, 01008 size_type s_pos, size_type s_n ); 01009 01010 /** 01011 * Replaces \a n characters of this string starting at the given position 01012 * with a substring of the given string. 01013 * 01014 * @param pos The position within this string to replace at. 01015 * @param n The number of characters to replace. 01016 * @param s The replacement string. 01017 * @param s_pos The starting position is \a s. 01018 * @param s_n The number of characters of \a s to use. 01019 * @return this string. 01020 */ 01021 String& replace( size_type pos, size_type n, std::string const &s, 01022 size_type s_pos, size_type s_n ); 01023 01024 /** 01025 * Replaces \a n characters of this string starting at the given position 01026 * with a substring of the given string. 01027 * 01028 * @param pos The position within this string to replace at. 01029 * @param n The number of characters to replace. 01030 * @param s The replacement C string. 01031 * @param s_n The number of characters of \a s to use. 01032 * @return this string. 01033 */ 01034 String& replace( size_type pos, size_type n, const_pointer s, size_type s_n ); 01035 01036 /** 01037 * Replaces \a n characters of this string starting at the given position 01038 * with \a c_n copies of \a c. 01039 * 01040 * @param pos The position within this string to replace at. 01041 * @param n The number of characters to replace. 01042 * @param c_n The number of copies of \c to replace with. 01043 * @param c The character to replace with. 01044 * @return this string. 01045 */ 01046 String& replace( size_type pos, size_type n, size_type c_n, value_type c ); 01047 01048 /** 01049 * Replaces the range of characters [i,j) of this string with the given 01050 * string. 01051 * 01052 * @param i The iterator marking the first character of the range. 01053 * @param j The iterator marking one past the last character of the range. 01054 * @param s The replacement string. 01055 * @return this string. 01056 */ 01057 String& replace( iterator i, iterator j, String const &s ); 01058 01059 /** 01060 * Replaces the range of characters [i,j) of this string with the given 01061 * string. 01062 * 01063 * @param i The iterator marking the first character of the range. 01064 * @param j The iterator marking one past the last character of the range. 01065 * @param s The replacement string. 01066 * @return this string. 01067 */ 01068 String& replace( iterator i, iterator j, std::string const &s ); 01069 01070 /** 01071 * Replaces the range of characters [i,j) of this string with the given 01072 * string. 01073 * 01074 * @param i The iterator marking the first character of the range. 01075 * @param j The iterator marking one past the last character of the range. 01076 * @param s The null-terminated replacement C string. 01077 * @return this string. 01078 */ 01079 String& replace( iterator i, iterator j, const_pointer s ); 01080 01081 /** 01082 * Replaces the range of characters [i,j) of this string with a substring of 01083 * the given string. 01084 * 01085 * @param i The iterator marking the first character of the range. 01086 * @param j The iterator marking one past the last character of the range. 01087 * @param s The replacement C string. 01088 * @param s_n The number of characters of \a s to use. 01089 * @return this string. 01090 */ 01091 String& replace( iterator i, iterator j, const_pointer s, size_type s_n ); 01092 01093 /** 01094 * Replaces the range of characters [i,j) of this string with \a c_n copies 01095 * of \a c. 01096 * 01097 * @param i The iterator marking the first character of the range. 01098 * @param j The iterator marking one past the last character of the range. 01099 * @param n The number of copies of \c to replace with. 01100 * @param c The character to replace with. 01101 * @return Returns this string. 01102 */ 01103 String& replace( iterator i, iterator j, size_type n, value_type c ); 01104 01105 /** 01106 * Replaces the range of characters [i,j) of this string with the range of 01107 * characters [si,sj). 01108 * 01109 * @param i The iterator marking the first character of the range. 01110 * @param j The iterator marking one past the last character of the range. 01111 * @param si The iterator marking the first character of the range. 01112 * @param sj The iterator marking one past the last character of the range. 01113 * @return this string. 01114 */ 01115 String& replace( iterator i, iterator j, iterator si, iterator sj ); 01116 01117 ////////// iterators //////////////////////////////////////////////////////// 01118 01119 /** 01120 * Returns a read/write iterator positioned at the first character of the 01121 * string. 01122 * 01123 * @return said iterator. 01124 */ 01125 iterator begin(); 01126 01127 /** 01128 * Returns a read-only iterator positioned at the first character of the 01129 * string. 01130 * 01131 * @return said iterator. 01132 */ 01133 const_iterator begin() const; 01134 01135 /** 01136 * Returns a read/write iterator positioned at one past the last character of 01137 * the string. 01138 * 01139 * @return said iterator. 01140 */ 01141 iterator end(); 01142 01143 /** 01144 * Returns a read-only iterator positioned at one past the last character of 01145 * the string. 01146 * 01147 * @return said iterator. 01148 */ 01149 const_iterator end() const; 01150 01151 /** 01152 * Returns a read/write reverse iterator positioned at the first character of 01153 * the reversed string. 01154 * 01155 * @return said iterator. 01156 */ 01157 reverse_iterator rbegin(); 01158 01159 /** 01160 * Returns a read-only reverse iterator positioned at the first character of 01161 * the reversed string. 01162 * 01163 * @return said iterator. 01164 */ 01165 const_reverse_iterator rbegin() const; 01166 01167 /** 01168 * Returns a read/write reverse iterator positioned at one past the last 01169 * character of the reversed string. 01170 * 01171 * @return said iterator. 01172 */ 01173 reverse_iterator rend(); 01174 01175 /** 01176 * Returns a read-only reverse iterator positioned at one past the last 01177 * character of the reversed string. 01178 * 01179 * @return said iterator. 01180 */ 01181 const_reverse_iterator rend() const; 01182 01183 ////////// miscellaneous //////////////////////////////////////////////////// 01184 01185 /** 01186 * Copies a substring to a C string buffer. 01187 * 01188 * @param buf The buffer to copy into. 01189 * @param n The number of characters to copy. 01190 * It's the caller's responsibility to ensure that the size of \a buf <= \a 01191 * n. 01192 * @param pos The position of the first character to copy. 01193 * @return the number of characters actually copied. 01194 * @throw std::out_of_range if \a pos >= size(). 01195 */ 01196 size_type copy( pointer buf, size_type n, size_type pos = 0 ) const; 01197 01198 /** 01199 * Gets a pointer to a null-terminated array of characters representing the 01200 * string's contents. 01201 * 01202 * @return said pointer. 01203 * @see data() 01204 */ 01205 const_pointer c_str() const; 01206 01207 /** 01208 * Gets a pointer to the raw character data comprising the string, not 01209 * necessarily null-terminated. 01210 * 01211 * @return said pointer. 01212 * @see c_str() 01213 */ 01214 const_pointer data() const; 01215 01216 /** 01217 * Attemts to pre-allocated enough memory to contain the given number of 01218 * bytes. 01219 * 01220 * @param n The number of bytes. 01221 */ 01222 void reserve( size_type n ); 01223 01224 /** 01225 * Resizes the string to the given number of characters. 01226 * If the number < size(), the string will be truncated; 01227 * if the number > size(), the string will be extended 01228 * and the new elements will be set to \a c. 01229 * 01230 * @param n The number of characters. 01231 * @param c Characters to fill any new positions. 01232 */ 01233 void resize( size_type n, value_type c = value_type() ); 01234 01235 /** 01236 * Gets a \c std::string equivalent of this string. 01237 * (There intentionally is no <code>operator std::string() const</code> since 01238 * its convenient use would mask the expense of creating a new \c 01239 * std::string.) 01240 * This function is an extension to the std::string API. 01241 * 01242 * @return said \c std::string. 01243 */ 01244 std::string str() const; 01245 01246 /** 01247 * Creates a new string that is a substring of this string. 01248 * 01249 * @param pos The position in this string for first character of the new 01250 * string. 01251 * @param n The number of characters to extract. 01252 * @return the new string. 01253 * @throw std::out_of_range if \a pos >= size(). 01254 */ 01255 String substr( size_type pos = 0, size_type n = npos ) const; 01256 01257 /** 01258 * Swaps the contents of this string with another. 01259 * This is an O(1) operation. 01260 * 01261 * @param s The string to swap with. 01262 */ 01263 void swap( String &s ); 01264 01265 ///////////////////////////////////////////////////////////////////////////// 01266 01267 private: 01268 // 01269 // We need to use a struct in order to assert that its size >= the size of 01270 // the internal string class. 01271 // 01272 struct string_storage_type { 01273 // 01274 // We need to do this union weirdness so as not to break strict-aliasing 01275 // rules. 01276 // 01277 union { 01278 void *rep_; 01279 char storage_[1]; 01280 }; 01281 #ifdef ZORBA_DEBUG_STRING 01282 char *debug_str_; 01283 #endif /* ZORBA_DEBUG_STRING */ 01284 }; 01285 01286 string_storage_type string_storage_; 01287 01288 // Using a struct prevents void* ambiguity with char*. 01289 struct zstring_ptr { void const *ptr; }; 01290 01291 String( zstring_ptr ); 01292 String& operator=( zstring_ptr ); 01293 01294 static void size_check(); 01295 01296 friend ZORBA_DLL_PUBLIC bool operator==( String const&, String const& ); 01297 friend ZORBA_DLL_PUBLIC bool operator==( String const&, std::string const& ); 01298 friend ZORBA_DLL_PUBLIC bool operator==( String const&, const_pointer ); 01299 01300 friend ZORBA_DLL_PUBLIC bool operator<( String const&, String const& ); 01301 friend ZORBA_DLL_PUBLIC bool operator<( String const&, std::string const& ); 01302 friend ZORBA_DLL_PUBLIC bool operator<( String const&, const_pointer ); 01303 friend ZORBA_DLL_PUBLIC bool operator<( std::string const&, String const& ); 01304 friend ZORBA_DLL_PUBLIC bool operator<( const_pointer, String const& ); 01305 01306 friend ZORBA_DLL_PUBLIC bool operator<=( String const&, String const& ); 01307 friend ZORBA_DLL_PUBLIC bool operator<=( String const&, std::string const& ); 01308 friend ZORBA_DLL_PUBLIC bool operator<=( String const&, const_pointer ); 01309 friend ZORBA_DLL_PUBLIC bool operator<=( std::string const&, String const& ); 01310 friend ZORBA_DLL_PUBLIC bool operator<=( const_pointer, String const& ); 01311 01312 friend ZORBA_DLL_PUBLIC String operator+( String const&, String const& ); 01313 friend ZORBA_DLL_PUBLIC String operator+( String const&, std::string const& ); 01314 friend ZORBA_DLL_PUBLIC String operator+( String const&, const_pointer ); 01315 friend ZORBA_DLL_PUBLIC String operator+( std::string const&, String const& ); 01316 friend ZORBA_DLL_PUBLIC String operator+( const_pointer, String const& ); 01317 01318 friend ZORBA_DLL_PUBLIC 01319 std::ostream& operator<<( std::ostream&, String const& ); 01320 01321 friend class Unmarshaller; 01322 }; 01323 01324 ////////// relational operators /////////////////////////////////////////////// 01325 01326 ZORBA_DLL_PUBLIC bool operator==( String const &s1, String const &s2 ); 01327 ZORBA_DLL_PUBLIC bool operator==( String const &s1, std::string const &s2 ); 01328 ZORBA_DLL_PUBLIC bool operator==( String const &s1, String::const_pointer s2 ); 01329 01330 ZORBA_DLL_PUBLIC bool operator<( String const &s1, String const &s2 ); 01331 ZORBA_DLL_PUBLIC bool operator<( String const &s1, std::string const &s2 ); 01332 ZORBA_DLL_PUBLIC bool operator<( String const &s1, String::const_pointer s2 ); 01333 ZORBA_DLL_PUBLIC bool operator<( std::string const &s1, String const &s2 ); 01334 ZORBA_DLL_PUBLIC bool operator<( String::const_pointer s1, String const &s2 ); 01335 01336 ZORBA_DLL_PUBLIC bool operator<=( String const &s1, String const &s2 ); 01337 ZORBA_DLL_PUBLIC bool operator<=( String const &s1, std::string const &s2 ); 01338 ZORBA_DLL_PUBLIC bool operator<=( String const &s1, String::const_pointer s2 ); 01339 ZORBA_DLL_PUBLIC bool operator<=( std::string const &s1, String const &s2 ); 01340 ZORBA_DLL_PUBLIC bool operator<=( String::const_pointer s1, String const &s2 ); 01341 01342 inline bool operator==( std::string const &s1, String const &s2 ) { 01343 return s2 == s1; 01344 } 01345 01346 inline bool operator==( String::const_pointer s1, String const &s2 ) { 01347 return s2 == s1; 01348 } 01349 01350 inline bool operator!=( String const &s1, String const &s2 ) { 01351 return !(s1 == s2); 01352 } 01353 01354 inline bool operator!=( String const &s1, std::string const &s2 ) { 01355 return !(s1 == s2); 01356 } 01357 01358 inline bool operator!=( String const &s1, String::const_pointer s2 ) { 01359 return !(s1 == s2); 01360 } 01361 01362 inline bool operator!=( std::string const &s1, String const &s2 ) { 01363 return !(s1 == s2); 01364 } 01365 01366 inline bool operator!=( String::const_pointer s1, String const &s2 ) { 01367 return !(s1 == s2); 01368 } 01369 01370 inline bool operator>=( String const &s1, String const &s2 ) { 01371 return !(s1 < s2); 01372 } 01373 01374 inline bool operator>=( String const &s1, std::string const &s2 ) { 01375 return !(s1 < s2); 01376 } 01377 01378 inline bool operator>=( String const &s1, String::const_pointer s2 ) { 01379 return !(s1 < s2); 01380 } 01381 01382 inline bool operator>=( std::string const &s1, String const &s2 ) { 01383 return !(s1 < s2); 01384 } 01385 01386 inline bool operator>=( String::const_pointer s1, String const &s2 ) { 01387 return !(s1 < s2); 01388 } 01389 01390 inline bool operator>( String const &s1, String const &s2 ) { 01391 return !(s1 <= s2); 01392 } 01393 01394 inline bool operator>( String const &s1, std::string const &s2 ) { 01395 return !(s1 <= s2); 01396 } 01397 01398 inline bool operator>( String const &s1, String::const_pointer s2 ) { 01399 return !(s1 <= s2); 01400 } 01401 01402 inline bool operator>( std::string const &s1, String const &s2 ) { 01403 return !(s1 <= s2); 01404 } 01405 01406 inline bool operator>( String::const_pointer s1, String const &s2 ) { 01407 return !(s1 <= s2); 01408 } 01409 01410 ////////// concatenation ////////////////////////////////////////////////////// 01411 01412 ZORBA_DLL_PUBLIC String operator+( String const &s1, String const &s2 ); 01413 ZORBA_DLL_PUBLIC String operator+( String const &s1, std::string const &s2 ); 01414 ZORBA_DLL_PUBLIC String operator+( String const &s1, String::const_pointer s2 ); 01415 ZORBA_DLL_PUBLIC String operator+( std::string const &s1, String const &s2 ); 01416 ZORBA_DLL_PUBLIC String operator+( String::const_pointer s1, String const &s2 ); 01417 01418 ////////// ostream insertion ////////////////////////////////////////////////// 01419 01420 ZORBA_DLL_PUBLIC std::ostream& operator<<( std::ostream &o, String const &s ); 01421 01422 /////////////////////////////////////////////////////////////////////////////// 01423 01424 } // namespace zorba 01425 01426 #endif /* ZORBA_STRING_API_H */ 01427 /* vim:set et sw=2 ts=2: */