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
25namespace Poco {
26
27
28class 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{
54public:
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 59.
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 59.
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 59.
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 59.
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
238protected:
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
253private:
254 DateTime _dateTime;
255 int _tzd;
256
257 friend class DateTimeFormatter;
258 friend class DateTimeParser;
259};
260
261
262//
263// inlines
264//
265inline int LocalDateTime::year() const
266{
267 return _dateTime.year();
268}
269
270
271inline int LocalDateTime::month() const
272{
273 return _dateTime.month();
274}
275
276
277inline int LocalDateTime::week(int firstDayOfWeek) const
278{
279 return _dateTime.week(firstDayOfWeek);
280}
281
282
283inline int LocalDateTime::day() const
284{
285 return _dateTime.day();
286}
287
288
289inline int LocalDateTime::dayOfWeek() const
290{
291 return _dateTime.dayOfWeek();
292}
293
294
295inline int LocalDateTime::dayOfYear() const
296{
297 return _dateTime.dayOfYear();
298}
299
300
301inline int LocalDateTime::hour() const
302{
303 return _dateTime.hour();
304}
305
306
307inline int LocalDateTime::hourAMPM() const
308{
309 return _dateTime.hourAMPM();
310}
311
312
313inline bool LocalDateTime::isAM() const
314{
315 return _dateTime.isAM();
316}
317
318
319inline bool LocalDateTime::isPM() const
320{
321 return _dateTime.isPM();
322}
323
324
325inline int LocalDateTime::minute() const
326{
327 return _dateTime.minute();
328}
329
330
331inline int LocalDateTime::second() const
332{
333 return _dateTime.second();
334}
335
336
337inline int LocalDateTime::millisecond() const
338{
339 return _dateTime.millisecond();
340}
341
342
343inline int LocalDateTime::microsecond() const
344{
345 return _dateTime.microsecond();
346}
347
348
349inline double LocalDateTime::julianDay() const
350{
351 return _dateTime.julianDay();
352}
353
354
355inline int LocalDateTime::tzd() const
356{
357 return _tzd;
358}
359
360
361inline Timestamp LocalDateTime::timestamp() const
362{
363 return Timestamp::fromUtcTime(_dateTime.utcTime());
364}
365
366
367inline Timestamp::UtcTimeVal LocalDateTime::utcTime() const
368{
369 return _dateTime.utcTime() - ((Timestamp::TimeDiff) _tzd)*10000000;
370}
371
372
373inline void LocalDateTime::adjustForTzd()
374{
375 _dateTime += Timespan(((Timestamp::TimeDiff) _tzd)*Timespan::SECONDS);
376}
377
378
379inline 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