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
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39//# Forward Declarations
40class String;
41class MVEpoch;
42class 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'.<br>
139// The <src>MVTime::ISO</src> format implies FITS followed by a Z
140// for the UTC time zone. It uses a space instead of T as separator.
141// It also implies CLEAN.
142// The <src>BOOST</src> format implies DMY and USE_SPACE (space instead
143// of slash between date and time).
144// <br>
145// The output format can be modified with modifiers (specify as
146// MVTime::TIME | MVTime::MOD (or + MVTime::MOD)).
147// <note role=caution> For overloading/casting
148// problems with some compilers, the
149// use of modifiers necessitates either the presence of a precision
150// (i.e. <src>(A|B, prec)</src>), or an explicit cast:
151// <src>((MVTime::formatTypes)(A|B))</src>, or make use of
152// the provided <src>TIME[_CLEAN][_NO_H[M]]</src> and
153// <src>ANGLE[_CLEAN][_NO_D[M]]</src>.
154// </note>
155//
156// The modifiers can be:
157// <ul>
158// <li> <src>MVTime::CLEAN</src> to suppress leading or trailing
159// periods (or colons for TIME). Note that he result can not be
160// read automatically.
161// <li> <src>MVTime::NO_H</src> (or <src>NO_D</src>) to suppress
162// the output of hours (or degrees): useful for offsets
163// <li> <src>MVTime::NO_HM</src> (or <src>NO_DM</src>), to
164// suppress the degrees and minutes.
165// <li> <src>MVTime::DAY</src> will precede the output with
166// 'Day-' (e.g. Wed-). Space delimiter is used for USE_SPACE.
167// <li> <src>MVTime::NO_TIME</src> will suppress printing of time.
168// </ul>
169// Output in formats like <src>20'</src> can be done via the standard
170// Quantum output (e.g. <src> stream << time.get("'") </src>).
171// <li> Available formats:
172// <ul>
173// <li> MVTime::ANGLE in +ddd.mm.ss.ttt format
174// <li> MVTime::TIME in hh:mm:ss.ttt format
175// <li> MVTime::[ANGLE|TIME]_CLEAN format without superfluous periods
176// <li> MVTime::[ANGLE|TIME][_CLEAN]_NO_[D|H][M] in format with
177// leading zero fields left empty.
178// <li> MVTime::CLEAN modifier for suppressing superfluous periods
179// <li> MVTime::USE_SPACE to use a space instead of a slash
180// as delimiter between date and time.
181// <li> MVTime::USE_Z to follow the time by a Z for the UTC time zone.
182// <li> MVTime::NO_[D|H][M] modifier to suppress first field(s)
183// <li> MVTime::DIG2 modifier to get +dd.mm.ss.ttt in angle or
184// time format(i.e. in range -90 - +90 or -12 - +12)
185// <li> MVTime::LOCAL modifier to produce local time (as derived from
186// aipsrc time.tzoffset). In FITS mode the time zone will
187// be appended (as <src><sign>hh:mm</src>).
188// <note role=caution>The adding of the timezone is not part
189// of the FITS standard, but of the underlying ISO standard. It can
190// be used to export local times in standard format.</note>
191// </ul>
192// </ul>
193// The default formatting can be overwritten by a
194// <src> MVTime::setFormat(); </src> statement; which returns an
195// MVTime::Format
196// structure, that can be used in a subsequent one to reset to previous.
197// The format set holds for all MVTime output on all streams.<br>
198// Temporary formats (i.e. for one MVTime output only), can be set by
199// outputting a format (i.e. <src> stream << MVTime::Format() << ... </src>).
200// <note role=caution> A setFormat() will also
201// reset any lingering temporary format.
202// A setFormat(getFormat()) will reset without changing. Problems could
203// arise in parallel processors. </note>
204// Input can be read if the values are in any of the above (non-clean) output
205// formats. <br>
206// For other formatting practice, the output can be written to a String with
207// the string() member functions.<br>
208// Note that using a temporary format is inherently thread-unsafe because
209// the format is kept in a static variable. Another thread may overwrite
210// the format just set. The only thread-safe way to format an MVTime is using
211// a <src>print</src> or <src>string</src> that accepts a Format object.
212//
213// Strings and input can be converted to an MVTime (or Quantity) by
214// <src>Bool read(Quantity &out, const String &in)</src> and
215// <src> istream >> MVTime &</src>. In the latter case the actual
216// reading is done by the String read, which reads between white-spaces.<br>
217// The following input formats (note no blanks allowed) are supported
218// (+stands for an optional + or -; v for an unsigned integer; dv for a
219// floating number. [] indicate optional values. Separating codes are
220// case insensitive), numbers(like yyyy) can be of any length.
221// The separator between date and time part can be a slash (as shown below),
222// a hyphen, or one or more spaces.
223// <ul>
224// <li> today -- (UT) time now
225// <li> today/[time] -- time on today (0:0:0 if omitted)
226// <li> yyyy/mm/dd[/time] -- date + time. An omitted date (leading /)
227// will be today + time; an omitted month will
228// indicate use of day number in year (1 == 1/1)
229// <li> dd[-]MMM[-]yyyy[/time] -- date +time If yyyy <100: around 2000.
230// MMM can be at least first three characters
231// of month name; or a month number (1 == Jan).
232// Omitted month indicates day is day number.
233// <li> ccyy-mm-dd[Ttime[Z|+-hh[:mm]]] -- new FITS format the 'T' as time
234// separator. Time should be UTC.
235// The 'Z' separator (for UTC) is part of an
236// earlier FITS proposal, and will be recognised
237// for backward compatibility.
238// A signed hh or hh:mm can be present to
239// indicate time zone. This value will be
240// subtracted to give UTC. To recognise this
241// format, the year should be greater than 1000.
242// <note role=caution> The time-zone information
243// is not part of the FITS standard, but of the
244// underlying ISO standard.</note>
245// </ul>
246// The time can be expressed as described in
247// <linkto class=MVAngle>MVAngle</linkto>
248// Examples of valid strings:
249// <srcblock>
250// ToDay note case independence
251// 1996/11/20 20 November 1996 0h UT
252// 1996/11/20/5:20 20 November 1996 at 5h20m
253// 20Nov96-5h20m same (again no case dependence)
254// 1996-11-20T5:20 same (FITS format, case dependent)
255// </srcblock>
256// </synopsis>
257//
258// <example>
259// See synopsis
260// </example>
261//
262// <motivation>
263// To be able to format date/time-like values in user-required ways.
264// </motivation>
265//
266// <todo asof="1996/11/15">
267// <li> Nothing I know of
268// </todo>
269
270class MVTime {
271
272 public:
273
274//# Enumerations
275// Format types
279 CLEAN = 4,
280 NO_D = 8,
282 YMD = TIME+32,
283 DMY = TIME+64,
284 DAY = 128,
285 NO_TIME = 256,
286 MJD = TIME+512,
287 DIG2 = 1024,
288 FITS = TIME+2048,
289 LOCAL = 4096,
290 USE_SPACE = 8192,
291 ALPHA = 16384,
292 USE_Z = 32768,
308 MOD_MASK = CLEAN + NO_DM + DAY + NO_TIME + DIG2 +
310 };
311
312//# Local structure
313// Format structure
314 class Format {
315 public:
316 friend class MVTime;
318 uInt inprec = 0) :
319 typ(intyp), prec(inprec) {;};
320 Format(uInt inprec) :
321 typ(MVTime::TIME), prec(inprec) {;};
322// Construct from type and precision (present due to overlaoding problems)
323 Format(uInt intyp, uInt inprec) :
324 typ((MVTime::formatTypes)intyp), prec(inprec) {;};
325 private:
328 };
329
330//# Friends
331// Output a date/time
332 friend ostream &operator<<(ostream &os, const MVTime &meas);
333// Input a date/time
334 friend istream &operator>>(istream &is, MVTime &meas);
335// Set a temporary format
336 friend ostream &operator<<(ostream &os, const MVTime::Format &form);
337
338//# Constructors
339// Default constructor: generate a zero value
341// Copy constructor
342 MVTime(const MVTime &other);
343// Copy assignment
344 MVTime &operator=(const MVTime &other);
345// Constructor from Double (in MJD)
347// Constructor from Quantum : value can be an angle or time
348// <thrown>
349// <li> AipsError if not a time or angle
350// </thrown>
351 MVTime(const Quantity &other);
352// Constructor from Time
353 MVTime(const Time &other);
354// Constructor from MVEpoch;
355 MVTime(const MVEpoch &other);
356// Constructor from yy, mm, dd, dd (all dd with fractions allowed)
357 MVTime(Int yy, Int mm, Double dd, Double d=0.0);
358
359//# Destructor
361
362//# Operators
363// Conversion operator
364 operator Double() const;
365
366//# General member functions
367 // Make res time Quantity from string. The String version will accept
368 // a time/angle Quantity as well. It returns False in case of an error.
369 // chk=True means that the entire string should be consumed.
370 // throwExcp=True means that an exception is thrown in case of an error.
371 // <group>
372 static Bool read(Quantity &res, const String &in, Bool chk=True);
373 static Bool read(Quantity &res, MUString &in, Bool chk=True);
374 static Bool read(Quantity &res, const String &in, Bool chk, Bool throwExcp);
375 static Bool read(Quantity &res, MUString &in, Bool chk, Bool throwExcp);
376 // </group>
377// Get value of date/time (MJD) in given units
378// <group>
379 Double day() const;
380 Double hour() const;
381 Double minute() const;
382 Double second() const;
383 Quantity get() const;
384 Quantity get(const Unit &inunit) const;
385 Time getTime() const;
386// </group>
387// Get indicated part of the time/date
388// <group>
389 const String &dayName() const;
390 static const String &dayName(uInt which);
391 const String &monthName() const;
392 static const String &monthName(uInt which);
393 // Mon = 1; Sun = 7;
394 uInt weekday() const;
395 // Jan =1
396 uInt month() const;
397 uInt monthday() const;
398 Int year() const;
399 Int ymd() const;
400 uInt yearday() const;
401 uInt yearweek() const;
402// </group>
403// Output data.
404// <note role=warning>
405// The first function below is thread-unsafe because it uses the result of
406// the setFormat function which changes a static class member.
407// The other functions are thread-safe because the format is directly given.
408// </note>
409// <group>
410 String string() const;
411 String string(MVTime::formatTypes intyp, uInt inprec = 0) const;
412 String string(uInt intyp, uInt inprec) const;
413 String string(uInt inprec) const;
414 String string(const MVTime::Format &form) const;
415 void print(ostream &oss, const MVTime::Format &form) const;
416// </group>
417// Set default format
418// <note role=warning>
419// It is thread-unsafe to print using the setFormat functions because they
420// change a static class member. The only thred-safe way to print a time is
421// to use the print function above.
422// </note>
423// <group>
425 uInt inprec = 0);
426 static Format setFormat(uInt intyp, uInt inprec);
427 static Format setFormat(uInt inprec = 0);
428 static Format setFormat(const Format &form);
429// </group>
430 // Get default format
432 // Get code belonging to string. 0 if not known
434 // Get time zone offset (in days)
436
437 private:
438//# Data
439// Value
441// Default format
443// Temporary format
444// <group>
447// </group>
448
449//# Member functions
450 // Get the y,m,d values
451 void ymd(Int &yyyy, Int &mm, Int &dd) const;
452};
453
454// Global functions.
455// Output
456// <group>
457ostream &operator<<(ostream &os, const MVTime &meas);
458ostream &operator>>(ostream &is, MVTime &meas);
459// Set a temporary format (thread-unsafe).
460ostream &operator<<(ostream &os, const MVTime::Format &form);
461// </group>
462
463// is equal operator, uses operator Double which returns days
464inline Bool operator==(const MVTime &lh, const MVTime &rh)
465{ return (lh.operator Double() == rh.operator Double());}
466
467
468
469} //# NAMESPACE CASACORE - END
470
471#endif
static functions and enumerations
Definition: fits.h:161
Format structure.
Definition: MVTime.h:314
MVTime::formatTypes typ
Definition: MVTime.h:326
Format(uInt inprec)
Definition: MVTime.h:320
Format(MVTime::formatTypes intyp=MVTime::TIME, uInt inprec=0)
Definition: MVTime.h:317
Format(uInt intyp, uInt inprec)
Construct from type and precision (present due to overlaoding problems)
Definition: MVTime.h:323
MVTime(Int yy, Int mm, Double dd, Double d=0.0)
Constructor from yy, mm, dd, dd (all dd with fractions allowed)
static Bool read(Quantity &res, const String &in, Bool chk=True)
Make res time Quantity from string.
String string(uInt intyp, uInt inprec) const
String string(const MVTime::Format &form) const
MVTime(const MVTime &other)
Copy constructor.
formatTypes
Format types.
Definition: MVTime.h:276
Int ymd() const
uInt weekday() const
Mon = 1; Sun = 7;.
Double second() const
MVTime(Double d)
Constructor from Double (in MJD)
uInt yearday() const
static Format getFormat()
Get default format.
Double day() const
Get value of date/time (MJD) in given units.
static Bool interimSet
Definition: MVTime.h:446
MVTime(const Quantity &other)
Constructor from Quantum : value can be an angle or time.
Double val
Value.
Definition: MVTime.h:440
MVTime()
Default constructor: generate a zero value.
static const String & dayName(uInt which)
Double minute() const
static Double timeZone()
Get time zone offset (in days)
void ymd(Int &yyyy, Int &mm, Int &dd) const
Get the y,m,d values.
Time getTime() const
uInt yearweek() const
static Format setFormat(uInt intyp, uInt inprec)
static Format setFormat(const Format &form)
static MVTime::Format defaultFormat
Default format.
Definition: MVTime.h:442
const String & dayName() const
Get indicated part of the time/date.
static MVTime::Format interimFormat
Temporary format.
Definition: MVTime.h:445
void print(ostream &oss, const MVTime::Format &form) const
static Bool read(Quantity &res, const String &in, Bool chk, Bool throwExcp)
friend ostream & operator<<(ostream &os, const MVTime &meas)
Output a date/time.
static Format setFormat(uInt inprec=0)
friend istream & operator>>(istream &is, MVTime &meas)
Input a date/time.
uInt monthday() const
uInt month() const
Jan =1.
MVTime(const Time &other)
Constructor from Time.
friend ostream & operator<<(ostream &os, const MVTime::Format &form)
Set a temporary format.
Int year() const
String string() const
Output data.
static Bool read(Quantity &res, MUString &in, Bool chk, Bool throwExcp)
static Bool read(Quantity &res, MUString &in, Bool chk=True)
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 ...
String string(MVTime::formatTypes intyp, uInt inprec=0) const
Quantity get() const
static MVTime::formatTypes giveMe(const String &in)
Get code belonging to string.
const String & monthName() const
Quantity get(const Unit &inunit) const
MVTime & operator=(const MVTime &other)
Copy assignment.
String string(uInt inprec) const
static const String & monthName(uInt which)
Double hour() const
MVTime(const MVEpoch &other)
Constructor from MVEpoch;.
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
AipsIO & operator>>(AipsIO &os, Record &rec)
Definition: Record.h:465
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
unsigned int uInt
Definition: aipstype.h:51
bool operator==(const casacore_allocator< T, ALIGNMENT > &, const casacore_allocator< T, ALIGNMENT > &)
Definition: Allocator.h:129
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43
double Double
Definition: aipstype.h:55