casacore
Time.h
Go to the documentation of this file.
1 //# Time.h: enquiry functions for calendar and clock time, with some operations
2 //# Copyright (C) 1994,1995,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 
27 //# $Id$
28 
29 #ifndef CASA_TIME_H
30 #define CASA_TIME_H
31 
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/BasicSL/String.h>
34 #include <casacore/casa/iosfwd.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 // <Summary> date and time enquiry functions, with some operations.
39 // </summary>
40 //
41 // <use visibility=export>
42 //
43 // <reviewed reviewer="Paul Shannon" date="1995/03/01" tests="tTime" demos="">
44 // This class might be better named a Date object, especially given that
45 // more accurate Time classes are going to be required.
46 // </reviewed>
47 
48 // <prerequisite>
49 // <li> you should understand the difference between "Julian" and
50 // "modified Julian" date
51 // </prerequisite>
52 
53 // <synopsis>
54 // This class provides convenient date objects for the programmer.
55 // Once constructed, they may be compared, read and written, and
56 // queried for a wide variety of re-expressions. In a typical (?) use
57 // you might create a Time object, and then query it to find out
58 // the current month, day of the week, and whether it is a leap
59 // year. You can also find out the number of seconds which have elapsed
60 // since a specific Time.
61 //
62 // <note role=caution> This class should not be used for very high precision
63 // work. The time from epoch (1970.0) in seconds is
64 // interconverted between computer "double" values, and
65 // some loss of accuracy might result.
66 // </note>
67 // </synopsis>
68 
69 // <example>
70 // <srcblock>
71 // Time startTime;
72 // Time moonLanding (1969,7,14);
73 // cout << "date and time of moon landing: " << moonLanding << endl;
74 // cout << "day of week: " << moonLanding.dayOfWeek () << endl;
75 // cout << "day of year: " << moonLanding.dayOfYear () << endl;
76 // cout << "seconds since moon landing: " << moonLanding.age () << endl;
77 // cout << "weeks since moon landing: " <<
78 // moonLanding.age () / (60 * 60 * 24 * 7) << endl;
79 // cout << "seconds elapsed since start: " << startTime.age () << endl;
80 // </srcblock>
81 // </example>
82 //
83 
84 // <todo asof="1995/03/23">
85 // <li> member function 'age' might be renamed 'elapsedTime'
86 // <li> A reference to the source of each algorithm should be provided.
87 // </todo>
88 class Time {
89 
90  public:
91  // the default constructor returns an object with the present date and time
92  Time ();
93  // Construct time with Julian day number
94  Time (double jdn);
95  // Construct Time with Gregorian calendar
96  // <ul>
97  // <li> seconds after the minute [0,59.999] (include milliseconds)
98  // <li> minutes after the hour [0,59]
99  // <li> hours after midnight [0,23]
100  // <li> day of the month [1,31]
101  // <li> month of the year [1,12]
102  // <li> year. Beware, because '94' refers to the early Christian era, not
103  // the 20th century.
104  // </ul>
106  double sec=0.0);
107 
108  // Copy constructor
109  Time (const Time& time);
110 
111  // return the Julian day (unit day)
112  double julianDay () const;
113  // return the modified Julian day (unit day)
114  double modifiedJulianDay () const;
115 
116  // initialise the julian day data with Time class
118 
119  double operator - (const Time& begin);
120  Time operator + (const double plus);
121 
122  Bool operator == (const Time& other) const;
123  Bool operator != (const Time& other) const;
124  Bool operator > (const Time& other) const;
125  Bool operator < (const Time& other) const;
126 
127  // if iso is True, then use ISO 8601 format
128  // otherwise, produce the string of the form
129  // Tue Mar 22 16:40:24 1994
130  // with GMT time
131  String toString(const Bool iso=False) const;
132 
133  // returns a String in ISO 8601 format YYYY-MM-DDTHH:MM:SS in GMT
134  // note: for dates beyond year 9999, use more digits for year
135  const String ISODate() const
136  { return toString(True); }
137 
138  // write the current time, GMT, in format
139  // Tue Mar 22 16:40:24 1994
140  friend ostream& operator<<(ostream& out, const Time& other)
141  {
142  out << other.toString(False);
143  return out;
144  }
145 
146  // read in date, which must be in the following format
147  // month/day/year,hour:min:sec
148  // where month,day,year,hour,min and sec are uInt.
149  friend istream& operator >> (istream&, Time&);
150 
151  // reset date to the present instant
152  void now ();
154  double sec=0.0);
155 
156  // number of seconds which have elapsed since Time object was created
157  // or reset
158  double age ();
159 
160  // Return the seconds, minutes or hour part of the time.
161  // <group>
163  double dseconds ();
166  // </group>
167 
170 
171  uInt year ();
172 
174 
175 
177 
179 
181 
182  static Bool isLeapYear ();
183 
185 
186  // Returns the difference, in seconds, between UTC and local time.
187  // Negative values are west of GMT, positive are east.
188  static Int timeZoneSeconds ();
189  // Same as timeZoneSeconds(), but returns fractional days rather
190  // than seconds.
191  static Double timeZoneDays ();
192  // Returns a string, e.g. "EST" or "MDT", describing the current
193  // local time zone.
194  static String timeZoneName ();
195 
196  protected:
197 
198  // Modified Julian day number
199  // 40587 modified Julian day number = 00:00:00 January 1, 1970, GMT.
201  // the fraction of the day
203 
204 };
205 
206 
207 } //# NAMESPACE CASACORE - END
208 
209 #endif
210 //# roel's original comments -- these may be useful in creating demo
211 //# programs when we get some time...
212 
213 //# The function now () updated datas with the present time.
214 //
215 //# When create a object. The mJulianDay and mJulianDayfrac datas are
216 //# initialise with actual modified Julian day. (<now() function).
217 //# The default constructor is at preset time.
218 //#
219 //# i.e. 40587 modified Julian day number = 00:00:00 January 1, 1970, GMT.
220 //# and 2440587.5 Julian day number = 00:00:00 January 1, 1970, GMT,
221 //# then modified Julian day number = Julian day number - 2400000.5
222 //#
223 //# Important :We are consindered GMT time for all functions.
224 //# We are considered only dates after 2400000 Julian day = 12:00:00
225 //# November 15, 1858, GMT.
226 //#
227 //# When execute the now() function the actual mJulianDay and
228 //# mJulianDayFrac datas are replace for the new modified Julian day
229 //# and the fraction of the day.
230 //#
231 //# The function is invoked looks as follows
232 //#
233 //# <code>
234 //#
235 //# Time t; // The default constructor is at present time (now())
236 //#
237 //# t.now();
238 //#
239 //# </code>
240 //#
241 //# When execute the setDate() function the actual mJulianDay and
242 //# mJulianDayFrac datas are replace for the new date
243 //#
244 //# The function is invoked looks as follows
245 //#
246 //# <code>
247 //#
248 //# Time t; // The default constructor is at present time (now())
249 //#
250 //# t.setDate(1915,2,21);
251 //#
252 //# </code>
253 //#
254 //# The function age() return the time in seconds between
255 //# some Time object and now.
256 //#
257 //# The function is invoked looks as follows
258 //#
259 //# <code>
260 //#
261 //# Time t; // The default constructor is at present time (now())
262 //#
263 //# cout<<"time since x "<< t.age() <<"\n";
264 //#
265 //# </code>
266 //#
267 //# The function julianDay() return the julian day number.
268 //#
269 //# The function is invoked looks as follows
270 //#
271 //# <code>
272 //#
273 //# Time t;
274 //#
275 //# cout<<"Julian day number "<<t.julianDay()<<"\n";
276 //#
277 //# </code>
278 //#
279 //# The function modifiedJulianDay() return the modified julian day number.
280 //#
281 //# The function is invoked looks as follows
282 //#
283 //# <code>
284 //#
285 //# Time t;
286 //#
287 //# cout<<"Modified Julian day number "<<t.modifiedJulianDay()<<"\n";
288 //#
289 //# </code>
290 //#
291 //# The function dayOfMonth() return day of the month [1,31]
292 //# Note: This function doesn't modified the actual datas (mJulianDay and '
293 //# mJulianDayFrac).
294 //#
295 //# The function is invoked looks as follows
296 //#
297 //# <code>
298 //#
299 //# Time t;
300 //#
301 //#
302 //# cout<<"day of month "<< t.dayOfMonth() <<"\n";
303 //#
304 //# </code>
305 //#
306 //# The function month() return month of the year [1,12]
307 //# Note: This function doesn't modified the actual datas (mJulianDay and '
308 //# mJulianDayFrac).
309 //#
310 //# The function is invoked looks as follows
311 //#
312 //# <code>
313 //#
314 //# Time t;
315 //#
316 //#
317 //# cout<<"month "<< t.month() <<"\n";
318 //#
319 //# </code>
320 //#
321 //# The function year() return the year.
322 //# Note: This function doesn't modified the actual datas (mJulianDay and '
323 //# mJulianDayFrac).
324 //#
325 //# The function is invoked looks as follows
326 //#
327 //# <code>
328 //#
329 //# Time t;
330 //#
331 //#
332 //# cout<<"Year "<< t.year() <<"\n";
333 //#
334 //# </code>
335 //#
336 //# The function dayOfWeek() return days since sunday [1,7].
337 //# Note: This function doesn't modified the actual datas (mJulianDay and '
338 //# mJulianDayFrac).
339 //#
340 //# The function is invoked looks as follows
341 //#
342 //# <code>
343 //#
344 //# Time t;
345 //#
346 //#
347 //# cout<<"day of week "<< t.dayOfWeek() <<"\n";
348 //#
349 //# </code>
350 //#
351 //# The function dayOfYear() return day of the year [1,366]
352 //# Note: This function doesn't modified the actual datas (mJulianDay and '
353 //# mJulianDayFrac).
354 //#
355 //# The function is invoked looks as follows
356 //#
357 //# <code>
358 //#
359 //# Time t;
360 //#
361 //#
362 //# cout<<"day of year "<< t.dayOfYear() <<"\n";
363 //#
364 //# </code>
365 //#
366 //# The function leapSeconds() return leap seconds.
367 //# We have the next datas
368 //#
369 //# -Note: leapSeconds() removed 1997.10.07 by Jeff Uphoff, after
370 //# -recommendation by Wim Brouw.
371 //#
372 //# leapsec=10;
373 //#
374 //# if(modified Julian Day>=41499) leapsec++; // 1 July 1972
375 //# if(modified Julian Day>=41683) leapsec++; // 1 January 1973
376 //# if(modified Julian Day>=42048) leapsec++; // 1 January 1974
377 //# if(modified Julian Day>=42413) leapsec++; // 1 January 1975
378 //# if(modified Julian Day>=42778) leapsec++; // 1 January 1976
379 //# if(modified Julian Day>=43144) leapsec++; // 1 January 1977
380 //# if(modified Julian Day>=43509) leapsec++; // 1 January 1978
381 //# if(modified Julian Day>=43874) leapsec++; // 1 January 1979
382 //# if(modified Julian Day>=44239) leapsec++; // 1 January 1980
383 //# if(modified Julian Day>=44786) leapsec++; // 1 July 1981
384 //# if(modified Julian Day>=45151) leapsec++; // 1 July 1982
385 //# if(modified Julian Day>=45516) leapsec++; // 1 July 1983
386 //# if(modified Julian Day>=46247) leapsec++; // 1 July 1985
387 //# if(modified Julian Day>=47161) leapsec++; // 1 January 1988
388 //# if(modified Julian Day>=47892) leapsec++; // 1 January 1990
389 //# if(modified Julian Day>=48257) leapsec++; // 1 January 1991
390 //# if(modified Julian Day>=48804) leapsec++; // 1 July 1992
391 //# if(modified Julian Day>=49169) leapsec++; // 1 July 1993
392 //#
393 //# The function is invoked looks as follows
394 //#
395 //# <code>
396 //#
397 //# Time t;
398 //#
399 //# cout<<"Leap seconds "<< t.leapSeconds() <<"\n";
400 //#
401 //# </code>
402 //#
403 //# The function howManyDaysInMonth() return how many days are in a month.
404 //#
405 //# The function is invoked looks as follows
406 //#
407 //# <code>
408 //#
409 //# Time t;
410 //# uInt month=1,month2=2,year=1992;
411 //#
412 //# cout<<"how many days are in this month "<< howManyDaysInMonth() <<"\n"
413 //# cout<<"how many days are in January "<< howManyDaysInMonth(month) <<"\n";
414 //# cout<<"how many days are in february of 1992 "<<
415 //# howManyDaysInMonth(month,year) <<"\n"; // 1992 is a leap year
416 //#
417 //# </code>
418 //#
419 //# The function isLeapYear() return bool value. True if is a leap year
420 //# and False in other case.
421 //#
422 //# The function is invoked looks as follows
423 //#
424 //# <code>
425 //#
426 //# Time t;
427 //#
428 //# uInt year=1992;
429 //#
430 //# if(isLeapYear(year))
431 //# cout<<"Is a leap year";
432 //#
433 //# if(isLeapYear())
434 //# cout<<"This year is a leap year";
435 //#
436 //# </code>
String: the storage and methods of handling collections of characters.
Definition: String.h:225
void now()
reset date to the present instant
friend istream & operator>>(istream &, Time &)
read in date, which must be in the following format month/day/year,hour:min:sec where month,...
Time(uInt year, uInt month, uInt day, uInt hour=0, uInt min=0, double sec=0.0)
Construct Time with Gregorian calendar.
double age()
number of seconds which have elapsed since Time object was created or reset
double operator-(const Time &begin)
double dseconds()
Time(double jdn)
Construct time with Julian day number.
Bool operator<(const Time &other) const
static uInt howManyDaysInMonth(uInt month, uInt year)
static Bool isLeapYear()
double mJulianDayfrac
the fraction of the day
Definition: Time.h:202
Bool operator>(const Time &other) const
static Double timeZoneDays()
Same as timeZoneSeconds(), but returns fractional days rather than seconds.
Time operator+(const double plus)
String toString(const Bool iso=False) const
if iso is True, then use ISO 8601 format otherwise, produce the string of the form Tue Mar 22 16:40:2...
static uInt howManyDaysInMonth()
void setDate(uInt year, uInt month, uInt day, uInt hour=0, uInt min=0, double sec=0.0)
double julianDay() const
return the Julian day (unit day)
static Bool isLeapYear(uInt year)
uInt mJulianDay
Modified Julian day number 40587 modified Julian day number = 00:00:00 January 1, 1970,...
Definition: Time.h:200
friend ostream & operator<<(ostream &out, const Time &other)
write the current time, GMT, in format Tue Mar 22 16:40:24 1994
Definition: Time.h:140
double modifiedJulianDay() const
return the modified Julian day (unit day)
static Int timeZoneSeconds()
Returns the difference, in seconds, between UTC and local time.
const String ISODate() const
returns a String in ISO 8601 format YYYY-MM-DDTHH:MM:SS in GMT note: for dates beyond year 9999,...
Definition: Time.h:135
Time & operator=(const Time &time)
initialise the julian day data with Time class
Time()
the default constructor returns an object with the present date and time
uInt seconds()
Return the seconds, minutes or hour part of the time.
Time(const Time &time)
Copy constructor.
Bool operator==(const Time &other) const
static String timeZoneName()
Returns a string, e.g.
Bool operator!=(const Time &other) const
const Double hour
hour
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
TableExprNode time(const TableExprNode &node)
Definition: ExprNode.h:1580
unsigned int uInt
Definition: aipstype.h:51
LatticeExprNode min(const LatticeExprNode &left, const LatticeExprNode &right)
TableExprNode day(const TableExprNode &node)
Definition: ExprNode.h:1523
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