[80] | 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 |
---|