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/Arrays/ArrayFwd.h>
35#include <casacore/casa/BasicSL/String.h>
36#include <casacore/casa/Containers/Block.h>
37
38//# Forward Declarations
39#include <casacore/casa/iosfwd.h>
40namespace casacore { //# NAMESPACE CASACORE - BEGIN
41
42class Regex;
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
230{
231public:
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
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
251
252 // Destructor
254
255//# Operators
256 // Obtain remaining string (same as <src>get()</src>).
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();
272 // </group>
273
274 // Act on sign; return +1 or -1 depending on signs found (-- == +)
275 // <group>
276 void skipSign();
277 Bool testSign() const;
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;
288 void skipuInt();
290 Bool testuInt() const;
292 // </group>
293
294 // Act on Double field. If no value 0 returned and False.
295 // <group>
300 // </group>
301
302 // Act on character(s)
303 // <group>
304 void skipChar(Int n=1);
305 void skipChar(Char ch);
307 void skipCharNC(Char ch);
311 void skipChar(const Regex &ex);
312 Bool tSkipChar(const Regex &ex);
313 void skipAlpha();
315 void skipNum();
319 Bool testChar(Char ch) const;
321 Bool testChar(const Regex &ex) const;
323 Bool testNum() const;
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;
338 void skipString(const Regex &ex);
339 void skipString(const String &ex);
340 void skipStringNC(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
352
353 // Get frequency of occurrence
354 Int freqChar(Char ch) const;
355
356 // Get part of string
357 // <group>
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
385private:
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
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>
417ostream &operator<<(ostream &os, const MUString &in);
418// </group>
420
421} //# NAMESPACE CASACORE - END
422
423#endif
Bool testChar(const Regex &ex) const
Int initLast()
Initialise last settings; return pointer.
Int getPtr() const
Get pointer.
friend ostream & operator<<(ostream &os, const MUString &in)
Output String starting at pointer.
void setLast(Int st)
Set last settings.
String getStringNC(const String &ex)
MUString(const MUString &other)
Copy constructor; new pointer will be same as old.
String operator()()
Obtain remaining string (same as get()).
Bool status() const
Get status last get.
static uInt minimaxNC(const String &in, const Vector< String > &tname)
MUString(const Char *in)
void pop()
Restore pointer from stack (or set to start if stack empty)
~MUString()
Destructor.
Bool testSign() const
void skipBlank()
Act on whitespace; adjusting pointer if skip.
String str
Data String value.
Definition: MUString.h:388
const String & lastGet() const
Get String found at last get.
String get(uInt st)
Bool tSkipString(const String &ex)
void skipStringNC(const String &ex)
void skipChar(Int n=1)
Act on character(s)
Bool testString(const String &ex) const
Bool testNum() const
MUString()
Default constructor creates an empty string.
void skipDouble()
Act on Double field.
Bool testAlpha() const
void adjustPtr(Int in)
Member functions Make a new pointer between 0 and len inclusive.
void skipString(const Regex &ex)
Block< uInt > stack
Pointer stack.
Definition: MUString.h:394
Bool testChar(Char ch) const
Bool tSkipString(const Regex &ex)
String getString(const String &ex)
Bool tSkipChar(Char nc)
void skipInt()
Act on integer field.
void unpush()
Restore stack for one level.
static uInt minimaxNC(const String &in, Int N_name, const String tname[])
Do minimax check on list of Strings.
Bool testCharNC(Char ch) const
Bool tSkipCharNC(Char ch)
Bool testStringNC(const String &ex) const
Bool matchPair(Char nd)
Match a pair of opening(at pointer)/closing characters (e.g.
String getString(const Regex &ex)
void setPtr(Int in=0)
(Re-)set pointer
Int freqChar(Char ch) const
Get frequency of occurrence.
void skipChar(const Regex &ex)
Bool testInt() const
Bool testuInt() const
Bool testString(const Regex &ex) const
Act on series of characters.
MUString & operator=(const MUString &other)
Copy assignment; new pointer will be same as old.
Bool testDouble() const
uInt stpt
Pointer into stack.
Definition: MUString.h:396
Bool testAlphaNum() const
String get(uInt st, uInt nd)
void skipCharNC(Char ch)
uInt len
Length of string.
Definition: MUString.h:392
Bool stat
Status of last get.
Definition: MUString.h:398
Bool eos() const
test for end of string
Bool tSkipChar(const Regex &ex)
Bool tSkipOneCharNC(Char ch)
uInt ptr
0-based pointer into string
Definition: MUString.h:390
void skipChar(Char ch)
MUString(const String &in)
Create from String; setting pointer at start.
Bool tSkipStringNC(const String &ex)
Bool tSkipOneChar(Char ch)
String lget
String found at last get.
Definition: MUString.h:400
String get()
Get part of string.
Bool testBlank() const
void skipSign()
Act on sign; return +1 or -1 depending on signs found (– == +)
void push()
Save current pointer on internal stack.
void skipString(const String &ex)
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
unsigned int uInt
Definition: aipstype.h:51
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
double Double
Definition: aipstype.h:55
char Char
Definition: aipstype.h:46
ostream & operator<<(ostream &os, const MUString &in)