1 //
2 // LocalDateTime.h
3 //
4 // Library: Foundation
5 // Package: DateTime
6 // Module: LocalDateTime
7 //
8 // Definition of the LocalDateTime class.
9 //
10 // Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11 // and Contributors.
12 //
13 // SPDX-License-Identifier: BSL-1.0
14 //
15
16
17 #ifndef Foundation_LocalDateTime_INCLUDED
18 #define Foundation_LocalDateTime_INCLUDED
19
20
21 #include "Poco/Foundation.h"
22 #include "Poco/DateTime.h"
23
24
25 namespace Poco {
26
27
28 class Foundation_API LocalDateTime
29 /// This class represents an instant in local time
30 /// (as opposed to UTC), expressed in years, months, days,
31 /// hours, minutes, seconds and milliseconds based on the
32 /// Gregorian calendar.
33 ///
34 /// In addition to the date and time, the class also
35 /// maintains a time zone differential, which denotes
36 /// the difference in seconds from UTC to local time,
37 /// i.e. UTC = local time - time zone differential.
38 ///
39 /// Although LocalDateTime supports relational and arithmetic
40 /// operators, all date/time comparisons and date/time arithmetic
41 /// should be done in UTC, using the DateTime or Timestamp
42 /// class for better performance. The relational operators
43 /// normalize the dates/times involved to UTC before carrying out
44 /// the comparison.
45 ///
46 /// The time zone differential is based on the input date and
47 /// time and current time zone. A number of constructors accept
48 /// an explicit time zone differential parameter. These should
49 /// not be used since daylight savings time processing is impossible
50 /// since the time zone is unknown. Each of the constructors
51 /// accepting a tzd parameter have been marked as deprecated and
52 /// may be removed in a future revision.
53 {
54 public:
55 LocalDateTime();
56 /// Creates a LocalDateTime with the current date/time
57 /// for the current time zone.
58
59 LocalDateTime(int year, int month, int day, int hour = 0, int minute = 0, int second = 0, int millisecond = 0, int microsecond = 0);
60 /// Creates a LocalDateTime for the given Gregorian local date and time.
61 /// * year is from 0 to 9999.
62 /// * month is from 1 to 12.
63 /// * day is from 1 to 31.
64 /// * hour is from 0 to 23.
65 /// * minute is from 0 to 59.
66 /// * second is from 0 to 60 (allowing leap seconds).
67 /// * millisecond is from 0 to 999.
68 /// * microsecond is from 0 to 999.
69
70 //@ deprecated
71 LocalDateTime(int tzd, int year, int month, int day, int hour, int minute, int second, int millisecond, int microsecond);
72 /// Creates a LocalDateTime for the given Gregorian date and time in the
73 /// time zone denoted by the time zone differential in tzd.
74 /// * tzd is in seconds.
75 /// * year is from 0 to 9999.
76 /// * month is from 1 to 12.
77 /// * day is from 1 to 31.
78 /// * hour is from 0 to 23.
79 /// * minute is from 0 to 59.
80 /// * second is from 0 to 60 (allowing leap seconds).
81 /// * millisecond is from 0 to 999.
82 /// * microsecond is from 0 to 999.
83
84 LocalDateTime(const DateTime& dateTime);
85 /// Creates a LocalDateTime from the UTC time given in dateTime,
86 /// using the time zone differential of the current time zone.
87
88 //@ deprecated
89 LocalDateTime(int tzd, const DateTime& dateTime);
90 /// Creates a LocalDateTime from the UTC time given in dateTime,
91 /// using the given time zone differential. Adjusts dateTime
92 /// for the given time zone differential.
93
94 //@ deprecated
95 LocalDateTime(int tzd, const DateTime& dateTime, bool adjust);
96 /// Creates a LocalDateTime from the UTC time given in dateTime,
97 /// using the given time zone differential. If adjust is true,
98 /// adjusts dateTime for the given time zone differential.
99
100 LocalDateTime(double julianDay);
101 /// Creates a LocalDateTime for the given Julian day in the local time zone.
102
103 //@ deprecated
104 LocalDateTime(int tzd, double julianDay);
105 /// Creates a LocalDateTime for the given Julian day in the time zone
106 /// denoted by the time zone differential in tzd.
107
108 LocalDateTime(const LocalDateTime& dateTime);
109 /// Copy constructor. Creates the LocalDateTime from another one.
110
111 ~LocalDateTime();
112 /// Destroys the LocalDateTime.
113
114 LocalDateTime& operator = (const LocalDateTime& dateTime);
115 /// Assigns another LocalDateTime.
116
117 LocalDateTime& operator = (const Timestamp& timestamp);
118 /// Assigns a timestamp
119
120 LocalDateTime& operator = (double julianDay);
121 /// Assigns a Julian day in the local time zone.
122
123 LocalDateTime& assign(int year, int month, int day, int hour = 0, int minute = 0, int second = 0, int millisecond = 0, int microseconds = 0);
124 /// Assigns a Gregorian local date and time.
125 /// * year is from 0 to 9999.
126 /// * month is from 1 to 12.
127 /// * day is from 1 to 31.
128 /// * hour is from 0 to 23.
129 /// * minute is from 0 to 59.
130 /// * second is from 0 to 60 (allowing leap seconds).
131 /// * millisecond is from 0 to 999.
132 /// * microsecond is from 0 to 999.
133
134 //@ deprecated
135 LocalDateTime& assign(int tzd, int year, int month, int day, int hour, int minute, int second, int millisecond, int microseconds);
136 /// Assigns a Gregorian local date and time in the time zone denoted by
137 /// the time zone differential in tzd.
138 /// * tzd is in seconds.
139 /// * year is from 0 to 9999.
140 /// * month is from 1 to 12.
141 /// * day is from 1 to 31.
142 /// * hour is from 0 to 23.
143 /// * minute is from 0 to 59.
144 /// * second is from 0 to 60 (allowing leap seconds).
145 /// * millisecond is from 0 to 999.
146 /// * microsecond is from 0 to 999.
147
148 //@ deprecated
149 LocalDateTime& assign(int tzd, double julianDay);
150 /// Assigns a Julian day in the time zone denoted by the
151 /// time zone differential in tzd.
152
153 void swap(LocalDateTime& dateTime);
154 /// Swaps the LocalDateTime with another one.
155
156 int year() const;
157 /// Returns the year.
158
159 int month() const;
160 /// Returns the month (1 to 12).
161
162 int week(int firstDayOfWeek = DateTime::MONDAY) const;
163 /// Returns the week number within the year.
164 /// FirstDayOfWeek should be either SUNDAY (0) or MONDAY (1).
165 /// The returned week number will be from 0 to 53. Week number 1 is the week
166 /// containing January 4. This is in accordance to ISO 8601.
167 ///
168 /// The following example assumes that firstDayOfWeek is MONDAY. For 2005, which started
169 /// on a Saturday, week 1 will be the week starting on Monday, January 3.
170 /// January 1 and 2 will fall within week 0 (or the last week of the previous year).
171 ///
172 /// For 2007, which starts on a Monday, week 1 will be the week starting on Monday, January 1.
173 /// There will be no week 0 in 2007.
174
175 int day() const;
176 /// Returns the day within the month (1 to 31).
177
178 int dayOfWeek() const;
179 /// Returns the weekday (0 to 6, where
180 /// 0 = Sunday, 1 = Monday, ..., 6 = Saturday).
181
182 int dayOfYear() const;
183 /// Returns the number of the day in the year.
184 /// January 1 is 1, February 1 is 32, etc.
185
186 int hour() const;
187 /// Returns the hour (0 to 23).
188
189 int hourAMPM() const;
190 /// Returns the hour (0 to 12).
191
192 bool isAM() const;
193 /// Returns true if hour < 12;
194
195 bool isPM() const;
196 /// Returns true if hour >= 12.
197
198 int minute() const;
199 /// Returns the minute (0 to 59).
200
201 int second() const;
202 /// Returns the second (0 to 59).
203
204 int millisecond() const;
205 /// Returns the millisecond (0 to 999)
206
207 int microsecond() const;
208 /// Returns the microsecond (0 to 999)
209
210 double julianDay() const;
211 /// Returns the Julian day for the date.
212
213 int tzd() const;
214 /// Returns the time zone differential.
215
216 DateTime utc() const;
217 /// Returns the UTC equivalent for the local date and time.
218
219 Timestamp timestamp() const;
220 /// Returns the date and time expressed as a Timestamp.
221
222 Timestamp::UtcTimeVal utcTime() const;
223 /// Returns the UTC equivalent for the local date and time.
224
225 bool operator == (const LocalDateTime& dateTime) const;
226 bool operator != (const LocalDateTime& dateTime) const;
227 bool operator < (const LocalDateTime& dateTime) const;
228 bool operator <= (const LocalDateTime& dateTime) const;
229 bool operator > (const LocalDateTime& dateTime) const;
230 bool operator >= (const LocalDateTime& dateTime) const;
231
232 LocalDateTime operator + (const Timespan& span) const;
233 LocalDateTime operator - (const Timespan& span) const;
234 Timespan operator - (const LocalDateTime& dateTime) const;
235 LocalDateTime& operator += (const Timespan& span);
236 LocalDateTime& operator -= (const Timespan& span);
237
238 protected:
239 LocalDateTime(Timestamp::UtcTimeVal utcTime, Timestamp::TimeDiff diff, int tzd);
240
241 void determineTzd(bool adjust = false);
242 /// Recalculate the tzd based on the _dateTime member based
243 /// on the current timezone using the Standard C runtime functions.
244 /// If adjust is true, then adjustForTzd() is called after the
245 /// differential is calculated.
246
247 void adjustForTzd();
248 /// Adjust the _dateTime member based on the _tzd member.
249
250 std::time_t dstOffset(int& dstOffset) const;
251 /// Determine the DST offset for the current date/time.
252
253 private:
254 DateTime _dateTime;
255 int _tzd;
256
257 friend class DateTimeFormatter;
258 friend class DateTimeParser;
259 };
260
261
262 //
263 // inlines
264 //
year()265 inline int LocalDateTime::year() const
266 {
267 return _dateTime.year();
268 }
269
270
month()271 inline int LocalDateTime::month() const
272 {
273 return _dateTime.month();
274 }
275
276
week(int firstDayOfWeek)277 inline int LocalDateTime::week(int firstDayOfWeek) const
278 {
279 return _dateTime.week(firstDayOfWeek);
280 }
281
282
day()283 inline int LocalDateTime::day() const
284 {
285 return _dateTime.day();
286 }
287
288
dayOfWeek()289 inline int LocalDateTime::dayOfWeek() const
290 {
291 return _dateTime.dayOfWeek();
292 }
293
294
dayOfYear()295 inline int LocalDateTime::dayOfYear() const
296 {
297 return _dateTime.dayOfYear();
298 }
299
300
hour()301 inline int LocalDateTime::hour() const
302 {
303 return _dateTime.hour();
304 }
305
306
hourAMPM()307 inline int LocalDateTime::hourAMPM() const
308 {
309 return _dateTime.hourAMPM();
310 }
311
312
isAM()313 inline bool LocalDateTime::isAM() const
314 {
315 return _dateTime.isAM();
316 }
317
318
isPM()319 inline bool LocalDateTime::isPM() const
320 {
321 return _dateTime.isPM();
322 }
323
324
minute()325 inline int LocalDateTime::minute() const
326 {
327 return _dateTime.minute();
328 }
329
330
second()331 inline int LocalDateTime::second() const
332 {
333 return _dateTime.second();
334 }
335
336
millisecond()337 inline int LocalDateTime::millisecond() const
338 {
339 return _dateTime.millisecond();
340 }
341
342
microsecond()343 inline int LocalDateTime::microsecond() const
344 {
345 return _dateTime.microsecond();
346 }
347
348
julianDay()349 inline double LocalDateTime::julianDay() const
350 {
351 return _dateTime.julianDay();
352 }
353
354
tzd()355 inline int LocalDateTime::tzd() const
356 {
357 return _tzd;
358 }
359
360
timestamp()361 inline Timestamp LocalDateTime::timestamp() const
362 {
363 return Timestamp::fromUtcTime(_dateTime.utcTime());
364 }
365
366
utcTime()367 inline Timestamp::UtcTimeVal LocalDateTime::utcTime() const
368 {
369 return _dateTime.utcTime() - ((Timestamp::TimeDiff) _tzd)*10000000;
370 }
371
372
adjustForTzd()373 inline void LocalDateTime::adjustForTzd()
374 {
375 _dateTime += Timespan(((Timestamp::TimeDiff) _tzd)*Timespan::SECONDS);
376 }
377
378
swap(LocalDateTime & d1,LocalDateTime & d2)379 inline void swap(LocalDateTime& d1, LocalDateTime& d2)
380 {
381 d1.swap(d2);
382 }
383
384
385 } // namespace Poco
386
387
388 #endif // Foundation_LocalDateTime_INCLUDED
389