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>
casacore::Time::modifiedJulianDay
double modifiedJulianDay() const
return the modified Julian day (unit day)
casacore::Time::now
void now()
reset date to the present instant
casacore::Time::operator!=
Bool operator!=(const Time &other) const
casacore::Time::hours
uInt hours()
casacore::Time
Definition: Time.h:88
casacore::Time::operator<<
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
casacore::Time::timeZoneName
static String timeZoneName()
Returns a string, e.g.
casacore::Time::operator=
Time & operator=(const Time &time)
initialise the julian day data with Time class
casacore::C::hour
const Double hour
hour
casacore::Time::setDate
void setDate(uInt year, uInt month, uInt day, uInt hour=0, uInt min=0, double sec=0.0)
casacore::Time::timeZoneDays
static Double timeZoneDays()
Same as timeZoneSeconds(), but returns fractional days rather than seconds.
casacore::Time::dayOfWeek
uInt dayOfWeek()
casacore::Time::minutes
uInt minutes()
casacore::Time::age
double age()
number of seconds which have elapsed since Time object was created or reset
casacore::Time::ISODate
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
casacore::Time::julianDay
double julianDay() const
return the Julian day (unit day)
casacore::Time::timeZoneSeconds
static Int timeZoneSeconds()
Returns the difference, in seconds, between UTC and local time.
casacore::Time::operator-
double operator-(const Time &begin)
casacore::Double
double Double
Definition: aipstype.h:55
casacore::Time::dayOfMonth
uInt dayOfMonth()
casacore::Time::howManyDaysInMonth
static uInt howManyDaysInMonth()
casacore::Time::Time
Time(const Time &time)
Copy constructor.
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::Time::isLeapYear
static Bool isLeapYear()
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::Time::Time
Time(uInt year, uInt month, uInt day, uInt hour=0, uInt min=0, double sec=0.0)
Construct Time with Gregorian calendar.
casacore::min
LatticeExprNode min(const LatticeExprNode &left, const LatticeExprNode &right)
casacore::Time::toString
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...
casacore::Time::month
uInt month()
casacore::Time::year
uInt year()
casacore::Int
int Int
Definition: aipstype.h:50
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::Time::operator<
Bool operator<(const Time &other) const
casacore::True
const Bool True
Definition: aipstype.h:43
casacore::time
TableExprNode time(const TableExprNode &node)
Definition: ExprNode.h:1537
casacore::Time::mJulianDay
uInt mJulianDay
Modified Julian day number 40587 modified Julian day number = 00:00:00 January 1, 1970,...
Definition: Time.h:200
casacore::Time::mJulianDayfrac
double mJulianDayfrac
the fraction of the day
Definition: Time.h:202
casacore::Time::dayOfYear
uInt dayOfYear()
casacore::Time::operator+
Time operator+(const double plus)
casacore::Time::seconds
uInt seconds()
Return the seconds, minutes or hour part of the time.
casacore::Time::operator==
Bool operator==(const Time &other) const
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::Time::dseconds
double dseconds()
casacore::Time::operator>
Bool operator>(const Time &other) const
casacore::Time::Time
Time()
the default constructor returns an object with the present date and time
casacore::Time::isLeapYear
static Bool isLeapYear(uInt year)
casacore::day
TableExprNode day(const TableExprNode &node)
Definition: ExprNode.h:1480
casacore::Time::Time
Time(double jdn)
Construct time with Julian day number.
casacore::Time::howManyDaysInMonth
static uInt howManyDaysInMonth(uInt month, uInt year)
casacore::Time::operator>>
friend istream & operator>>(istream &, Time &)
read in date, which must be in the following format month/day/year,hour:min:sec where month,...