1 | // |
---|
2 | // DateTime.h |
---|
3 | // |
---|
4 | // $Id: //poco/1.3/Foundation/include/Poco/DateTime.h#3 $ |
---|
5 | // |
---|
6 | // Library: Foundation |
---|
7 | // Package: DateTime |
---|
8 | // Module: DateTime |
---|
9 | // |
---|
10 | // Definition of the DateTime class. |
---|
11 | // |
---|
12 | // Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH. |
---|
13 | // and Contributors. |
---|
14 | // |
---|
15 | // Permission is hereby granted, free of charge, to any person or organization |
---|
16 | // obtaining a copy of the software and accompanying documentation covered by |
---|
17 | // this license (the "Software") to use, reproduce, display, distribute, |
---|
18 | // execute, and transmit the Software, and to prepare derivative works of the |
---|
19 | // Software, and to permit third-parties to whom the Software is furnished to |
---|
20 | // do so, all subject to the following: |
---|
21 | // |
---|
22 | // The copyright notices in the Software and this entire statement, including |
---|
23 | // the above license grant, this restriction and the following disclaimer, |
---|
24 | // must be included in all copies of the Software, in whole or in part, and |
---|
25 | // all derivative works of the Software, unless such copies or derivative |
---|
26 | // works are solely in the form of machine-executable object code generated by |
---|
27 | // a source language processor. |
---|
28 | // |
---|
29 | // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
---|
30 | // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
---|
31 | // FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT |
---|
32 | // SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE |
---|
33 | // FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, |
---|
34 | // ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
---|
35 | // DEALINGS IN THE SOFTWARE. |
---|
36 | // |
---|
37 | |
---|
38 | |
---|
39 | #ifndef Foundation_DateTime_INCLUDED |
---|
40 | #define Foundation_DateTime_INCLUDED |
---|
41 | |
---|
42 | |
---|
43 | #include "Poco/Foundation.h" |
---|
44 | #include "Poco/Timestamp.h" |
---|
45 | #include "Poco/Timespan.h" |
---|
46 | |
---|
47 | |
---|
48 | namespace Poco { |
---|
49 | |
---|
50 | |
---|
51 | class Foundation_API DateTime |
---|
52 | /// This class represents an instant in time, expressed |
---|
53 | /// in years, months, days, hours, minutes, seconds |
---|
54 | /// and milliseconds based on the Gregorian calendar. |
---|
55 | /// The class is mainly useful for conversions between |
---|
56 | /// UTC, Julian day and Gregorian calendar dates. |
---|
57 | /// |
---|
58 | /// The date and time stored in a DateTime is always in UTC |
---|
59 | /// (Coordinated Universal Time) and thus independent of the |
---|
60 | /// timezone in effect on the system. |
---|
61 | /// |
---|
62 | /// Conversion calculations are based on algorithms |
---|
63 | /// collected and described by Peter Baum at |
---|
64 | /// http://vsg.cape.com/~pbaum/date/date0.htm |
---|
65 | /// |
---|
66 | /// Internally, this class stores a date/time in two |
---|
67 | /// forms (UTC and broken down) for performance reasons. Only use |
---|
68 | /// this class for conversions between date/time representations. |
---|
69 | /// Use the Timestamp class for everything else. |
---|
70 | /// |
---|
71 | /// Notes: |
---|
72 | /// * Zero is a valid year (in accordance with ISO 8601 and astronomical year numbering) |
---|
73 | /// * Year zero (0) is a leap year |
---|
74 | /// * Negative years (years preceding 1 BC) are not supported |
---|
75 | /// |
---|
76 | /// For more information, please see: |
---|
77 | /// * http://en.wikipedia.org/wiki/Gregorian_Calendar |
---|
78 | /// * http://en.wikipedia.org/wiki/Julian_day |
---|
79 | /// * http://en.wikipedia.org/wiki/UTC |
---|
80 | /// * http://en.wikipedia.org/wiki/ISO_8601 |
---|
81 | { |
---|
82 | public: |
---|
83 | enum Months |
---|
84 | /// Symbolic names for month numbers (1 to 12). |
---|
85 | { |
---|
86 | JANUARY = 1, |
---|
87 | FEBRUARY, |
---|
88 | MARCH, |
---|
89 | APRIL, |
---|
90 | MAY, |
---|
91 | JUNE, |
---|
92 | JULY, |
---|
93 | AUGUST, |
---|
94 | SEPTEMBER, |
---|
95 | OCTOBER, |
---|
96 | NOVEMBER, |
---|
97 | DECEMBER |
---|
98 | }; |
---|
99 | |
---|
100 | enum DaysOfWeek |
---|
101 | /// Symbolic names for week day numbers (0 to 6). |
---|
102 | { |
---|
103 | SUNDAY = 0, |
---|
104 | MONDAY, |
---|
105 | TUESDAY, |
---|
106 | WEDNESDAY, |
---|
107 | THURSDAY, |
---|
108 | FRIDAY, |
---|
109 | SATURDAY |
---|
110 | }; |
---|
111 | |
---|
112 | DateTime(); |
---|
113 | /// Creates a DateTime for the current date and time. |
---|
114 | |
---|
115 | DateTime(const Timestamp& timestamp); |
---|
116 | /// Creates a DateTime for the date and time given in |
---|
117 | /// a Timestamp. |
---|
118 | |
---|
119 | DateTime(int year, int month, int day, int hour = 0, int minute = 0, int second = 0, int millisecond = 0, int microsecond = 0); |
---|
120 | /// Creates a DateTime for the given Gregorian date and time. |
---|
121 | /// * year is from 0 to 9999. |
---|
122 | /// * month is from 1 to 12. |
---|
123 | /// * day is from 1 to 31. |
---|
124 | /// * hour is from 0 to 23. |
---|
125 | /// * minute is from 0 to 59. |
---|
126 | /// * second is from 0 to 59. |
---|
127 | /// * millisecond is from 0 to 999. |
---|
128 | /// * microsecond is from 0 to 999. |
---|
129 | |
---|
130 | DateTime(double julianDay); |
---|
131 | /// Creates a DateTime for the given Julian day. |
---|
132 | |
---|
133 | DateTime(Timestamp::UtcTimeVal utcTime, Timestamp::TimeDiff diff); |
---|
134 | /// Creates a DateTime from an UtcTimeVal and a TimeDiff. |
---|
135 | /// |
---|
136 | /// Mainly used internally by DateTime and friends. |
---|
137 | |
---|
138 | DateTime(const DateTime& dateTime); |
---|
139 | /// Copy constructor. Creates the DateTime from another one. |
---|
140 | |
---|
141 | ~DateTime(); |
---|
142 | /// Destroys the DateTime. |
---|
143 | |
---|
144 | DateTime& operator = (const DateTime& dateTime); |
---|
145 | /// Assigns another DateTime. |
---|
146 | |
---|
147 | DateTime& operator = (const Timestamp& timestamp); |
---|
148 | /// Assigns a Timestamp. |
---|
149 | |
---|
150 | DateTime& operator = (double julianDay); |
---|
151 | /// Assigns a Julian day. |
---|
152 | |
---|
153 | DateTime& assign(int year, int month, int day, int hour = 0, int minute = 0, int second = 0, int millisecond = 0, int microseconds = 0); |
---|
154 | /// Assigns a Gregorian date and time. |
---|
155 | /// * year is from 0 to 9999. |
---|
156 | /// * month is from 1 to 12. |
---|
157 | /// * day is from 1 to 31. |
---|
158 | /// * hour is from 0 to 23. |
---|
159 | /// * minute is from 0 to 59. |
---|
160 | /// * second is from 0 to 59. |
---|
161 | /// * millisecond is from 0 to 999. |
---|
162 | /// * microsecond is from 0 to 999. |
---|
163 | |
---|
164 | void swap(DateTime& dateTime); |
---|
165 | /// Swaps the DateTime with another one. |
---|
166 | |
---|
167 | int year() const; |
---|
168 | /// Returns the year. |
---|
169 | |
---|
170 | int month() const; |
---|
171 | /// Returns the month (1 to 12). |
---|
172 | |
---|
173 | int week(int firstDayOfWeek = MONDAY) const; |
---|
174 | /// Returns the week number within the year. |
---|
175 | /// FirstDayOfWeek should be either SUNDAY (0) or MONDAY (1). |
---|
176 | /// The returned week number will be from 0 to 53. Week number 1 is the week |
---|
177 | /// containing January 4. This is in accordance to ISO 8601. |
---|
178 | /// |
---|
179 | /// The following example assumes that firstDayOfWeek is MONDAY. For 2005, which started |
---|
180 | /// on a Saturday, week 1 will be the week starting on Monday, January 3. |
---|
181 | /// January 1 and 2 will fall within week 0 (or the last week of the previous year). |
---|
182 | /// |
---|
183 | /// For 2007, which starts on a Monday, week 1 will be the week startung on Monday, January 1. |
---|
184 | /// There will be no week 0 in 2007. |
---|
185 | |
---|
186 | int day() const; |
---|
187 | /// Returns the day witin the month (1 to 31). |
---|
188 | |
---|
189 | int dayOfWeek() const; |
---|
190 | /// Returns the weekday (0 to 6, where |
---|
191 | /// 0 = Sunday, 1 = Monday, ..., 6 = Saturday). |
---|
192 | |
---|
193 | int dayOfYear() const; |
---|
194 | /// Returns the number of the day in the year. |
---|
195 | /// January 1 is 1, February 1 is 32, etc. |
---|
196 | |
---|
197 | int hour() const; |
---|
198 | /// Returns the hour (0 to 23). |
---|
199 | |
---|
200 | int hourAMPM() const; |
---|
201 | /// Returns the hour (0 to 12). |
---|
202 | |
---|
203 | bool isAM() const; |
---|
204 | /// Returns true if hour < 12; |
---|
205 | |
---|
206 | bool isPM() const; |
---|
207 | /// Returns true if hour >= 12. |
---|
208 | |
---|
209 | int minute() const; |
---|
210 | /// Returns the minute (0 to 59). |
---|
211 | |
---|
212 | int second() const; |
---|
213 | /// Returns the second (0 to 59). |
---|
214 | |
---|
215 | int millisecond() const; |
---|
216 | /// Returns the millisecond (0 to 999) |
---|
217 | |
---|
218 | int microsecond() const; |
---|
219 | /// Returns the microsecond (0 to 999) |
---|
220 | |
---|
221 | double julianDay() const; |
---|
222 | /// Returns the julian day for the date and time. |
---|
223 | |
---|
224 | Timestamp timestamp() const; |
---|
225 | /// Returns the date and time expressed as a Timestamp. |
---|
226 | |
---|
227 | Timestamp::UtcTimeVal utcTime() const; |
---|
228 | /// Returns the date and time expressed in UTC-based |
---|
229 | /// time. UTC base time is midnight, October 15, 1582. |
---|
230 | /// Resolution is 100 nanoseconds. |
---|
231 | |
---|
232 | bool operator == (const DateTime& dateTime) const; |
---|
233 | bool operator != (const DateTime& dateTime) const; |
---|
234 | bool operator < (const DateTime& dateTime) const; |
---|
235 | bool operator <= (const DateTime& dateTime) const; |
---|
236 | bool operator > (const DateTime& dateTime) const; |
---|
237 | bool operator >= (const DateTime& dateTime) const; |
---|
238 | |
---|
239 | DateTime operator + (const Timespan& span) const; |
---|
240 | DateTime operator - (const Timespan& span) const; |
---|
241 | Timespan operator - (const DateTime& dateTime) const; |
---|
242 | DateTime& operator += (const Timespan& span); |
---|
243 | DateTime& operator -= (const Timespan& span); |
---|
244 | |
---|
245 | void makeUTC(int tzd); |
---|
246 | /// Converts a local time into UTC, by applying the given time zone differential. |
---|
247 | |
---|
248 | void makeLocal(int tzd); |
---|
249 | /// Converts a UTC time into a local time, by applying the given time zone differential. |
---|
250 | |
---|
251 | static bool isLeapYear(int year); |
---|
252 | /// Returns true if the given year is a leap year; |
---|
253 | /// false otherwise. |
---|
254 | |
---|
255 | static int daysOfMonth(int year, int month); |
---|
256 | /// Returns the number of days in the given month |
---|
257 | /// and year. Month is from 1 to 12. |
---|
258 | |
---|
259 | static bool isValid(int year, int month, int day, int hour = 0, int minute = 0, int second = 0, int millisecond = 0, int microsecond = 0); |
---|
260 | /// Checks if the given date and time is valid |
---|
261 | /// (all arguments are within a proper range). |
---|
262 | /// |
---|
263 | /// Returns true if all arguments are valid, false otherwise. |
---|
264 | |
---|
265 | protected: |
---|
266 | static double toJulianDay(Timestamp::UtcTimeVal utcTime); |
---|
267 | /// Computes the Julian day for an UTC time. |
---|
268 | |
---|
269 | static double toJulianDay(int year, int month, int day, int hour = 0, int minute = 0, int second = 0, int millisecond = 0, int microsecond = 0); |
---|
270 | /// Computes the Julian day for a gregorian calendar date and time. |
---|
271 | /// See <http://vsg.cape.com/~pbaum/date/jdimp.htm>, section 2.3.1 for the algorithm. |
---|
272 | |
---|
273 | static Timestamp::UtcTimeVal toUtcTime(double julianDay); |
---|
274 | /// Computes the UTC time for a Julian day. |
---|
275 | |
---|
276 | void computeGregorian(double julianDay); |
---|
277 | /// Computes the Gregorian date for the given Julian day. |
---|
278 | /// See <http://vsg.cape.com/~pbaum/date/injdimp.htm>, section 3.3.1 for the algorithm. |
---|
279 | |
---|
280 | void computeDaytime(); |
---|
281 | /// Extracts the daytime (hours, minutes, seconds, etc.) from the stored utcTime. |
---|
282 | |
---|
283 | private: |
---|
284 | void checkLimit(short& lower, short& higher, short limit); |
---|
285 | void normalize(); |
---|
286 | ///utility functions used to correct the overflow in computeGregorian |
---|
287 | |
---|
288 | Timestamp::UtcTimeVal _utcTime; |
---|
289 | short _year; |
---|
290 | short _month; |
---|
291 | short _day; |
---|
292 | short _hour; |
---|
293 | short _minute; |
---|
294 | short _second; |
---|
295 | short _millisecond; |
---|
296 | short _microsecond; |
---|
297 | }; |
---|
298 | |
---|
299 | |
---|
300 | // |
---|
301 | // inlines |
---|
302 | // |
---|
303 | inline Timestamp DateTime::timestamp() const |
---|
304 | { |
---|
305 | return Timestamp::fromUtcTime(_utcTime); |
---|
306 | } |
---|
307 | |
---|
308 | |
---|
309 | inline Timestamp::UtcTimeVal DateTime::utcTime() const |
---|
310 | { |
---|
311 | return _utcTime; |
---|
312 | } |
---|
313 | |
---|
314 | |
---|
315 | inline int DateTime::year() const |
---|
316 | { |
---|
317 | return _year; |
---|
318 | } |
---|
319 | |
---|
320 | |
---|
321 | inline int DateTime::month() const |
---|
322 | { |
---|
323 | return _month; |
---|
324 | } |
---|
325 | |
---|
326 | |
---|
327 | inline int DateTime::day() const |
---|
328 | { |
---|
329 | return _day; |
---|
330 | } |
---|
331 | |
---|
332 | |
---|
333 | inline int DateTime::hour() const |
---|
334 | { |
---|
335 | return _hour; |
---|
336 | } |
---|
337 | |
---|
338 | |
---|
339 | inline int DateTime::hourAMPM() const |
---|
340 | { |
---|
341 | if (_hour < 1) |
---|
342 | return 12; |
---|
343 | else if (_hour > 12) |
---|
344 | return _hour - 12; |
---|
345 | else |
---|
346 | return _hour; |
---|
347 | } |
---|
348 | |
---|
349 | |
---|
350 | inline bool DateTime::isAM() const |
---|
351 | { |
---|
352 | return _hour < 12; |
---|
353 | } |
---|
354 | |
---|
355 | |
---|
356 | inline bool DateTime::isPM() const |
---|
357 | { |
---|
358 | return _hour >= 12; |
---|
359 | } |
---|
360 | |
---|
361 | |
---|
362 | inline int DateTime::minute() const |
---|
363 | { |
---|
364 | return _minute; |
---|
365 | } |
---|
366 | |
---|
367 | |
---|
368 | inline int DateTime::second() const |
---|
369 | { |
---|
370 | return _second; |
---|
371 | } |
---|
372 | |
---|
373 | |
---|
374 | inline int DateTime::millisecond() const |
---|
375 | { |
---|
376 | return _millisecond; |
---|
377 | } |
---|
378 | |
---|
379 | |
---|
380 | inline int DateTime::microsecond() const |
---|
381 | { |
---|
382 | return _microsecond; |
---|
383 | } |
---|
384 | |
---|
385 | |
---|
386 | inline bool DateTime::operator == (const DateTime& dateTime) const |
---|
387 | { |
---|
388 | return _utcTime == dateTime._utcTime; |
---|
389 | } |
---|
390 | |
---|
391 | |
---|
392 | inline bool DateTime::operator != (const DateTime& dateTime) const |
---|
393 | { |
---|
394 | return _utcTime != dateTime._utcTime; |
---|
395 | } |
---|
396 | |
---|
397 | |
---|
398 | inline bool DateTime::operator < (const DateTime& dateTime) const |
---|
399 | { |
---|
400 | return _utcTime < dateTime._utcTime; |
---|
401 | } |
---|
402 | |
---|
403 | |
---|
404 | inline bool DateTime::operator <= (const DateTime& dateTime) const |
---|
405 | { |
---|
406 | return _utcTime <= dateTime._utcTime; |
---|
407 | } |
---|
408 | |
---|
409 | |
---|
410 | inline bool DateTime::operator > (const DateTime& dateTime) const |
---|
411 | { |
---|
412 | return _utcTime > dateTime._utcTime; |
---|
413 | } |
---|
414 | |
---|
415 | |
---|
416 | inline bool DateTime::operator >= (const DateTime& dateTime) const |
---|
417 | { |
---|
418 | return _utcTime >= dateTime._utcTime; |
---|
419 | } |
---|
420 | |
---|
421 | |
---|
422 | inline bool DateTime::isLeapYear(int year) |
---|
423 | { |
---|
424 | return (year % 4) == 0 && ((year % 100) != 0 || (year % 400) == 0); |
---|
425 | } |
---|
426 | |
---|
427 | |
---|
428 | inline void swap(DateTime& d1, DateTime& d2) |
---|
429 | { |
---|
430 | d1.swap(d2); |
---|
431 | } |
---|
432 | |
---|
433 | |
---|
434 | } // namespace Poco |
---|
435 | |
---|
436 | |
---|
437 | #endif // Foundation_DateTime_INCLUDED |
---|