casacore
MUString.h
Go to the documentation of this file.
1 //# MUString.h: Pointed String class to aid analysis of quantity strings
2 //# Copyright (C) 1996,1997,1999,2000,2001
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef CASA_MUSTRING_H
29 #define CASA_MUSTRING_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/BasicSL/String.h>
35 #include <casacore/casa/Containers/Block.h>
36 
37 //# Forward Declarations
38 #include <casacore/casa/iosfwd.h>
39 namespace casacore { //# NAMESPACE CASACORE - BEGIN
40 
41 class Regex;
42 template <class T> class Vector;
43 
44 // <summary>
45 // Pointed String class to aid analysis of quantity strings
46 // </summary>
47 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tMeasure" demos="">
48 // </reviewed>
49 
50 // <prerequisite>
51 // <li> <linkto classString>String</linkto>
52 // </prerequisite>
53 //
54 // <etymology>
55 // From Measure Utility String
56 // </etymology>
57 //
58 // <synopsis>
59 // The MUString is a class with a String and an embedded pointer. It can be used
60 // to linearly analyse a string for its semantics. Imagine for instance a
61 // string that represents an angle. It could be formatted as
62 // <src>[+-]hh:mm:ss.ttt</src>
63 // or as <src>[+-]hh[hH]mm[mM]</src> or as
64 // <src>[+-]dd.mm.ss.ttt</src> or with <src>.'s</src> replaced with
65 // <src>dms</src> or as <src>[+-]ddd.fff deg</src> etc.<br>
66 // The available methods aid in analysing this string (see example).<br>
67 // The following analysis method classes are avaible:
68 // <ul>
69 // <li> construct -- all constructors create a string with the pointer
70 // starting at the beginning of the string
71 // <li> testX(arg) -- all test methods test if the next available
72 // character(s) fulfill the specified argument test. E.g.
73 // <src>Bool testSign()</src> test if current character is + or -.
74 // If at end of string; False is returned, except for
75 // <src>testBlank()</src>. No pointer update. Any method with
76 // <em>NC</em> at the end (for no-case) will test irrespective
77 // of the case.
78 // <li> skipX(arg) -- all skip methods skip all available character(s)
79 // fulfilling the specified argument. E.g.
80 // <src>void skipSign()</src> will skip all + and - found at
81 // the current and subsequent positions. Pointer updated.
82 // <li> tSkipX(arg) -- will skip as skipX, and return Bool as in testX.
83 // Pointer updated
84 // <li> getX(arg) -- will get the indicated X value from the string.
85 // Pointer updated. A get will always return a valid result.
86 // However, if the value did not exist (e.g.
87 // <src>Double getDouble()</src> form a string like <src>"abc"</src>
88 // will return 0.0) a False status will be saved. It can be
89 // interrogated by the <src>Bool status()</src> function.
90 // The string part used in producing the value is also
91 // saved, and can be obtained with
92 // <src>const String &lastGet()</src>.
93 // No saving in case of a simple getChar() is done.
94 // <li> stack -- if it is necessary to save the current position of the
95 // pointer (for maybe later restoration) a <src>void push()</src>
96 // and <src>void pop()</src> are available
97 // <li> pointer -- the pointer can be manipulated with <src>void setPtr()</src>
98 // and <src>Int getPtr()</src>. Pointers are always protected in
99 // their value.
100 // </ul>
101 // The following types (<em>X</em> in the above list) are available
102 // <ul>
103 // <li> Char -- a single character
104 // <li> CharNC -- a single character with no case
105 // <li> String -- a string
106 // <li> StringNC -- a string without case
107 // <li> Alpha -- a through z and A through Z and _ (underscore)
108 // <li> Num -- digits 0 through 9
109 // <li> AlphaNum -- a field staring with Alpha, and remainder (if any)
110 // Alpha or Num
111 // <li> Sign -- a plus or minus
112 // <li> Blank -- a space ar a tab
113 // <li> uInt -- unsigned integer
114 // <li> Int -- an optionally signed integer
115 // <li> Double -- a double value
116 // </ul>
117 // General string aids are available. The main one a minimax, caseless
118 // check of an input String against a vector:
119 // <src>static uInt minimaxNC(String in, Int N_name, String name[])</src>
120 // and its vector equivalent:
121 // <src>static uInt minimaxNC(String in, Vector<String> name)</src>.
122 // Success is indicated by a return value less than N_name or the
123 // vector length.
124 // </synopsis>
125 //
126 // <example>
127 // See <linkto class=MVAngle>MVAngle</linkto> class for example background.
128 // The following example is the conversion of different input angle formats
129 // to a <linkto class=Quantum>Quantity</linkto>. A full blown example,
130 // but gives some idea of intricacies involved.
131 // <srcblock>
132 // res = Quantity(0.0, "rad"); // result
133 // MUString tmp(in); // Pointed non-const String
134 // tmp.skipBlank();
135 // Double s = tmp.getSign(); // sign
136 // tmp.push(); // Save position to rescan
137 // Double r = tmp.getuInt(); // first field
138 // Int tp = 0; // distributor
139 // if (tmp.tSkipChar('.')) { // if more than one ., dms format
140 // Double r1 = tmp.getuInt();
141 // if (tmp.tSkipChar('.')) {
142 // r += r1/60.0 + tmp.getDouble()/3600.0;
143 // tp = 4;
144 // } else { // else value with units
145 // tmp.pop(); // Reset position
146 // r = tmp.getDouble();
147 // };
148 // } else if (tmp.tSkipCharNC('d')) { // dms
149 // tp = 1;
150 // } else if (tmp.tSkipCharNC('h')) { // hms
151 // tp = 2;
152 // } else if (tmp.tSkipChar(':')) { // hms
153 // tp = 3;
154 // };
155 // switch (tp) {
156 // case 0: {
157 // UnitVal u; String us;
158 // if (!MVAngle::unitString(u,us,tmp)) return False;
159 // r *= s;
160 // if (u == UnitVal::NODIM) { // check correct dimension
161 // res = Quantity(r,"rad");
162 // return True;
163 // };
164 // if (u == UnitVal::ANGLE) {
165 // res = Quantity(r,us);
166 // return True;
167 // };
168 // if (u == UnitVal::TIME) {
169 // res = Quantity(Quantity(r/240.,us).getBaseValue(), "deg");
170 // return True;
171 // };
172 // return False;
173 // };
174 // break;
175 //
176 // case 1:
177 // case 2:
178 // case 3: { // get remainder od ms and hms formats
179 // Char tc = 'm';
180 // if (tp == 3) tc = ':';
181 // tmp.push();
182 // Double r1 = tmp.getuInt();
183 // if (tmp.tSkipChar('.')) {
184 // tmp.pop();
185 // r += tmp.getDouble()/3600.;
186 // } else if (tmp.tSkipCharNC(tc)) {
187 // r += r1/60.0 + tmp.getDouble()/3600.;
188 // } else {
189 // r += r1/3600.0;
190 // };
191 // r *= s;
192 // };
193 // break;
194 //
195 // default:
196 // break;
197 // };
198 //
199 // switch (tp) { // make correct units
200 //
201 // case 1:
202 // case 4:
203 // res = Quantity(r,"deg");
204 // break;
205 //
206 // case 2:
207 // case 3:
208 // res = Quantity(Quantity(r/240.,"h").getBaseValue(), "deg");
209 // break;
210 //
211 // default:
212 // break;
213 //
214 // };
215 // return True;
216 // </srcblock>
217 // </example>
218 //
219 // <motivation>
220 // The class was written to be able to analyse an input string for its
221 // <linkto class=Quantum>Quantum</linkto> representation as value with
222 // units, or os a date/time or as an angle.
223 // </motivation>
224 //
225 // <todo asof="1996/11/14">
226 // <li> nothing I know of
227 // </todo>
228 
229 class MUString
230 {
231 public:
232 
233 //# Friends
234  // Output String starting at pointer
235  friend ostream &operator<<(ostream &os, const MUString &in);
236 //# Enumerations
237 
238 //# Constructors
239  // Default constructor creates an empty string
240  MUString();
241  // Create from String; setting pointer at start
242  // <group>
243  MUString(const String &in);
244  MUString(const Char *in);
245  MUString(char in);
246  // </group>
247  // Copy constructor; new pointer will be same as old
248  MUString(const MUString &other);
249  // Copy assignment; new pointer will be same as old
250  MUString &operator=(const MUString &other);
251 
252  // Destructor
253  ~MUString();
254 
255 //# Operators
256  // Obtain remaining string (same as <src>get()</src>).
257  String operator()();
258 
259 //# General Member Functions
260  // Save current pointer on internal stack
261  void push();
262  // Restore pointer from stack (or set to start if stack empty)
263  void pop();
264  // Restore stack for one level
265  void unpush();
266 
267  // Act on whitespace; adjusting pointer if skip
268  // <group>
269  void skipBlank();
270  Bool testBlank() const;
271  Bool tSkipBlank();
272  // </group>
273 
274  // Act on sign; return +1 or -1 depending on signs found (-- == +)
275  // <group>
276  void skipSign();
277  Bool testSign() const;
278  Bool tSkipSign();
279  Int getSign();
280  // </group>
281 
282  // Act on integer field. If no integer found in 0 returned; and False
283  // <group>
284  void skipInt();
285  Bool testInt() const;
286  Bool tSkipInt();
287  Int getInt();
288  void skipuInt();
289  Bool tSkipuInt();
290  Bool testuInt() const;
291  uInt getuInt();
292  // </group>
293 
294  // Act on Double field. If no value 0 returned and False.
295  // <group>
296  void skipDouble();
297  Bool testDouble() const;
298  Bool tSkipDouble();
299  Double getDouble();
300  // </group>
301 
302  // Act on character(s)
303  // <group>
304  void skipChar(Int n=1);
305  void skipChar(Char ch);
306  Bool tSkipChar(Char nc);
307  void skipCharNC(Char ch);
308  Bool tSkipCharNC(Char ch);
309  Bool tSkipOneChar(Char ch);
311  void skipChar(const Regex &ex);
312  Bool tSkipChar(const Regex &ex);
313  void skipAlpha();
314  Bool tSkipAlpha();
315  void skipNum();
316  Bool tSkipNum();
317  void skipAlphaNum();
319  Bool testChar(Char ch) const;
320  Bool testCharNC(Char ch) const;
321  Bool testChar(const Regex &ex) const;
322  Bool testAlpha() const;
323  Bool testNum() const;
324  Bool testAlphaNum() const;
325  Char getChar();
326  String getAlpha();
328  // </group>
329 
330  // Act on series of characters
331  // <group>
332  Bool testString(const Regex &ex) const;
333  Bool testString(const String &ex) const;
334  Bool testStringNC(const String &ex) const;
335  Bool tSkipString(const Regex &ex);
336  Bool tSkipString(const String &ex);
337  Bool tSkipStringNC(const String &ex);
338  void skipString(const Regex &ex);
339  void skipString(const String &ex);
340  void skipStringNC(const String &ex);
341  String getString(const Regex &ex);
342  String getString(const String &ex);
343  String getStringNC(const String &ex);
344  // </group>
345 
346  // Match a pair of opening(at pointer)/closing characters (e.g. ( and )).
347  // Return False if wrong semantics. The string between the pair
348  // (excluding them)
349  // will be put in Last. If false, the ptr will be as originally; if True
350  // it will point beyond the matched closing character
351  Bool matchPair(Char nd);
352 
353  // Get frequency of occurrence
354  Int freqChar(Char ch) const;
355 
356  // Get part of string
357  // <group>
358  String get();
359  String get(uInt st);
360  String get(uInt st, uInt nd);
361  // </group>
362 
363  // Get pointer
364  Int getPtr() const;
365 
366  // (Re-)set pointer
367  void setPtr(Int in=0);
368 
369  // test for end of string
370  Bool eos() const;
371 
372  // Get status last get
373  Bool status() const;
374 
375  // Get String found at last get
376  const String &lastGet() const;
377 
378  // Do minimax check on list of Strings
379  // <group>
380  static uInt minimaxNC(const String &in, Int N_name,
381  const String tname[]);
382  static uInt minimaxNC(const String &in, const Vector<String> &tname);
383  // </group>
384 
385 private:
386  // Data
387  // String value
389  // 0-based pointer into string
391  // Length of string
393  // Pointer stack
395  // Pointer into stack
397  // Status of last get
399  // String found at last get
401 
402  // Member functions
403  // Make a new pointer between 0 and len inclusive
404  void adjustPtr(Int in);
405 
406  // Initialise last settings; return pointer
407  Int initLast();
408  // Set last settings
409  void setLast(Int st);
410 
411 };
412 
413 // Global functions
414 // <summary> Output global functions </summary>
415 // Output
416 // <group name=output>
417 ostream &operator<<(ostream &os, const MUString &in);
418 // </group>
419 
420 
421 } //# NAMESPACE CASACORE - END
422 
423 #endif
casacore::MUString::~MUString
~MUString()
Destructor.
casacore::MUString::tSkipDouble
Bool tSkipDouble()
casacore::MUString::testAlphaNum
Bool testAlphaNum() const
casacore::MUString::stack
Block< uInt > stack
Pointer stack.
Definition: MUString.h:394
casacore::MUString::skipStringNC
void skipStringNC(const String &ex)
casacore::MUString::tSkipuInt
Bool tSkipuInt()
casacore::MUString::getuInt
uInt getuInt()
casacore::MUString::tSkipAlpha
Bool tSkipAlpha()
casacore::MUString::stpt
uInt stpt
Pointer into stack.
Definition: MUString.h:396
casacore::MUString::testInt
Bool testInt() const
casacore::MUString::tSkipBlank
Bool tSkipBlank()
casacore::MUString::push
void push()
Save current pointer on internal stack.
casacore::MUString::skipChar
void skipChar(Int n=1)
Act on character(s)
casacore::MUString::status
Bool status() const
Get status last get.
casacore::MUString::testDouble
Bool testDouble() const
casacore::MUString::getPtr
Int getPtr() const
Get pointer.
casacore::MUString::tSkipCharNC
Bool tSkipCharNC(Char ch)
casacore::MUString::getChar
Char getChar()
casacore::MUString::len
uInt len
Length of string.
Definition: MUString.h:392
casacore::MUString::operator<<
friend ostream & operator<<(ostream &os, const MUString &in)
Output String starting at pointer.
casacore::MUString::tSkipInt
Bool tSkipInt()
casacore::MUString::getInt
Int getInt()
casacore::MUString::str
String str
Data String value.
Definition: MUString.h:388
casacore::MUString::testCharNC
Bool testCharNC(Char ch) const
casacore::MUString::initLast
Int initLast()
Initialise last settings; return pointer.
casacore::MUString::freqChar
Int freqChar(Char ch) const
Get frequency of occurrence.
casacore::MUString::tSkipChar
Bool tSkipChar(Char nc)
casacore::MUString::skipuInt
void skipuInt()
casacore::MUString::setPtr
void setPtr(Int in=0)
(Re-)set pointer
casacore::MUString::testNum
Bool testNum() const
casacore::MUString::stat
Bool stat
Status of last get.
Definition: MUString.h:398
casacore::MUString::get
String get()
Get part of string.
casacore::Double
double Double
Definition: aipstype.h:55
casacore::MUString::getStringNC
String getStringNC(const String &ex)
casacore::MUString::getDouble
Double getDouble()
casacore::MUString::testBlank
Bool testBlank() const
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::MUString::operator=
MUString & operator=(const MUString &other)
Copy assignment; new pointer will be same as old.
casacore::MUString::testStringNC
Bool testStringNC(const String &ex) const
casacore::MUString::skipSign
void skipSign()
Act on sign; return +1 or -1 depending on signs found (– == +)
casacore::MUString::tSkipOneCharNC
Bool tSkipOneCharNC(Char ch)
casacore::MUString::tSkipOneChar
Bool tSkipOneChar(Char ch)
casacore::MUString::testuInt
Bool testuInt() const
casacore::MUString::skipDouble
void skipDouble()
Act on Double field.
casacore::MUString::tSkipStringNC
Bool tSkipStringNC(const String &ex)
casacore::MUString::skipCharNC
void skipCharNC(Char ch)
casacore::MUString::skipNum
void skipNum()
casacore::MUString::lget
String lget
String found at last get.
Definition: MUString.h:400
casacore::Int
int Int
Definition: aipstype.h:50
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::MUString::skipAlphaNum
void skipAlphaNum()
casacore::MUString::getSign
Int getSign()
casacore::MUString::testString
Bool testString(const Regex &ex) const
Act on series of characters.
casacore::MUString::pop
void pop()
Restore pointer from stack (or set to start if stack empty)
casacore::MUString::operator()
String operator()()
Obtain remaining string (same as get()).
casacore::MUString::tSkipNum
Bool tSkipNum()
casacore::MUString::adjustPtr
void adjustPtr(Int in)
Member functions Make a new pointer between 0 and len inclusive.
casacore::MUString::eos
Bool eos() const
test for end of string
casacore::MUString::MUString
MUString()
Default constructor creates an empty string.
casacore::MUString::testAlpha
Bool testAlpha() const
casacore::MUString
Pointed String class to aid analysis of quantity strings.
Definition: MUString.h:229
casacore::MUString::setLast
void setLast(Int st)
Set last settings.
casacore::MUString::getAlpha
String getAlpha()
casacore::MUString::getAlphaNum
String getAlphaNum()
casacore::MUString::skipString
void skipString(const Regex &ex)
casacore::MUString::lastGet
const String & lastGet() const
Get String found at last get.
casacore::MUString::ptr
uInt ptr
0-based pointer into string
Definition: MUString.h:390
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::MUString::matchPair
Bool matchPair(Char nd)
Match a pair of opening(at pointer)/closing characters (e.g.
casacore::MUString::minimaxNC
static uInt minimaxNC(const String &in, Int N_name, const String tname[])
Do minimax check on list of Strings.
casacore::MUString::unpush
void unpush()
Restore stack for one level.
casacore::MUString::tSkipSign
Bool tSkipSign()
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::Block< uInt >
casacore::operator<<
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
casacore::Regex
Regular expression class.
Definition: Regex.h:198
casacore::MUString::skipInt
void skipInt()
Act on integer field.
casacore::MUString::skipAlpha
void skipAlpha()
casacore::MUString::tSkipAlphaNum
Bool tSkipAlphaNum()
casacore::Vector
A 1-D Specialization of the Array class.
Definition: ArrayIO.h:45
casacore::MUString::tSkipString
Bool tSkipString(const Regex &ex)
casacore::MUString::getString
String getString(const Regex &ex)
casacore::Char
char Char
Definition: aipstype.h:46
casacore::MUString::skipBlank
void skipBlank()
Act on whitespace; adjusting pointer if skip.
casacore::MUString::testChar
Bool testChar(Char ch) const
casacore::MUString_global_functions_output::operator<<
ostream & operator<<(ostream &os, const MUString &in)
casacore::MUString_global_functions_output
Global functions.
Definition: MUString.h:418
casacore::MUString::testSign
Bool testSign() const