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 <casacore/casa/aips.h>
00033 
00034 //# Includes
00035 #include <string>
00036 
00037 using std::string;
00038 
00039 #include <casacore/casa/iosstrfwd.h>
00040 #include <casacore/casa/sstream.h>
00041 
00042 namespace casacore { //# NAMESPACE CASACORE - 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 Casacore defined replacement operators at, before, after,
00052 // through, 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 Casacore implementation of a string class. It is
00114 // from 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 Casacore 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 Casacore additions 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 Casacore 
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 (** Casacore 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   // ** Casacore 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   // *** Casacore 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   // ** Casacore 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   // ** Casacore 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   // ** Casacore 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   // ** Casacore 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   // ** Casacore 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   // ** Casacore 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   // ** Casacore 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   // ** Casacore 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   // ** Casacore 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   // Create a formatted string using the given printf format string.
00574   static String format (const char* picture, ...);
00575 
00576   // Convert a String to a value. All characters in the string must be used.
00577   // It uses a shift from an ostringstream, so that operator must exist
00578   // for the data type used.
00579   // <br>In case of an error, an exception is thrown if <src>chk</src> is set.
00580   // Otherwise it returns False and <src>value</src> contains the value read
00581   // so far.
00582   // <group>
00583   template<typename T> inline Bool fromString (T& value, Bool chk=True) const
00584   {
00585     std::istringstream os(*this);
00586     os >> value;
00587     if (os.fail()  ||  !os.eof()) {
00588       if (chk) throwFromStringError();
00589       return False;
00590     }
00591     return True;
00592   }
00593   template<typename T> inline T fromString() const
00594   {
00595     T value;
00596     fromString(value);
00597     return value;
00598   }
00599   // </group>
00600 
00601   // Convert a string to an Int, Float or Double.
00602   // <br>In case of an error, an exception is thrown if <src>chk</src> is set.
00603   // Otherwise the value read so far is returned (0 if nothing read).
00604   // <group>
00605   static Int toInt (const String& s, Bool chk=False);
00606   static Float toFloat (const String& s, Bool chk=False);
00607   static Double toDouble (const String& s, Bool chk=False);
00608   // </group>
00609 
00610   // Convert a value to a String.
00611   // It uses a shift into an ostringstream, so that operator must be
00612   // defined for the data type used.
00613   template<typename T>
00614   static String toString(const T& value)
00615   {
00616     std::ostringstream os;
00617     os << value;
00618     return os.str();
00619   }
00620 
00621   // Remove beginning and ending whitespace.
00622   void trim();
00623 
00624   // Remove specified chars from beginning and end of string.
00625   void trim(char c[], uInt n);
00626 
00627   // Remove specified character from beginning of string.
00628   // If the character is repeated more than once on the left, all instances
00629   // will be removed; e.g. ltrim(',') results in ",,xy" becoming "xy".
00630   void ltrim(char c);
00631 
00632   // Remove specified character from end of string.
00633   // If the character is repeated more than once on the right, all instances
00634   // will be removed; e.g. rtrim(',') results in "xy,," becoming "xy".
00635   void rtrim(char c);
00636 
00637   // Does the string start with the specified string?
00638   Bool startsWith(const string& beginString) const
00639     { return find(beginString) == 0; }
00640 
00641   // Search functions. Returns either npos (if not found); else position.
00642   // <note role=warning> The RegexBase ones are ** Casacore additions</note>
00643   // <group>
00644   size_type find(const string &str, size_type pos=0) const {
00645     return string::find(str, pos); }
00646   size_type find(const Char *s, size_type pos=0) const {
00647     return string::find(s, pos); }
00648   size_type find(const Char *s, size_type pos, size_type n) const {
00649     return string::find(s, pos, n); }
00650   size_type find(Char c, size_type pos=0) const {
00651     return string::find(c, pos); }
00652   size_type find(const RegexBase &r, size_type pos=0) const;
00653   size_type rfind(const string &str, size_type pos=npos) const {
00654     return string::rfind(str, pos); }
00655   size_type rfind(const Char *s, size_type pos=npos) const {
00656     return string::rfind(s, pos); }
00657   size_type rfind(const Char *s, size_type pos, size_type n) const {
00658     return string::rfind(s, pos, n); }
00659   size_type rfind(Char c, size_type pos=npos) const {
00660     return string::rfind(c, pos); }
00661   size_type rfind(const RegexBase &r, size_type pos=npos) const;
00662   size_type find_first_of(const string &str, size_type pos=0) const {
00663     return string::find_first_of(str, pos); }
00664   size_type find_first_of(const Char *s, size_type pos=0) const {
00665     return string::find_first_of(s, pos); }
00666   size_type find_first_of(const Char *s, size_type pos, size_type n) const {
00667     return string::find_first_of(s, pos, n); }
00668   size_type find_first_of(Char c, size_type pos=0) const {
00669     return string::find_first_of(c, pos); }
00670   size_type find_last_of(const string &str, size_type pos=npos) const {
00671     return string::find_last_of(str, pos); }
00672   size_type find_last_of(const Char *s, size_type pos=npos) const {
00673     return string::find_last_of(s, pos); }
00674   size_type find_last_of(const Char *s, size_type pos, size_type n) const {
00675     return string::find_last_of(s, pos, n); }
00676   size_type find_last_of(Char c, size_type pos=npos) const {
00677     return string::find_last_of(c, pos); }
00678   size_type find_first_not_of(const string &str, size_type pos=0) const {
00679     return string::find_first_not_of(str, pos); }
00680   size_type find_first_not_of(const Char *s, size_type pos=0) const {
00681     return string::find_first_not_of(s, pos); }
00682   size_type find_first_not_of(const Char *s, size_type pos, size_type n) const {
00683     return string::find_first_not_of(s, pos, n); }
00684   size_type find_first_not_of(Char c, size_type pos=0) const {
00685     return string::find_first_not_of(c, pos); }
00686   size_type find_last_not_of(const string &str, size_type pos=npos) const {
00687     return string::find_last_not_of(str, pos); }
00688   size_type find_last_not_of(const Char *s, size_type pos=npos) const {
00689     return string::find_last_not_of(s, pos); }
00690   size_type find_last_not_of(const Char *s, size_type pos, size_type n) const {
00691     return string::find_last_not_of(s, pos, n); }
00692   size_type find_last_not_of(Char c, size_type pos=npos) const {
00693     return string::find_last_not_of(c, pos); }
00694   // </group>
00695   
00696   // Containment. ** Casacore addition
00697   // <group name=contains>
00698   Bool contains(Char c) const {
00699     return (find(c) != npos); }
00700   Bool contains(const string &str) const {
00701     return (find(str) != npos); }
00702   Bool contains(const Char *s) const {
00703     return (find(s) != npos); }
00704   Bool contains(const RegexBase &r) const;
00705   // </group>
00706   // Does the string starting at the given position contain the given substring?
00707   // If the position is negative, it is counted from the end.
00708   // ** Casacore addition
00709   // <group name=contains_pos>
00710   Bool contains(Char c, Int pos) const;
00711   Bool contains(const string &str, Int pos) const;
00712   Bool contains(const Char *s, Int pos) const;
00713   Bool contains(const RegexBase &r, Int pos) const;
00714   // </group>
00715 
00716   // Matches entire string from pos
00717   // (or till pos if negative pos). ** Casacore addition
00718   // <group name=matches>
00719   Bool matches(const string &str, Int pos = 0) const;
00720   Bool matches(Char c, Int pos = 0) const {
00721     return matches(String(c), pos); };
00722   Bool matches(const Char *s, Int pos = 0) const {
00723     return matches(String(s), pos); };
00724   Bool matches(const RegexBase &r, Int pos = 0) const;
00725   // </group>
00726 
00727   // Concatenate by prepending the argument onto String. ** Casacore addition
00728   // <group name=concatenation_method>
00729   void prepend(const string &str); 
00730   void prepend(const Char *s);
00731   void prepend(Char c);
00732   // </group> 
00733 
00734   // Return the position of the target in the string or npos for failure.
00735   // ** Casacore addition
00736   // <group name=index>
00737   size_type index(Char c, Int startpos = 0) const {
00738     return ((startpos >= 0) ? find(c, startpos) :
00739             rfind(c, length() + startpos - 1)); }
00740   size_type index(const string &str, Int startpos = 0) const { 
00741     return ((startpos >= 0) ? find(str, startpos) :
00742             rfind(str, length() + startpos - str.length())); }
00743   size_type index(const Char *s, Int startpos = 0) const {
00744     return ((startpos >= 0) ? find(s, startpos) :
00745             rfind(s, length() + startpos - traits_type::length(s))); }
00746   size_type index(const RegexBase &r, Int startpos = 0) const;
00747   // </group>
00748 
00749   //  Return the number of occurences of target in String. ** Casacore addition
00750   // <group name=freq>
00751   Int freq(Char c) const; 
00752   Int freq(const string &str) const;
00753   Int freq(const Char *s) const;
00754   // </group>
00755 
00756   // Extract the string "at" the argument's position. ** Casacore addition
00757   // <group name=at>
00758   SubString at(size_type pos, size_type len);
00759   String at(size_type pos, size_type len) const {
00760     return String(*this, pos, len); }
00761   SubString at(const string &str, Int startpos = 0);
00762   String at(const string &str, Int startpos = 0) const;
00763   SubString at(const Char *s, Int startpos = 0);
00764   String at(const Char *s, Int startpos = 0) const;
00765   SubString at(Char c, Int startpos = 0);
00766   String at(Char c, Int startpos = 0) const;
00767   SubString at(const RegexBase &r, Int startpos = 0); 
00768   String at(const RegexBase &r, Int startpos = 0) const; 
00769   // Next ones for overloading reasons. 
00770   // <note role=tip> It is better to use the <src>substr()</src> method
00771   // in stead. </note>
00772   // <group>
00773   SubString at(Int pos, Int len) {
00774     return at(static_cast<size_type>(pos), static_cast<size_type>(len));
00775   };
00776   String at(Int pos, Int len) const {
00777     return at(static_cast<size_type>(pos), static_cast<size_type>(len));
00778   };
00779   SubString at(Int pos, size_type len) {
00780     return at(static_cast<size_type>(pos), len);
00781   };
00782   String at(Int pos, size_type len) const {
00783     return at(static_cast<size_type>(pos), len);
00784   };
00785   // </group>
00786   // </group>
00787 
00788   // Start at startpos and extract the string "before" the argument's 
00789   // position, exclusive. ** Casacore addition
00790   // <group name=before>
00791   SubString before(size_type pos) const;
00792   SubString before(const string &str, size_type startpos = 0) const;
00793   SubString before(const Char *s, size_type startpos = 0) const;
00794   SubString before(Char c, size_type startpos = 0) const;
00795   SubString before(const RegexBase &r, size_type startpos = 0) const;
00796   // Next one for overloading reasons
00797   SubString before(Int pos) const {
00798     return before(static_cast<size_type>(pos)); };    
00799   // </group>
00800 
00801   // Start at startpos and extract the SubString "through" to the argument's 
00802   // position, inclusive. ** Casacore addition
00803   // <group name=through>
00804   SubString through(size_type pos);
00805   SubString through(const string &str, size_type startpos = 0);
00806   SubString through(const Char *s, size_type startpos = 0);
00807   SubString through(Char c, size_type startpos = 0);
00808   SubString through(const RegexBase &r, size_type startpos = 0);
00809   // Next one for overloading reasons
00810   SubString through(Int pos) {
00811     return through(static_cast<size_type>(pos)); }
00812   // </group>
00813 
00814   // Start at startpos and extract the SubString "from" the argument's 
00815   // position, inclusive, to the String's end. ** Casacore addition
00816   // <group name=from>
00817   SubString from(size_type pos);
00818   SubString from(const string &str, size_type startpos = 0);
00819   SubString from(const Char *s, size_type startpos = 0);
00820   SubString from(Char c, size_type startpos = 0);
00821   SubString from(const RegexBase &r, size_type startpos = 0);
00822   // Next one for overloading reasons
00823   SubString from(Int pos) {
00824     return from(static_cast<size_type>(pos));
00825   };
00826   // </group>
00827 
00828   // Start at startpos and extract the SubString "after" the argument's 
00829   // position, exclusive, to the String's end. ** Casacore addition
00830   // <group name=after>
00831   SubString after(size_type pos);
00832   SubString after(const string &str, size_type startpos = 0);
00833   SubString after(const Char *s, size_type startpos = 0);
00834   SubString after(Char c, size_type startpos = 0);
00835   SubString after(const RegexBase &r, size_type startpos = 0);
00836   // Next one for overloading reasons
00837   SubString after(Int pos) {
00838     return after(static_cast<size_type>(pos));
00839   };
00840   // </group>
00841 
00842   // Maybe forget some. ** Casacore addition
00843   // <group>
00844   // internal transformation to reverse order of String.
00845   void reverse();
00846   // internal transformation to capitalization of String.
00847   void capitalize();
00848   // internal transformation to uppercase of String
00849   void upcase();
00850   // internal transformation to lowercase of String
00851   void downcase();
00852   // </group>
00853 
00854   // Delete len chars starting at pos. ** Casacore addition
00855   void del(size_type pos, size_type len);
00856 
00857   // Delete the first occurrence of target after startpos. ** Casacore addition
00858   //<group name=del_after>
00859   void del(const string &str, size_type startpos = 0);
00860   void del(const Char *s, size_type startpos = 0);
00861   void del(Char c, size_type startpos = 0);
00862   void del(const RegexBase &r, size_type startpos = 0);
00863   // Overload problem
00864   void del(Int pos, Int len) {
00865     del(static_cast<size_type>(pos), static_cast<size_type>(len)); }
00866   //</group> 
00867 
00868   // Global substitution: substitute all occurrences of pat with repl, and
00869   // return the number of replacements.
00870   // ** Casacore addition
00871   //<group name=gsub>
00872   Int gsub(const string &pat, const string &repl);
00873   Int gsub(const Char *pat, const string &repl);
00874   Int gsub(const Char *pat, const Char *repl);
00875   Int gsub(const RegexBase &pat, const string &repl);
00876   //</group>
00877 
00878 private:
00879   // Helper functions for at, before etc
00880   // <group>
00881   SubString _substr(size_type first, size_type l) const {
00882     return SubString(*this, first, l); }
00883   // </group>
00884 
00885   // Helper function for fromString.
00886   void throwFromStringError() const;
00887 };
00888 
00889 // <summary>
00890 // Global concatenation operators
00891 // </summary>
00892 
00893 // The global concatenation operators
00894 // <group name=concatenator>
00895 inline String operator+(const String &lhs, const String &rhs) {
00896   String str(lhs); str.append(rhs); return str; }
00897 inline String operator+(const Char *lhs, const String &rhs) {
00898   String str(lhs); str.append(rhs); return str; }
00899 inline String operator+(Char lhs, const String &rhs) {
00900   String str(lhs); str.append(rhs); return str; }
00901 inline String operator+(const String &lhs, const Char *rhs) {
00902   String str(lhs); str.append(rhs); return str; }
00903 inline String operator+(const String &lhs, Char rhs) {
00904   String str(lhs); str.append(rhs); return str; }
00905 // </group>
00906 
00907 // <summary>
00908 // Global comparison operators
00909 // </summary>
00910 
00911 // The global comparison operators
00912 // <group name=comparitor>
00913 inline Bool operator==(const String &x, const String &y) {
00914   return x.compare(y) == 0; }
00915 inline Bool operator!=(const String &x, const String &y) {
00916   return x.compare(y) != 0; }
00917 inline Bool operator>(const String &x, const String &y) {
00918   return x.compare(y) > 0; }
00919 inline Bool operator>=(const String &x, const String &y) {
00920   return x.compare(y) >= 0; }
00921 inline Bool operator<(const String &x, const String &y) {
00922   return x.compare(y) < 0; }
00923 inline Bool operator<=(const String &x, const String &y) {
00924   return x.compare(y) <= 0; }
00925 inline Bool operator==(const String &x, const Char *t) {
00926   return x.compare(t) == 0; }
00927 inline Bool operator!=(const String &x, const Char *t) {
00928   return x.compare(t) != 0; }
00929 inline Bool operator>(const String &x, const Char *t) {
00930   return x.compare(t) > 0; }
00931 inline Bool operator>=(const String &x, const Char *t) {
00932   return x.compare(t) >= 0; }
00933 inline Bool operator<(const String &x, const Char *t) {
00934   return x.compare(t) < 0; }
00935 inline Bool operator<=(const String &x, const Char *t) {
00936   return x.compare(t) <= 0; }
00937 inline Bool operator==(const String &x, const Char t) {
00938   return x.compare(String(t)) == 0; }
00939 inline Bool operator!=(const String &x, const Char t) {
00940   return x.compare(String(t)) != 0; }
00941 inline Bool operator>(const String &x, const Char t) {
00942   return x.compare(String(t)) > 0; }
00943 inline Bool operator>=(const String &x, const Char t) {
00944   return x.compare(String(t)) >= 0; }
00945 inline Bool operator<(const String &x, const Char t) {
00946   return x.compare(String(t)) < 0; }
00947 inline Bool operator<=(const String &x, const Char t) {
00948   return x.compare(String(t)) <= 0; }
00949 // ** Casacore additions of global compares. Returns 0 if equal; lt or gt 0 if
00950 // strings unequal or of unequal lengths.
00951 // <group>
00952 inline Int compare(const string &x, const string &y) {
00953   return x.compare(y); }
00954 inline Int compare(const string &x, const Char *y) {
00955   return x.compare(y); }
00956 inline Int compare(const string &x, const Char y) {
00957   return x.compare(String(y)); }
00958 // this version ignores case. ** Casacore addition. Result is 0 if equal
00959 // strings of equal lengths; else lt or gt 0 to indicate differences.
00960 Int fcompare(const String& x, const String& y);
00961 // </group>
00962 // </group>
00963 
00964 // <summary> Splitting </summary>
00965 // Global function which splits the String into string array res at separator
00966 // and returns the number of elements.  ** Casacore addition
00967 // <group name=split>
00968 Int split(const string &str, string res[], Int maxn,
00969           const string &sep);
00970 Int split(const string &str, string res[], Int maxn,
00971           const Char sep);
00972 Int split(const string &str, string res[], Int maxn,
00973           const RegexBase &sep);
00974 //</group> 
00975 
00976 // <summary> Some general functions </summary>
00977 // Functions to find special patterns, join and replicate
00978 // <group name=common>
00979 String common_prefix(const string &x, const string &y, 
00980                      Int startpos = 0);
00981 String common_suffix(const string &x, const string &y, 
00982                      Int startpos = -1);
00983 String replicate(Char c, String::size_type n);
00984 String replicate(const string &str, String::size_type n);
00985 String join(string src[], Int n, const string &sep);
00986 // </group>
00987 
00988 // <summary> Casing and related functions </summary>
00989 // Case conversion and rearrangement functions
00990 // <group name=case>
00991 // Global function which returns a transformation to reverse order of String.
00992 String reverse(const string& str);
00993 // Global function  which returns a transformation to uppercase of String.
00994 String upcase(const string& str);
00995 // Global function  which returns a transformation to lowercase of String.
00996 String downcase(const string& str);
00997 // Global function  which returns a transformation to capitalization of 
00998 // String.
00999 String capitalize(const string& str);
01000 // Global function  which removes leading and trailing whitespace.
01001 String trim(const string& str);
01002 // </group>
01003 
01004 // <summary> IO </summary>
01005 // <group name=io>
01006 // Output
01007 ostream &operator<<(ostream &s, const String &x);
01008 // </group>
01009 
01010 //# Inlines
01011 inline SubString::SubString(const string &str, string::size_type pos,
01012                             string::size_type len) :
01013   ref_p(str), pos_p((pos > str.length()) ? str.length() : pos),
01014   len_p((len == string::npos || pos_p+len > str.length()) ?
01015         str.length()-pos_p : len) {}
01016 
01017 inline SubString String::operator()(size_type pos, size_type len) {
01018   return at(pos, len); }
01019 inline  const Char *SubString::chars() const {
01020   return String(*this).c_str(); }
01021 
01022 inline Bool String::contains(Char c, Int pos) const {
01023   return (index(c, pos) != npos); }
01024 inline Bool String::contains(const string &str, Int pos) const {
01025   return (index(str, pos) != npos); }
01026 inline Bool String::contains(const Char *s, Int pos) const {
01027   return (index(s, pos) != npos); }
01028 inline Bool String::contains(const RegexBase &r, Int pos) const {
01029   return (index(r, pos) != npos); }
01030 
01031 inline ostream &operator<<(ostream &s, const String &x) {
01032   s << x.c_str(); return s; }
01033 
01034 
01035 } //# NAMESPACE CASACORE - END
01036 
01037 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1