casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
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
void skipBlank()
Act on whitespace; adjusting pointer if skip.
void skipInt()
Act on integer field.
A 1-D Specialization of the Array class.
Bool testStringNC(const String &ex) const
int Int
Definition: aipstype.h:50
Int initLast()
Initialise last settings; return pointer.
std::vector< double > Vector
Definition: ds9context.h:24
String lget
String found at last get.
Definition: MUString.h:400
Bool testuInt() const
void skipSign()
Act on sign; return +1 or -1 depending on signs found (– == +)
Bool tSkipString(const Regex &ex)
void push()
Save current pointer on internal stack.
uInt stpt
Pointer into stack.
Definition: MUString.h:396
Bool testNum() const
Bool testAlphaNum() const
void skipChar(Int n=1)
Act on character(s)
Block< uInt > stack
Pointer stack.
Definition: MUString.h:394
Bool testDouble() const
Bool tSkipStringNC(const String &ex)
Pointed String class to aid analysis of quantity strings.
Definition: MUString.h:229
Bool tSkipOneChar(Char ch)
char Char
Definition: aipstype.h:46
uInt len
Length of string.
Definition: MUString.h:392
void unpush()
Restore stack for one level.
Bool testCharNC(Char ch) const
MUString & operator=(const MUString &other)
Copy assignment; new pointer will be same as old.
ostream & operator<<(ostream &os, const std::pair< T, U > &p)
Bool tSkipOneCharNC(Char ch)
const String & lastGet() const
Get String found at last get.
String getStringNC(const String &ex)
Bool tSkipCharNC(Char ch)
String operator()()
Obtain remaining string (same as get()).
Bool testBlank() const
String getString(const Regex &ex)
double Double
Definition: aipstype.h:55
Bool stat
Status of last get.
Definition: MUString.h:398
Regular expression class.
Definition: Regex.h:198
Bool eos() const
test for end of string
~MUString()
Destructor.
Int freqChar(Char ch) const
Get frequency of occurrence.
Bool tSkipChar(Char nc)
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
static uInt minimaxNC(const String &in, Int N_name, const String tname[])
Do minimax check on list of Strings.
void setPtr(Int in=0)
(Re-)set pointer
Bool matchPair(Char nd)
Match a pair of opening(at pointer)/closing characters (e.g.
Bool testString(const Regex &ex) const
Act on series of characters.
void skipCharNC(Char ch)
void setLast(Int st)
Set last settings.
void pop()
Restore pointer from stack (or set to start if stack empty)
Bool testSign() const
void adjustPtr(Int in)
Member functions Make a new pointer between 0 and len inclusive.
Int getPtr() const
Get pointer.
MUString()
Default constructor creates an empty string.
void skipDouble()
Act on Double field.
Bool testChar(Char ch) const
Bool testAlpha() const
String: the storage and methods of handling collections of characters.
Definition: String.h:223
uInt ptr
0-based pointer into string
Definition: MUString.h:390
void skipString(const Regex &ex)
Bool status() const
Get status last get.
void skipStringNC(const String &ex)
Bool testInt() const
String str
Data String value
Definition: MUString.h:388
unsigned int uInt
Definition: aipstype.h:51
friend ostream & operator<<(ostream &os, const MUString &in)
Output String starting at pointer.
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42