casacore
MVTime.h
Go to the documentation of this file.
1 //# MVTime.h: Class to handle date/time type conversions and I/O
2 //# Copyright (C) 1996,1997,1998,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_MVTIME_H
29 #define CASA_MVTIME_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/Quanta/Quantum.h>
35 #include <casacore/casa/iosfwd.h>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward Declarations
40 class String;
41 class MVEpoch;
42 class Time;
43 
44 //# Constants (SUN compiler does not accept non-simple default arguments)
45 
46 // <summary>
47 // Class to handle date/time type conversions and I/O
48 // </summary>
49 
50 // <use visibility=export>
51 
52 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tMeasure" demos="">
53 // </reviewed>
54 
55 // <prerequisite>
56 // <li> <linkto class=Quantum>Quantum</linkto>
57 // <li> <linkto class=MVAngle>MVAngle</linkto>
58 // <li> <a href="http://mcps.k12.md.us/departments/year2000/Technology/ISO_std.html">
59 // ISO8601 standard</a> on dates and time.
60 // </prerequisite>
61 //
62 // <etymology>
63 // From Measure, Value and Time
64 // </etymology>
65 //
66 // <synopsis>
67 // An MVTime is a simple Double for date/time conversions and I/O.
68 // Its internal value is in MJD. For high precision the
69 // <linkto class=MVEpoch>MVEpoch</linkto> class should be used.<br>
70 // It can be constructed from a Double (in which case MJD are assumed),
71 // or from a Quantity (<src>Quantum<Double></src>). Quantities must be in
72 // either angle or time units, or from a
73 // <linkto class=MVEpoch>MVEpoch</linkto><br>
74 // The <linkto class=Time>OS/Time class</linkto> can be used as both input
75 // and output. An <src>MVTime(Time)</src> constructor exists, as well
76 // as a <src>Time getTime()</src>.<br>
77 // Construction from year, month, day is also supported.
78 // <note role=caution> Dates before 16 Oct 1582 are considered to be Julian,
79 // rather than Gregorian</note>
80 // It has an automatic conversion to Double, so all standard mathematical
81 // operations can operate on it.<br>
82 // The class has a number of special functions to obtain data:
83 // <ul>
84 // <li> <src>Double day()</src> will return value in days
85 // <li> <src>Double hour()</src> will return value in hours
86 // <li> <src>Double minute()</src> will return value in minutes
87 // <li> <src>Double second()</src> will return value in seconds
88 // <li> <src>Quantity get()</src> will return days
89 // <li> <src>Quantity get(Unit)</src> will return in specified units
90 // (angle(in which case it will be between -pi and +pi) or time)
91 // <li> <src>uInt weekday()</src> will return day of week (1=Mon, 7=Sun)
92 // <li> <src>uInt month()</src> will return month (1=Jan)
93 // <li> <src>Int year()</src> will return year
94 // <li> <src>uInt monthday()</src> will return day of the month
95 // <li> <src>uInt yearday()</src> will return day of year (Jan01 = 1)
96 // <li> <src>uInt yearweek()</src> will return week of year
97 // (week containing Jan04 = 1, week start on Monday).
98 // The week before the first week will be called 0, contrary
99 // to standard practice (week 53/52 of previous year).
100 // <li> <src>Int ymd()</src> will return yyyymmdd as a single number
101 // <li> <src>const String &dayName()</src> will return name of day
102 // (Sun, Mon, Tue, Wed, Thu, Fri, Sat)
103 // <li> <src>const String &monthName()</src> will retrun name of Month
104 // (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec)
105 // </ul>
106 // Output formatting is done with the <src><<</src> statement, with the
107 // following rules:
108 // <ul>
109 // <li> standard output is done in the following format:
110 // <src>hh:mm:ss.tt</src>. The number of
111 // digits presented will be based on the precision attached to the
112 // current stream
113 // <li> output can be formatted by using either the <src>setFormat()</src>
114 // method for global angle format setting, or the output of
115 // <src>MVTime::Format()</src> data for a once off change (see later).
116 // Formats have a first argument which
117 // determines the type (default, if not given, MVTime::TIME, other
118 // possibility MVTime::ANGLE (as +ddd.mm.ss.tt..),
119 // the second the number of digits wanted (default stream precision),
120 // with a value:
121 // <ul>
122 // <li> <3 : hh:: only
123 // <li> <5 : hh:mm:
124 // <li> <7 : hh:mm:ss
125 // <li> >6 : with precision-6 t's added
126 // </ul>
127 // comparable for angle. <note role=tip> The added colons are
128 // to enable input
129 // checking of the format. Look at the 'clean' types to bypass them.
130 // </note>
131 // The <src>MVTime::YMD</src> format implies TIME, and will
132 // precede the time with 'yyyy/mm/dd/' (or use
133 // <src>MVTime::YMD_ONLY</src> to include <src>NO_TIME</src>
134 // modifier).<br>
135 // The <src>MVTime::DMY</src> format implies TIME, and will
136 // precede the time with 'dd-Mon-yyyy/'.<br>
137 // The <src>MVTime::FITS</src> format implies TIME, and will
138 // precede the time with 'ccyy-mm-ddT'.
139 // The <src>BOOST</src> format implies DMY and USE_SPACE (space instead
140 // of slash between date and time).
141 // <br>
142 // The output format can be modified with modifiers (specify as
143 // MVTime::TIME | MVTime::MOD (or + MVTime::MOD)).
144 // <note role=caution> For overloading/casting
145 // problems with some compilers, the
146 // use of modifiers necessitates either the presence of a precision
147 // (i.e. <src>(A|B, prec)</src>), or an explicit cast:
148 // <src>((MVTime::formatTypes)(A|B))</src>, or make use of
149 // the provided <src>TIME[_CLEAN][_NO_H[M]]</src> and
150 // <src>ANGLE[_CLEAN][_NO_D[M]]</src>.
151 // </note>
152 //
153 // The modifiers can be:
154 // <ul>
155 // <li> <src>MVTime::CLEAN</src> to suppress leading or trailing
156 // periods (or colons for TIME). Note that he result can not be
157 // read automatically.
158 // <li> <src>MVTime::NO_H</src> (or <src>NO_D</src>) to suppress
159 // the output of hours (or degrees): useful for offsets
160 // <li> <src>MVTime::NO_HM</src> (or <src>NO_DM</src>), to
161 // suppress the degrees and minutes.
162 // <li> <src>MVTime::DAY</src> will precede the output with
163 // 'Day-' (e.g. Wed-). Space delimiter is used for USE_SPACE.
164 // <li> <src>MVTime::NO_TIME</src> will suppress printing of time.
165 // </ul>
166 // Output in formats like <src>20'</src> can be done via the standard
167 // Quantum output (e.g. <src> stream << time.get("'") </src>).
168 // <li> Available formats:
169 // <ul>
170 // <li> MVTime::ANGLE in +ddd.mm.ss.ttt format
171 // <li> MVTime::TIME in hh:mm:ss.ttt format
172 // <li> MVTime::[ANGLE|TIME]_CLEAN format without superfluous periods
173 // <li> MVTime::[ANGLE|TIME][_CLEAN]_NO_[D|H][M] in format with
174 // leading zero fields left empty.
175 // <li> MVTime::CLEAN modifier for suppressing superfluous periods
176 // <li> MVTime::USE_SPACE to use a space instead of a slash
177 // as delimiter between date and time.
178 // <li> MVTime::NO_[D|H][M] modifier to suppress first field(s)
179 // <li> MVTime::DIG2 modifier to get +dd.mm.ss.ttt in angle or
180 // time format(i.e. in range -90 - +90 or -12 - +12)
181 // <li> MVTime::LOCAL modifier to produce local time (as derived from
182 // aipsrc time.tzoffset). In FITS mode the time zone will
183 // be appended (as <src><sign>hh:mm</src>).
184 // <note role=caution>The adding of the timezone is not part
185 // of the FITS standard, but of the underlying ISO standard. It can
186 // be used to export local times in standard format.</note>
187 // </ul>
188 // </ul>
189 // The default formatting can be overwritten by a
190 // <src> MVTime::setFormat(); </src> statement; which returns an
191 // MVTime::Format
192 // structure, that can be used in a subsequent one to reset to previous.
193 // The format set holds for all MVTime output on all streams.<br>
194 // Temporary formats (i.e. for one MVTime output only), can be set by
195 // outputting a format (i.e. <src> stream << MVTime::Format() << ... </src>).
196 // <note role=caution> A setFormat() will also
197 // reset any lingering temporary format.
198 // A setFormat(getFormat()) will reset without changing. Problems could
199 // arise in parallel processors. </note>
200 // Input can be read if the values are in any of the above (non-clean) output
201 // formats. <br>
202 // For other formatting practice, the output can be written to a String with
203 // the string() member functions.<br>
204 // Note that using a temporary format is inherently thread-unsafe because
205 // the format is kept in a static variable. Another thread may overwrite
206 // the format just set. The only thread-safe way to format an MVTime is using
207 // a <src>print</src> or <src>string</src> that accepts a Format object.
208 //
209 // Strings and input can be converted to an MVTime (or Quantity) by
210 // <src>Bool read(Quantity &out, const String &in)</src> and
211 // <src> istream >> MVTime &</src>. In the latter case the actual
212 // reading is done by the String read, which reads between white-spaces.<br>
213 // The following input formats (note no blanks allowed) are supported
214 // (+stands for an optional + or -; v for an unsigned integer; dv for a
215 // floating number. [] indicate optional values. Separating codes are
216 // case insensitive), numbers(like yyyy) can be of any length.
217 // The separator between date and time part can be a slash (as shown below),
218 // a hyphen, or one or more spaces.
219 // <ul>
220 // <li> today -- (UT) time now
221 // <li> today/[time] -- time on today (0:0:0 if omitted)
222 // <li> yyyy/mm/dd[/time] -- date + time. An omitted date (leading /)
223 // will be today + time; an omitted month will
224 // indicate use of day number in year (1 == 1/1)
225 // <li> dd[-]MMM[-]yyyy[/time] -- date +time If yyyy <100: around 2000.
226 // MMM can be at least first three characters
227 // of month name; or a month number (1 == Jan).
228 // Omitted month indicates day is day number.
229 // <li> ccyy-mm-dd[Ttime[Z|+-hh[:mm]]] -- new FITS format the 'T' as time
230 // separator. Time should be UTC.
231 // The 'Z' separator (for UTC) is part of an
232 // earlier FITS proposal, and will be recognised
233 // for backward compatibility.
234 // A signed hh or hh:mm can be present to
235 // indicate time zone. This value will be
236 // subtracted to give UTC. To recognise this
237 // format, the year should be greater than 1000.
238 // <note role=caution> The time-zone information
239 // is not part of the FITS standard, but of the
240 // underlying ISO standard.</note>
241 // </ul>
242 // The time can be expressed as described in
243 // <linkto class=MVAngle>MVAngle</linkto>
244 // Examples of valid strings:
245 // <srcblock>
246 // ToDay note case independence
247 // 1996/11/20 20 November 1996 0h UT
248 // 1996/11/20/5:20 20 November 1996 at 5h20m
249 // 20Nov96-5h20m same (again no case dependence)
250 // 1996-11-20T5:20 same (FITS format, case dependent)
251 // </srcblock>
252 // </synopsis>
253 //
254 // <example>
255 // See synopsis
256 // </example>
257 //
258 // <motivation>
259 // To be able to format date/time-like values in user-required ways.
260 // </motivation>
261 //
262 // <todo asof="1996/11/15">
263 // <li> Nothing I know of
264 // </todo>
265 
266 class MVTime {
267 
268  public:
269 
270 //# Enumerations
271 // Format types
272  enum formatTypes {
275  CLEAN = 4,
276  NO_D = 8,
277  NO_DM = NO_D+16,
278  YMD = TIME+32,
279  DMY = TIME+64,
280  DAY = 128,
281  NO_TIME = 256,
282  MJD = TIME+512,
283  DIG2 = 1024,
284  FITS = TIME+2048,
285  LOCAL = 4096,
286  USE_SPACE = 8192,
287  ALPHA = 16384,
299  TIME_CLEAN_NO_H = TIME + CLEAN + NO_H,
302  MOD_MASK = CLEAN + NO_DM + DAY + NO_TIME + DIG2 +
303  LOCAL + USE_SPACE + ALPHA
304  };
305 
306 //# Local structure
307 // Format structure
308  class Format {
309  public:
310  friend class MVTime;
312  uInt inprec = 0) :
313  typ(intyp), prec(inprec) {;};
314  Format(uInt inprec) :
315  typ(MVTime::TIME), prec(inprec) {;};
316 // Construct from type and precision (present due to overlaoding problems)
317  Format(uInt intyp, uInt inprec) :
318  typ((MVTime::formatTypes)intyp), prec(inprec) {;};
319  Format(const Format &other) :
320  typ(other.typ), prec(other.prec) {;};
321  private:
324  };
325 
326 //# Friends
327 // Output a date/time
328  friend ostream &operator<<(ostream &os, const MVTime &meas);
329 // Input a date/time
330  friend istream &operator>>(istream &is, MVTime &meas);
331 // Set a temporary format
332  friend ostream &operator<<(ostream &os, const MVTime::Format &form);
333 
334 //# Constructors
335 // Default constructor: generate a zero value
336  MVTime();
337 // Copy constructor
338  MVTime(const MVTime &other);
339 // Copy assignment
340  MVTime &operator=(const MVTime &other);
341 // Constructor from Double (in MJD)
342  MVTime(Double d);
343 // Constructor from Quantum : value can be an angle or time
344 // <thrown>
345 // <li> AipsError if not a time or angle
346 // </thrown>
347  MVTime(const Quantity &other);
348 // Constructor from Time
349  MVTime(const Time &other);
350 // Constructor from MVEpoch;
351  MVTime(const MVEpoch &other);
352 // Constructor from yy, mm, dd, dd (all dd with fractions allowed)
353  MVTime(Int yy, Int mm, Double dd, Double d=0.0);
354 
355 //# Destructor
356  ~MVTime();
357 
358 //# Operators
359 // Conversion operator
360  operator Double() const;
361 
362 //# General member functions
363  // Make res time Quantity from string. The String version will accept
364  // a time/angle Quantity as well. The chk checks for eos
365  // <group>
366  static Bool read(Quantity &res, const String &in, Bool chk=True);
367  static Bool read(Quantity &res, MUString &in, Bool chk=True);
368  // </group>
369 // Get value of date/time (MJD) in given units
370 // <group>
371  Double day() const;
372  Double hour() const;
373  Double minute() const;
374  Double second() const;
375  Quantity get() const;
376  Quantity get(const Unit &inunit) const;
377  Time getTime() const;
378 // </group>
379 // Get indicated part of the time/date
380 // <group>
381  const String &dayName() const;
382  static const String &dayName(uInt which);
383  const String &monthName() const;
384  static const String &monthName(uInt which);
385  // Mon = 1; Sun = 7;
386  uInt weekday() const;
387  // Jan =1
388  uInt month() const;
389  uInt monthday() const;
390  Int year() const;
391  Int ymd() const;
392  uInt yearday() const;
393  uInt yearweek() const;
394 // </group>
395 // Output data.
396 // <note role=warning>
397 // The first function below is thread-unsafe because it uses the result of
398 // the setFormat function which changes a static class member.
399 // The other functions are thread-safe because the format is directly given.
400 // </note>
401 // <group>
402  String string() const;
403  String string(MVTime::formatTypes intyp, uInt inprec = 0) const;
404  String string(uInt intyp, uInt inprec) const;
405  String string(uInt inprec) const;
406  String string(const MVTime::Format &form) const;
407  void print(ostream &oss, const MVTime::Format &form) const;
408 // </group>
409 // Set default format
410 // <note role=warning>
411 // It is thread-unsafe to print using the setFormat functions because they
412 // change a static class member. The only thred-safe way to print a time is
413 // to use the print function above.
414 // </note>
415 // <group>
416  static Format setFormat(MVTime::formatTypes intyp,
417  uInt inprec = 0);
418  static Format setFormat(uInt intyp, uInt inprec);
419  static Format setFormat(uInt inprec = 0);
420  static Format setFormat(const Format &form);
421 // </group>
422  // Get default format
423  static Format getFormat();
424  // Get code belonging to string. 0 if not known
425  static MVTime::formatTypes giveMe(const String &in);
426  // Get time zone offset (in days)
427 static Double timeZone();
428 
429  private:
430 //# Data
431 // Value
433 // Default format
435 // Temporary format
436 // <group>
438  static Bool interimSet;
439 // </group>
440 
441 //# Member functions
442  // Get the y,m,d values
443  void ymd(Int &yyyy, Int &mm, Int &dd) const;
444 };
445 
446 // Global functions.
447 // Output
448 // <group>
449 ostream &operator<<(ostream &os, const MVTime &meas);
450 ostream &operator>>(ostream &is, MVTime &meas);
451 // Set a temporary format (thread-unsafe).
452 ostream &operator<<(ostream &os, const MVTime::Format &form);
453 // </group>
454 
455 // is equal operator, uses operator Double which returns days
456 inline Bool operator==(const MVTime &lh, const MVTime &rh)
457 { return (lh.operator Double() == rh.operator Double());}
458 
459 
460 
461 } //# NAMESPACE CASACORE - END
462 
463 #endif
Double hour() const
Double val
Value.
Definition: MVTime.h:432
int Int
Definition: aipstype.h:50
uInt month() const
Jan =1.
friend ostream & operator<<(ostream &os, const MVTime &meas)
Output a date/time.
void print(ostream &oss, const MVTime::Format &form) const
uInt monthday() const
friend class MVTime
Definition: MVTime.h:310
bool operator==(const std11_allocator< T > &, const std11_allocator< T > &)
Definition: Allocator.h:99
Format structure.
Definition: MVTime.h:308
uInt weekday() const
Mon = 1; Sun = 7;.
static MVTime::formatTypes giveMe(const String &in)
Get code belonging to string.
static Bool interimSet
Definition: MVTime.h:438
uInt yearweek() const
static Format getFormat()
Get default format.
static functions and enumerations
Definition: fits.h:165
Pointed String class to aid analysis of quantity strings.
Definition: MUString.h:229
Double day() const
Get value of date/time (MJD) in given units.
Format(MVTime::formatTypes intyp=MVTime::TIME, uInt inprec=0)
Definition: MVTime.h:311
Double second() const
Int year() const
static Double timeZone()
Get time zone offset (in days)
defines physical units
Definition: Unit.h:189
static Format setFormat(MVTime::formatTypes intyp, uInt inprec=0)
Set default format Warning: It is thread-unsafe to print using the setFormat functions because they ...
formatTypes
Format types.
Definition: MVTime.h:272
MVTime & operator=(const MVTime &other)
Copy assignment.
double Double
Definition: aipstype.h:55
date and time enquiry functions, with some operations.
Definition: Time.h:88
static Bool read(Quantity &res, const String &in, Bool chk=True)
Make res time Quantity from string.
const String & dayName() const
Get indicated part of the time/date.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
MVTime::formatTypes typ
Definition: MVTime.h:320
Time getTime() const
static MVTime::Format interimFormat
Temporary format.
Definition: MVTime.h:437
Format(const Format &other)
Definition: MVTime.h:319
uInt yearday() const
String string() const
Output data.
A class for high precision time.
Definition: MVEpoch.h:90
Int ymd() const
String: the storage and methods of handling collections of characters.
Definition: String.h:223
static MVTime::Format defaultFormat
Default format.
Definition: MVTime.h:434
friend istream & operator>>(istream &is, MVTime &meas)
Input a date/time.
Class to handle date/time type conversions and I/O.
Definition: MVTime.h:266
Format(uInt inprec)
Definition: MVTime.h:314
const String & monthName() const
const Bool True
Definition: aipstype.h:43
this file contains all the compiler specific defines
Definition: mainpage.dox:28
Format(uInt intyp, uInt inprec)
Construct from type and precision (present due to overlaoding problems)
Definition: MVTime.h:317
Double minute() const
unsigned int uInt
Definition: aipstype.h:51