zorba_string.h
Go to the documentation of this file.
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: */
blog comments powered by Disqus