String.h

Go to the documentation of this file.
00001 //# String.h: String class
00002 //# Copyright (C) 2001,2002,2003
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id$
00027 
00028 #ifndef CASA_STRING_H
00029 #define CASA_STRING_H
00030 
00031 //# Includes
00032 #include <casa/aips.h>
00033 
00034 //# Includes
00035 #include <string>
00036 
00037 using std::string;
00038 
00039 #include <casa/iosstrfwd.h>
00040 #include <casa/sstream.h>
00041 
00042 namespace casa { //# NAMESPACE CASA - BEGIN
00043 
00044 //# Forward Declarations
00045 class String;
00046 class RegexBase;
00047 
00048 // <summary> SubString help class to be used in at, before, ... </summary>
00049 // <synopsis>
00050 // The SubString class can only be used by the String class to be able to
00051 // operate the aips++ defined replacement operators at, before, after, through,
00052 // from. The class is used transparently in operations like:
00053 // <srcblock>
00054 //      string.at(2,3) = "five";
00055 // </srcblock> 
00056 // If the SubString starts at a position outside the length of the
00057 // original string (like e.g. in after(1000000)), a zero length string is
00058 // created (not an exception thrown like in standard string operations).
00059 // </synopsis>
00060 
00061 class SubString {
00062 public:
00063   //# Friends
00064   friend class String;
00065   // Make a string
00066   operator const string() const { return string(ref_p, pos_p, len_p); }
00067   // Assignment
00068   // <group>
00069   SubString &operator=(const SubString &str);
00070   SubString &operator=(const String &str);
00071   SubString &operator=(const Char *s);
00072   SubString &operator=(const Char c);
00073   // </group>
00074   // Get as (const) C array
00075   const Char *chars() const;
00076   // Obtain length
00077   string::size_type length() const { return len_p; }
00078 
00079 private:
00080   //# Constructors
00081   // Constructor (there are no public constructors)
00082   SubString(const string &str, string::size_type pos,
00083             string::size_type len);
00084   //# Data
00085   // Referenced string
00086   const string &ref_p;
00087   // Start of sub-string
00088   string::size_type pos_p;
00089   // Length of sub-string
00090   string::size_type len_p;
00091 };
00092 
00093 // <summary> 
00094 // String: the storage and methods of handling collections of characters.
00095 // </summary>
00096 
00097 // <use visibility=export>
00098 
00099 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tString.cc" demos="">
00100 // </reviewed>
00101 
00102 // <prerequisite>
00103 //   <li> RegexBase - the regular expressions class
00104 //   <li> the std string class
00105 // </prerequisite>
00106 //
00107 // <etymology>
00108 // The String class name is a continuation of the "C" language custom of
00109 // refering to collections of characters as "strings of characters".
00110 // </etymology>
00111 //
00112 // <synopsis> 
00113 // The String class is the aips++ implementation of a string class. It is
00114 // closely based on the standard library string class, and all operations
00115 // and behaviour of strings as defined in the standard are available for
00116 // a String. The only difference is the extension with additional functions
00117 // in the aips++ String class as compared to the standard string class.
00118 // 
00119 // The String class may be instantiated in many ways:
00120 // <ol>
00121 // <li> A single character - <src>String myChar('C');</src>
00122 // <li> A Char* argument - <src>String myWord("Yowza");</src>
00123 // <li> The first n chararcters of a pre-existing string - 
00124 // <src>String myFoo("fooey", 3);</src>
00125 // </ol> As well as the copy and default constructors and iterator based ones.
00126 //
00127 // A String may be concatinated with another object (String, or 
00128 // char*) with either prepending or postpending.  A search for the position
00129 // of a character within a String may return its position, a Bool that it
00130 // is contained within or a Bool confirming your guess at the character's 
00131 // position is correct.  A check of the frequency of occurance of a string
00132 // within a String will return the number of occurances.  
00133 // 
00134 // Strings may be extracted from Strings at, before, through, from and 
00135 // after a starting position within the String.  Deletion of characters is
00136 // possible after a given position within the String. Global substitution
00137 // of characters within a String is provided, as well.  Splitting of Strings 
00138 // into a carray of Strings is possible, based upon a given separator 
00139 // character, with a return value of the number of elements split.  The joining
00140 // together of the elements of an array of Strings into one String is possible.
00141 // 
00142 // Finally, transformations of case and conversions of type are provided. 
00143 //
00144 // The standard string class provides the following functionality:
00145 // <ol>
00146 // <li> Construction from (part of) String, (part of) Char*,
00147 //              (repeating) Char, iterator pair.
00148 // <li> Assignment from String, Char*, Char
00149 // <li> Iterators: begin() and end(); rbegin() and rend() (Note: gcc reverse
00150 //              iterators still weak)
00151 // <li> Capacity: size, length, max_size, resize, capacity, reserve, clear,
00152 //              empty
00153 // <li> Special size: String::size_type, with indicator: String::npos
00154 // <li> Element access: [pos] and at(pos) (both const and non-const)
00155 // <li> Modifiers: += of String, Char*, Char; append of (part of) String,
00156 //              Char*, Char and iterator defined; assign() of (part of)
00157 //              String, Char* and (repeating) Char and iterator;
00158 //              insertion of same; replacing of same; erase of part of
00159 //              String; a copy and a swap.
00160 // <li> C-string: get Char* with c_str() or data() and get the relevant
00161 //              Allocator used (Note: not fully supported in gcc)
00162 // <li> Operations: find, rfind, find_first_of, find_last_of, find_first_not_of,
00163 //              find_last_not_of; substr (Note only readable substring);
00164 //              compare with (part of) String, Char*
00165 // <li> Globals: Addition operators for String, Char*, Char; all comparison
00166 //              operators for String and Char*; getline; input and output
00167 //              stream operators
00168 // <li> Typedef: All relevant typedefs for standard containers and iterator
00169 //              handling
00170 // </ol>
00171 // The aips++ addition are:
00172 // <ol>
00173 // <li> To standard: some Char function arguments where appropriate; RegexBase
00174 //              arguments in search like methods.
00175 // <li> Substring additions: at, before, after, from, through functions taking
00176 //              search String, Char* as arguments can give (hidden) substrings
00177 //              which can be assigned (as in <src> at(1,2) = ";"</src>)
00178 // <li> Methods: prepend (in addition to standard append); del (as erase);
00179 //              global substitution of String and patterns;
00180 //               freq (count of occurance); split/join of strings at separator
00181 //              or pattern; upcase, downcase, reverse;
00182 //               common_suffix and _prefix; replicate; case insensitive
00183 //              compare; creation from stream
00184 // </ol>
00185 
00186 // </synopsis> 
00187 //
00188 // <example>
00189 // <srcblock>
00190 // // Let's start with a simple string.
00191 // String myString("the time");
00192 // // add some more on the end...
00193 // myString += " for all good men";
00194 // // prepend some on the front...
00195 // myString.prepend("Now is ");
00196 // // do some concatination...
00197 // String evenMore;
00198 // evenMore += myString + " to come to";
00199 // // do some three way concatination
00200 // String allKeys, finishIt(" their country.");
00201 // allKeys = evenMore + "the aid of" + finishIt;
00202 // // find the spot where we put something earlier
00203 // String::size_type position = allKeys.index(finishIt);
00204 // // find if the word is in the String...
00205 // Bool query = myString.contains("good men");
00206 // // ask if the position we think is true is correct...
00207 // Bool answer = allKeys.matches(finishIt, position);
00208 // // How many spaces are in our phrase?
00209 // Int spacesCount = allKeys.freq(" ");
00210 // </srcblock>
00211 // </example>
00212 //
00213 // <motivation>
00214 // The String class eases the handling of characters within the AIPS++ 
00215 // environment.
00216 // </motivation>
00217 //
00218 // <todo asof=2000/12/05">
00219 //   <li> if old string disappeared; remove the alloc() call.
00220 //   <li> add more tests (for string methods) when old String disappears
00221 // </todo>
00222 
00223 class String : public string {
00224 
00225  public:
00226 
00227   //# Basic container typedefs
00228   typedef string::traits_type           traits_type;
00229   typedef string::value_type            value_type;
00230   typedef string::allocator_type        allocator_type;
00231   typedef string::size_type             size_type;
00232   typedef string::difference_type       difference_type;
00233 
00234   typedef string::reference             reference;
00235   typedef string::const_reference       const_reference;
00236   typedef string::pointer               pointer;
00237   typedef string::const_pointer         const_pointer;
00238 
00239   typedef string::iterator iterator;
00240   typedef string::const_iterator const_iterator;
00241   typedef string::reverse_iterator reverse_iterator;
00242   typedef string::const_reverse_iterator const_reverse_iterator;
00243   //# Next cast necessary to stop warning in gcc
00244   static const size_type npos = static_cast<size_type>(-1);
00245 
00246   //# Constructors
00247   // Default constructor
00248   String() : string("") {}
00249   // Construct from std string
00250   // Construct from (part of) other string: acts as copy constructor
00251   // <thrown>
00252   // <li> out_of_range if pos > str.size()
00253   // </thrown>
00254   String(const string& str, size_type pos=0, size_type n=npos) :
00255     string(str, pos, n) {}
00256   // Construct from char* with given length
00257   // <thrown>
00258   // <li> length_error if n == npos
00259   // </thrown>
00260   String(const Char* s, size_type n) : string(s, n) {}
00261   // Construct from char array
00262   String(const Char* s) : string(s) {}
00263   // Construct from a single char (repeated n times)
00264   // <thrown>
00265   // <li> length_error if n == npos
00266   // </thrown>
00267   String(size_type n, Char c) : string(n, c) {}
00268   // Construct from iterator
00269   template<class InputIterator>
00270     String(InputIterator begin, InputIterator end) : string(begin, end) {}
00271   // From single char (** aips++ addition).
00272   // <note role=warning> Note that there is no automatic Char-to-String
00273   // conversion available. This stops inadvertent conversions of
00274   // integer to string. </note>
00275   explicit String(Char c) : string(1, c) {}
00276   // Construct from a SubString
00277   String(const SubString &str) : string(str.ref_p, str.pos_p, str.len_p) {}
00278   // Construct from a stream.
00279   String(ostringstream &os);
00280 
00281   //# Destructor
00282   // Destructor
00283   ~String() {}
00284 
00285   //# Operators
00286   // Assignments (they are all deep copies according to standard)
00287   // <group>
00288   String& operator=(const string& str) {
00289     return static_cast<String&>(string::operator=(str)); }
00290   String& operator=(const SubString &str) {
00291     return (*this = String(str)); }
00292   String& operator=(const Char* s) {
00293     return static_cast<String&>(string::operator=(s)); }
00294   String& operator=(Char c) {
00295     return static_cast<String&>(string::operator=(c)); }
00296   // </group>
00297   // ** aips++ addition: synonym for at(pos, len)
00298   SubString operator()(size_type pos, size_type len);
00299   // Concatenate
00300   // <group>
00301   String& operator+=(const string& str) {
00302     return static_cast<String&>(string::operator+=(str)); }
00303   String& operator+=(const Char* s) {
00304     return static_cast<String&>(string::operator+=(s)); }
00305   String& operator+=(Char c) {
00306     return static_cast<String&>(string::operator+=(c)); }
00307   // </group>
00308 
00309   // Indexing. The standard version is undefined if <src>pos > size()</src>, or 
00310   // <src>pos >= size()</src> for non-const version. 
00311   // <note role=warning> The const_reference version needs the at() version
00312   // for the gcc compiler: no const [] exists. </note>
00313   // <group>
00314   const_reference operator[](size_type pos) const {
00315     return string::at(pos); }
00316   reference operator[](size_type pos) {
00317     return string::operator[](pos); }
00318   // *** aips++ addition
00319   // <group>
00320   const_reference elem(size_type pos) const {
00321     return string::at(pos); }
00322   Char firstchar() const { return at(static_cast<size_type>(0)); }
00323   Char lastchar() const { return at(length()-1); }
00324   // </group>
00325   // </group>
00326 
00327   //# Member functions
00328   // Iterators
00329   // <group>
00330   iterator begin() { return string::begin(); }
00331   const_iterator begin() const { return string::begin(); }
00332   iterator end() { return string::end(); }
00333   const_iterator end() const { return string::end(); }
00334   reverse_iterator rbegin() { return string::rbegin(); }
00335   const_reverse_iterator rbegin() const { return string::rbegin(); }
00336   reverse_iterator rend() { return string::rend(); }
00337   const_reverse_iterator rend() const { return string::rend(); }
00338   // </group>
00339 
00340   // Capacity, size
00341   // <group>
00342   size_type size() const { return string::size(); }
00343   size_type length() const { return string::length(); }
00344   size_type max_size() const { return string::max_size(); }
00345   size_type capacity() const { return string::capacity(); }
00346   // ** aips++ addition -- works as a capacity(n) -- Note Int
00347   Int allocation() const { return string::capacity(); } 
00348   // </group>
00349 
00350   // Resize by truncating or extending with copies of <src>c</src> (default 
00351   // Char())
00352   // <thrown>
00353   // <li> length_error if n > max_size()
00354   // <li> length_error if res_arg > max_size()
00355   // </thrown>
00356   // <group>
00357   // <note role=tip> The reserve length given is non-binding on the
00358   // implementation </note>
00359   String& resize(size_type n) {
00360     string::resize(n); return *this; }
00361   String& resize(size_type n, Char c) {
00362     string::resize(n, c); return *this; }
00363   String& reserve(size_type res_arg = 0) {
00364     string::reserve(res_arg); return *this; }
00365   // ** aips++ addition -- works as a resize(n)
00366   void alloc(size_type n) { string::resize(n); }
00367   // </group>
00368 
00369   // Clear the string
00370   // <note role=warning> clear() executed as erase() due to missing clear() in
00371   // gcc </note> 
00372   void clear() { string::erase(begin(), end()); }
00373 
00374   // Test for empty
00375   Bool empty() const { return string::empty(); }
00376 
00377   // Addressing
00378   // <thrown>
00379   // <li> out_of_range if pos >= size()
00380   // </thrown>
00381   // <group>
00382   const_reference at(size_type n) const { return string::at(n); }
00383   reference at(size_type n) { return string::at(n); }
00384   // </group>
00385 
00386   // Append
00387   // <thrown>
00388   // <li> out_of_range if pos > str.size()
00389   // <li> length_error if new size() >= npos
00390   // </thrown>
00391   // <note role=warning> The standard has a 
00392   // <src>void push_back(const Char) </src> which is completely undefined. It
00393   // probably is a remnant of the full list of container functions pop/push
00394   // back/front. </note>
00395   // <group>
00396   String& append(const string& str) {
00397     return static_cast<String&>(string::append(str)); }
00398   String& append(const string& str, size_type pos, size_type n) {
00399     return static_cast<String&>(string::append(str, pos, n)); }
00400   String& append(const Char* s, size_type n) {
00401     return static_cast<String&>(string::append(s, n)); }
00402   String& append(const Char* s) {
00403     return static_cast<String&>(string::append(s)); }
00404   String& append(size_type n, Char c) {
00405     return static_cast<String&>(string::append(n, c)); }
00406   template<class InputIterator>
00407     String& append(InputIterator first, InputIterator last) {
00408     return static_cast<String&>(string::append(first, last)); }
00409   // ** aips++ addition
00410   String& append(Char c) {
00411     return static_cast<String&>(string::append(1, c)); }
00412   // </group>
00413 
00414   // Assign
00415   // <thrown>
00416   // <li> out_of_range if pos > str.size()
00417   // </thrown>
00418   // <group>
00419   String& assign(const string& str) {
00420     return static_cast<String&>(string::assign(str)); }
00421   String& assign(const string& str, size_type pos, size_type n) {
00422     return static_cast<String&>(string::assign(str, pos, n)); }
00423   String& assign(const Char* s, size_type n) {
00424     return static_cast<String&>(string::assign(s, n)); }
00425   String& assign(const Char* s) {
00426     return static_cast<String&>(string::assign(s)); }
00427   String& assign(size_type n, Char c) {
00428     return static_cast<String&>(string::assign(n, c)); }
00429   template<class InputIterator>
00430     String& assign(InputIterator first, InputIterator last) {
00431     return static_cast<String&>(string::assign(first, last)); }
00432   // ** aips++ addition
00433   String& assign(Char c)  {
00434     return static_cast<String&>(string::assign(1, c)); }
00435   // </group>
00436 
00437   // Insert
00438   // <thrown>
00439   // <li> out_of_range if pos1 > str.size() or pos2 > str.size()
00440   // <li> length_error if new size() >= npos
00441   // </thrown>
00442   // <group>
00443   String& insert(size_type pos1, const string& str) {
00444     return static_cast<String&>(string::insert(pos1, str)); }
00445   String& insert(size_type pos1, const string& str,
00446                  size_type pos2, size_type n) {
00447     return static_cast<String&>(string::insert(pos1, str, pos2, n)); }
00448   String& insert(size_type pos, const Char* s, size_type n) {
00449     return static_cast<String&>(string::insert(pos, s, n)); }
00450   String& insert(size_type pos, const Char* s) {
00451     return static_cast<String&>(string::insert(pos, s)); }
00452   String& insert(size_type pos, size_type n, Char c) {
00453     return static_cast<String&>(string::insert(pos, n, c)); }
00454   // ** aips++ addition
00455   String& insert(size_type pos, Char c) {
00456     return static_cast<String&>(string::insert(pos, 1, c)); }
00457 
00458   iterator insert(iterator p, Char c) {
00459     return string::insert(p, c); }
00460   void insert(iterator p, size_type n, Char c) {
00461     string::insert(p, n, c); }
00462   template<class InputIterator>
00463     void insert(iterator p, InputIterator first, InputIterator last) {
00464     string::insert(p, first, last); }
00465   // ** aips++ additions
00466   // <group>
00467   String& insert(iterator p, const string& str) {
00468     return static_cast<String&>(string::insert(p-begin(), str)); }
00469   String& insert(iterator p, const Char* s, size_type n) {
00470     return static_cast<String&>(string::insert(p-begin(), s, n)); }
00471   String& insert(iterator p, const Char* s) {
00472     return static_cast<String&>(string::insert(p-begin(), s)); }
00473   // </group>
00474   // </group>
00475 
00476   // Compare. Returns 0 if strings equal and of equal size; else positive if
00477   // str larger or longer; else negative.
00478   // <note role=warning> The gcc compiler does not have the proper standard
00479   // compare functions. Hence they are locally implemented. </note>
00480   // <group>
00481   Int compare(const string& str) const {        
00482     return string::compare(str); }
00483   Int compare(size_type pos1, size_type n1, const string& str) const {
00484     return String(*this, pos1, n1).compare(str); }
00485   Int compare(size_type pos1, size_type n1, const string& str,
00486               size_type pos2, size_type n2) const {
00487     return String(*this, pos1, n1).compare(String(str, pos2, n2)); }
00488   Int compare(const Char* s) const {
00489     return string::compare(s); }
00490   Int compare(size_type pos1, size_type n1, const Char* s,
00491               size_type n2=npos) const {
00492     return String(*this, pos1, n1).compare(String(s, n2)); }
00493   // </group>
00494 
00495   // Erase
00496   // <group>
00497   String& erase(size_type pos, size_type n = npos) {
00498     return static_cast<String&>(string::erase(pos, n)); }
00499   iterator erase(iterator position) {
00500     return string::erase(position); }
00501   iterator erase(iterator first, iterator last) {
00502     return string::erase(first, last); }
00503   // </group>
00504 
00505   // Replace
00506   // <thrown>
00507   // <li> out_of_range if pos1 > str.size() or pos2 > str.size()
00508   // <li> length_error if new size() > npos
00509   // </thrown>
00510   // <group>
00511   String& replace(size_type pos1, size_type n1, const string& str) {
00512     return static_cast<String&>(string::replace(pos1, n1, str)); }
00513   String& replace(size_type pos1, size_type n1, const string& str,
00514                   size_type pos2, size_type n2) {
00515     return static_cast<String&>(string::replace(pos1, n1, str, pos2, n2)); }
00516   String& replace(size_type pos, size_type n1, const Char* s, size_type n2) {
00517     return static_cast<String&>(string::replace(pos, n1, s, n2)); }
00518   String& replace(size_type pos, size_type n1, const Char* s) {
00519     return static_cast<String&>(string::replace(pos, n1, s)); }
00520   String& replace(size_type pos, size_type n1, size_type n2, Char c) {
00521     return static_cast<String&>(string::replace(pos, n1, n2, c)); }
00522   // ** aips++ addition
00523   String& replace(size_type pos, size_type n1, Char c) {
00524     return static_cast<String&>(string::replace(pos, n1, 1, c)); }
00525   String& replace(iterator i1, iterator i2, const string& str) {
00526     return static_cast<String&>(string::replace(i1, i2, str)); }
00527   String& replace(iterator i1, iterator i2, const Char* s, size_type n) {
00528     return static_cast<String&>(string::replace(i1, i2, s, n)); }
00529   String& replace(iterator i1, iterator i2, const Char* s) {
00530     return static_cast<String&>(string::replace(i1, i2, s)); }
00531   String& replace(iterator i1, iterator i2, size_type n, Char c) {
00532     return static_cast<String&>(string::replace(i1, i2, n, c)); }
00533   // ** aips++ addition
00534   String& replace(iterator i1, iterator i2, Char c) {
00535     return static_cast<String&>(string::replace(i1, i2, 1, c)); }
00536   template<class InputIterator>
00537     String& replace(iterator i1, iterator i2, InputIterator j1, 
00538                     InputIterator j2) {
00539     return static_cast<String&>(string::replace(i1, i2, j1, j2)); }
00540   // </group>
00541 
00542   // Copy
00543   // <thrown>
00544   // <li> out_of_range if pos > size()
00545   // </thrown>
00546   size_type copy(Char* s, size_type n, size_type pos = 0) const {
00547     return string::copy(s, n, pos); }
00548 
00549   // Swap
00550   void swap(string& s) { string::swap(s); }
00551 
00552   // Get char array
00553   // <group>
00554   // As a proper null terminated C-string
00555   const Char *c_str() const { return string::c_str(); }
00556   // As pointer to char array 
00557   const Char *data() const { return string::data(); }
00558   // ** aips++ synonym
00559   const Char *chars() const { return string::c_str(); }
00560   // </group>
00561 
00562   // Get allocator used
00563   // <note role=warning> gcc has no get_allocator() </note>
00564   allocator_type get_allocator() const { return string::allocator_type(); }
00565 
00566   // Get a sub string
00567   // <thrown>
00568   // <li> out_of_range if pos > size()
00569   // </thrown>
00570   String substr(size_type pos=0, size_type n=npos) const {
00571     return String(*this, pos, n); }
00572 
00573   // Search functions. Returns either npos (if not found); else position.
00574   // <note role=warning> The RegexBase ones are ** aips++ additions</note>
00575   // <group>
00576   size_type find(const string &str, size_type pos=0) const {
00577     return string::find(str, pos); }
00578   size_type find(const Char *s, size_type pos=0) const {
00579     return string::find(s, pos); }
00580   size_type find(const Char *s, size_type pos, size_type n) const {
00581     return string::find(s, pos, n); }
00582   size_type find(Char c, size_type pos=0) const {
00583     return string::find(c, pos); }
00584   size_type find(const RegexBase &r, size_type pos=0) const;
00585   size_type rfind(const string &str, size_type pos=0) const {
00586     return string::find(str, pos); }
00587   size_type rfind(const Char *s, size_type pos=0) const {
00588     return string::rfind(s, pos); }
00589   size_type rfind(const Char *s, size_type pos, size_type n) const {
00590     return string::rfind(s, pos, n); }
00591   size_type rfind(Char c, size_type pos=0) const {
00592     return string::rfind(c, pos); }
00593   size_type rfind(const RegexBase &r, size_type pos=0) const;
00594   size_type find_first_of(const string &str, size_type pos=0) const {
00595     return string::find_first_of(str, pos); }
00596   size_type find_first_of(const Char *s, size_type pos=0) const {
00597     return string::find_first_of(s, pos); }
00598   size_type find_first_of(const Char *s, size_type pos, size_type n) const {
00599     return string::find_first_of(s, pos, n); }
00600   size_type find_first_of(Char c, size_type pos=0) const {
00601     return string::find_first_of(c, pos); }
00602   size_type find_last_of(const string &str, size_type pos=0) const {
00603     return string::find_last_of(str, pos); }
00604   size_type find_last_of(const Char *s, size_type pos=0) const {
00605     return string::find_last_of(s, pos); }
00606   size_type find_last_of(const Char *s, size_type pos, size_type n) const {
00607     return string::find_last_of(s, pos, n); }
00608   size_type find_last_of(Char c, size_type pos=0) const {
00609     return string::find_last_of(c, pos); }
00610   size_type find_first_not_of(const string &str, size_type pos=0) const {
00611     return string::find_first_not_of(str, pos); }
00612   size_type find_first_not_of(const Char *s, size_type pos=0) const {
00613     return string::find_first_not_of(s, pos); }
00614   size_type find_first_not_of(const Char *s, size_type pos, size_type n) const {
00615     return string::find_first_not_of(s, pos, n); }
00616   size_type find_first_not_of(Char c, size_type pos=0) const {
00617     return string::find_first_not_of(c, pos); }
00618   size_type find_last_not_of(const string &str, size_type pos=0) const {
00619     return string::find_last_not_of(str, pos); }
00620   size_type find_last_not_of(const Char *s, size_type pos=0) const {
00621     return string::find_last_not_of(s, pos); }
00622   size_type find_last_not_of(const Char *s, size_type pos, size_type n) const {
00623     return string::find_last_not_of(s, pos, n); }
00624   size_type find_last_not_of(Char c, size_type pos=0) const {
00625     return string::find_last_not_of(c, pos); }
00626   // </group>
00627   
00628   // Containment. ** aips++ addition
00629   // <group name=contains>
00630   Bool contains(Char c) const {
00631     return (find(c) != npos); }
00632   Bool contains(const string &str) const {
00633     return (find(str) != npos); }
00634   Bool contains(const Char *s) const {
00635     return (find(s) != npos); }
00636   Bool contains(const RegexBase &r) const;
00637   // </group>
00638   // Containment after (or before if pos negative) pos. ** aips++ addition
00639   // <group name=contains_pos>
00640   Bool contains(Char c, Int pos) const;
00641   Bool contains(const string &str, Int pos) const;
00642   Bool contains(const Char *s, Int pos) const;
00643   Bool contains(const RegexBase &r, Int pos) const;
00644   // </group>
00645 
00646   // Matches entire string from pos
00647   // (or till pos if negative pos). ** aips++ addition
00648   // <group name=matches>
00649   Bool matches(const string &str, Int pos = 0) const;
00650   Bool matches(Char c, Int pos = 0) const {
00651     return matches(String(c), pos); };
00652   Bool matches(const Char *s, Int pos = 0) const {
00653     return matches(String(s), pos); };
00654   Bool matches(const RegexBase &r, Int pos = 0) const;
00655   // </group>
00656 
00657   // Concatenate by prepending the argument onto String. ** aips++ addition
00658   // <group name=concatenation_method>
00659   void prepend(const string &str); 
00660   void prepend(const Char *s);
00661   void prepend(Char c);
00662   // </group> 
00663 
00664   // Return the position of the target in the string or npos for failure.
00665   // ** aips++ addition
00666   // <group name=index>
00667   size_type index(Char c, Int startpos = 0) const {
00668     return ((startpos >= 0) ? find(c, startpos) :
00669             rfind(c, length() + startpos - 1)); }
00670   size_type index(const string &str, Int startpos = 0) const { 
00671     return ((startpos >= 0) ? find(str, startpos) :
00672             rfind(str, length() + startpos - str.length())); }
00673   size_type index(const Char *s, Int startpos = 0) const {
00674     return ((startpos >= 0) ? find(s, startpos) :
00675             rfind(s, length() + startpos - traits_type::length(s))); }
00676   size_type index(const RegexBase &r, Int startpos = 0) const;
00677   // </group>
00678 
00679   //  Return the number of occurences of target in String. ** aips++ addition
00680   // <group name=freq>
00681   Int freq(Char c) const; 
00682   Int freq(const string &str) const;
00683   Int freq(const Char *s) const;
00684   // </group>
00685 
00686   // Extract the string "at" the argument's position. ** aips++ addition
00687   // <group name=at>
00688   SubString at(size_type pos, size_type len);
00689   String at(size_type pos, size_type len) const {
00690     return String(*this, pos, len); }
00691   SubString at(const string &str, Int startpos = 0);
00692   String at(const string &str, Int startpos = 0) const;
00693   SubString at(const Char *s, Int startpos = 0);
00694   String at(const Char *s, Int startpos = 0) const;
00695   SubString at(Char c, Int startpos = 0);
00696   String at(Char c, Int startpos = 0) const;
00697   SubString at(const RegexBase &r, Int startpos = 0); 
00698   String at(const RegexBase &r, Int startpos = 0) const; 
00699   // Next ones for overloading reasons. 
00700   // <note role=tip> It is better to use the <src>substr()</src> method
00701   // in stead. </note>
00702   // <group>
00703   SubString at(Int pos, Int len) {
00704     return at(static_cast<size_type>(pos), static_cast<size_type>(len));
00705   };
00706   String at(Int pos, Int len) const {
00707     return at(static_cast<size_type>(pos), static_cast<size_type>(len));
00708   };
00709   SubString at(Int pos, size_type len) {
00710     return at(static_cast<size_type>(pos), len);
00711   };
00712   String at(Int pos, size_type len) const {
00713     return at(static_cast<size_type>(pos), len);
00714   };
00715   // </group>
00716   // </group>
00717 
00718   // Start at startpos and extract the string "before" the argument's 
00719   // position, exclusive. ** aips++ addition
00720   // <group name=before>
00721   SubString before(size_type pos);
00722   SubString before(const string &str, Int startpos = 0);
00723   SubString before(const Char *s, Int startpos = 0);
00724   SubString before(Char c, Int startpos = 0);
00725   SubString before(const RegexBase &r, Int startpos = 0);
00726   // Next one for overloading reasons
00727   SubString before(Int pos) {
00728     return before(static_cast<size_type>(pos)); };    
00729   // </group>
00730 
00731   // Start at startpos and extract the SubString "through" to the argument's 
00732   // position, inclusive. ** aips++ addition
00733   // <group name=through>
00734   SubString through(size_type pos);
00735   SubString through(const string &str, Int startpos = 0);
00736   SubString through(const Char *s, Int startpos = 0);
00737   SubString through(Char c, Int startpos = 0);
00738   SubString through(const RegexBase &r, Int startpos = 0);
00739   // Next one for overloading reasons
00740   SubString through(Int pos) {
00741     return through(static_cast<size_type>(pos)); }
00742   // </group>
00743 
00744   // Start at startpos and extract the SubString "from" the argument's 
00745   // position, inclusive, to the String's end. ** aips++ addition
00746   // <group name=from>
00747   SubString from(size_type pos);
00748   SubString from(const string &str, Int startpos = 0);
00749   SubString from(const Char *s, Int startpos = 0);
00750   SubString from(Char c, Int startpos = 0);
00751   SubString from(const RegexBase &r, Int startpos = 0);
00752   // Next one for overloading reasons
00753   SubString from(Int pos) {
00754     return from(static_cast<size_type>(pos));
00755   };
00756   // </group>
00757 
00758   // Start at startpos and extract the SubString "after" the argument's 
00759   // position, exclusive, to the String's end. ** aips++ addition
00760   // <group name=after>
00761   SubString after(size_type pos);
00762   SubString after(const string &str, Int startpos = 0);
00763   SubString after(const Char *s, Int startpos = 0);
00764   SubString after(Char c, Int startpos = 0);
00765   SubString after(const RegexBase &r, Int startpos = 0);
00766   // Next one for overloading reasons
00767   SubString after(Int pos) {
00768     return after(static_cast<size_type>(pos));
00769   };
00770   // </group>
00771 
00772   // Maybe forget some. ** aips++ addition
00773   // <group>
00774   // internal transformation to reverse order of String.
00775   void reverse();
00776   // internal transformation to capitalization of String.
00777   void capitalize();
00778   // internal transformation to uppercase of String
00779   void upcase();
00780   // internal transformation to lowercase of String
00781   void downcase();
00782   // </group>
00783 
00784   // Delete len chars starting at pos. ** aips++ addition
00785   void del(size_type pos, size_type len);
00786 
00787   // Delete the first occurrence of target after startpos. ** aips++ addition
00788   //<group name=del_after>
00789   void del(const string &str, size_type startpos = 0);
00790   void del(const Char *s, size_type startpos = 0);
00791   void del(Char c, size_type startpos = 0);
00792   void del(const RegexBase &r, size_type startpos = 0);
00793   // Overload problem
00794   void del(Int pos, Int len) {
00795     del(static_cast<size_type>(pos), static_cast<size_type>(len)); }
00796   //</group> 
00797 
00798   // Global substitution: substitute all occurrences of pat with repl, and
00799   // return the number of replacements.
00800   // ** aips++ addition
00801   //<group name=gsub>
00802   Int gsub(const string &pat, const string &repl);
00803   Int gsub(const Char *pat, const string &repl);
00804   Int gsub(const Char *pat, const Char *repl);
00805   Int gsub(const RegexBase &pat, const string &repl);
00806   //</group>
00807 
00808   // Convert a integer to a String. This is a convenience function. Use the
00809   // ostringstream class for conversion of floating point data types
00810   // or more sophisticated formatting options.
00811   // <group>
00812   static String toString(Int value);
00813   static String toString(uInt value);
00814   static String toString(Double value);
00815   // </group>
00816 
00817 private:
00818   // Helper functions for at, before etc
00819   // <group>
00820   SubString _substr(size_type first, size_type l) {
00821     return SubString(*this, first, l); }
00822   // </group>
00823 };
00824 
00825 // <summary>
00826 // Global concatenation operators
00827 // </summary>
00828 
00829 // The global concatenation operators
00830 // <group name=concatenator>
00831 inline String operator+(const String &lhs, const String &rhs) {
00832   String str(lhs); str.append(rhs); return str; }
00833 inline String operator+(const Char *lhs, const String &rhs) {
00834   String str(lhs); str.append(rhs); return str; }
00835 inline String operator+(Char lhs, const String &rhs) {
00836   String str(lhs); str.append(rhs); return str; }
00837 inline String operator+(const String &lhs, const Char *rhs) {
00838   String str(lhs); str.append(rhs); return str; }
00839 inline String operator+(const String &lhs, Char rhs) {
00840   String str(lhs); str.append(rhs); return str; }
00841 // </group>
00842 
00843 // <summary>
00844 // Global comparison operators
00845 // </summary>
00846 
00847 // The global comparison operators
00848 // <group name=comparitor>
00849 inline Bool operator==(const String &x, const String &y) {
00850   return x.compare(y) == 0; }
00851 inline Bool operator!=(const String &x, const String &y) {
00852   return x.compare(y) != 0; }
00853 inline Bool operator>(const String &x, const String &y) {
00854   return x.compare(y) > 0; }
00855 inline Bool operator>=(const String &x, const String &y) {
00856   return x.compare(y) >= 0; }
00857 inline Bool operator<(const String &x, const String &y) {
00858   return x.compare(y) < 0; }
00859 inline Bool operator<=(const String &x, const String &y) {
00860   return x.compare(y) <= 0; }
00861 inline Bool operator==(const String &x, const Char *t) {
00862   return x.compare(t) == 0; }
00863 inline Bool operator!=(const String &x, const Char *t) {
00864   return x.compare(t) != 0; }
00865 inline Bool operator>(const String &x, const Char *t) {
00866   return x.compare(t) > 0; }
00867 inline Bool operator>=(const String &x, const Char *t) {
00868   return x.compare(t) >= 0; }
00869 inline Bool operator<(const String &x, const Char *t) {
00870   return x.compare(t) < 0; }
00871 inline Bool operator<=(const String &x, const Char *t) {
00872   return x.compare(t) <= 0; }
00873 inline Bool operator==(const String &x, const Char t) {
00874   return x.compare(String(t)) == 0; }
00875 inline Bool operator!=(const String &x, const Char t) {
00876   return x.compare(String(t)) != 0; }
00877 inline Bool operator>(const String &x, const Char t) {
00878   return x.compare(String(t)) > 0; }
00879 inline Bool operator>=(const String &x, const Char t) {
00880   return x.compare(String(t)) >= 0; }
00881 inline Bool operator<(const String &x, const Char t) {
00882   return x.compare(String(t)) < 0; }
00883 inline Bool operator<=(const String &x, const Char t) {
00884   return x.compare(String(t)) <= 0; }
00885 // ** aips++ additions of global compares. Returns 0 if equal; lt or gt 0 if
00886 // strings unequal or of unequal lengths.
00887 // <group>
00888 inline Int compare(const string &x, const string &y) {
00889   return x.compare(y); }
00890 inline Int compare(const string &x, const Char *y) {
00891   return x.compare(y); }
00892 inline Int compare(const string &x, const Char y) {
00893   return x.compare(String(y)); }
00894 // this version ignores case. ** aips++ addition. Result is 0 if equal
00895 // strings of equal lengths; else lt or gt 0 to indicate differences.
00896 Int fcompare(String x, String y);
00897 // </group>
00898 // </group>
00899 
00900 // <summary> Splitting </summary>
00901 // Global function which splits the String into string array res at separator
00902 // and returns the number of elements.  ** aips++ addition
00903 // <group name=split>
00904 Int split(const string &str, string res[], Int maxn,
00905           const string &sep);
00906 Int split(const string &str, string res[], Int maxn,
00907           const Char sep);
00908 Int split(const string &str, string res[], Int maxn,
00909           const RegexBase &sep);
00910 //</group> 
00911 
00912 // <summary> Some general functions </summary>
00913 // Functions to find special patterns, join and replicate
00914 // <group name=common>
00915 String common_prefix(const string &x, const string &y, 
00916                      Int startpos = 0);
00917 String common_suffix(const string &x, const string &y, 
00918                      Int startpos = -1);
00919 String replicate(Char c, String::size_type n);
00920 String replicate(const string &str, String::size_type n);
00921 String join(string src[], Int n, const string &sep);
00922 // </group>
00923 
00924 // <summary> Casing and related functions </summary>
00925 // Case conversion and rearrangement functions
00926 // <group name=case>
00927 // Global function which returns a transformation to reverse order of String.
00928 String reverse(string str);
00929 // Global function  which returns a transformation to uppercase of String.
00930 String upcase(string str);
00931 // Global function  which returns a transformation to lowercase of String.
00932 String downcase(string str);
00933 // Global function  which returns a transformation to capitalization of 
00934 // String.
00935 String capitalize(string str);
00936 // </group>
00937 
00938 // <summary> IO </summary>
00939 // <group name=io>
00940 // Output
00941 ostream &operator<<(ostream &s, const String &x);
00942 // </group>
00943 
00944 //# Inlines
00945 inline SubString::SubString(const string &str, string::size_type pos,
00946                             string::size_type len) :
00947   ref_p(str), pos_p((pos > str.length()) ? str.length() : pos),
00948   len_p((len == string::npos || pos_p+len > str.length()) ?
00949         str.length()-pos_p : len) {}
00950 
00951 inline SubString String::operator()(size_type pos, size_type len) {
00952   return at(pos, len); }
00953 inline  const Char *SubString::chars() const {
00954   return String(*this).c_str(); }
00955 
00956 inline Bool String::contains(Char c, Int pos) const {
00957   return (index(c, pos) != npos); }
00958 inline Bool String::contains(const string &str, Int pos) const {
00959   return (index(str, pos) != npos); }
00960 inline Bool String::contains(const Char *s, Int pos) const {
00961   return (index(s, pos) != npos); }
00962 inline Bool String::contains(const RegexBase &r, Int pos) const {
00963   return (index(r, pos) != npos); }
00964 
00965 inline Bool String::matches(const string &str, Int pos) const {
00966   return ((pos < 0) ? index(str, pos) == 0 :
00967           length() != 0 && str.length() != 0 &&
00968           length() == pos+str.length() &&
00969           static_cast<size_type>(pos) < length() &&
00970           index(str, pos) == static_cast<size_type>(pos)) ; }
00971 inline ostream &operator<<(ostream &s, const String &x) {
00972   s << x.c_str(); return s; }
00973 
00974 
00975 } //# NAMESPACE CASA - END
00976 
00977 #ifndef AIPS_NO_TEMPLATE_SRC
00978 #include <casa/BasicSL/String.cc>
00979 #endif //# AIPS_NO_TEMPLATE_SRC
00980 #endif

Generated on Mon Sep 1 22:33:39 2008 for NRAOCASA by  doxygen 1.5.1