E-MailRelay

gdatetime.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file gdatetime.h
19///
20
21#ifndef G_DATE_TIME_H
22#define G_DATE_TIME_H
23
24#include "gdef.h"
25#include "gexception.h"
26#include <chrono>
27#include <vector>
28#include <string>
29#include <iostream>
30
31 namespace G
32{
33 class DateTime ;
34 class SystemTime ;
35 class TimerTime ;
36 class TimeInterval ;
37 class BrokenDownTime ;
38 class DateTimeTest ;
39}
40
41//| \class G::BrokenDownTime
42/// An encapsulation of 'struct std::tm'.
43///
44 class G::BrokenDownTime
45{
46 public:
47 explicit BrokenDownTime( const struct std::tm & ) ;
48 ///< Constructor.
49
50 BrokenDownTime( int year , int month , int day , int hh , int mm , int ss ) ;
51 ///< Constructor.
52
53 static BrokenDownTime midday( int year , int month , int day ) ;
54 ///< Factory function for midday on the given date.
55
56 static BrokenDownTime local( SystemTime ) ;
57 ///< Factory function for the locale-dependent local time of the
58 ///< given epoch time. See also SystemTime::local().
59
60 static BrokenDownTime utc( SystemTime ) ;
61 ///< Factory function for the utc time of the given epoch time.
62 ///< See also SystemTime::utc().
63
64 void format( std::vector<char> & out , const char * fmt ) const ;
65 ///< Puts the formatted date, including a terminating null character,
66 ///< into the given buffer. Only simple non-locale-dependent format
67 ///< specifiers are allowed, and these allowed specifiers explicitly
68 ///< exclude '%z' and '%Z'.
69
70 std::string str( const char * fmt ) const ;
71 ///< Returns the formatted date, with the same restrictions
72 ///< as format().
73
74 std::string str() const ;
75 ///< Returns str() using a "%F %T" format.
76
77 int year() const ;
78 ///< Returns the four-digit year value.
79
80 int month() const ;
81 ///< Returns the 1..12 month value.
82
83 int day() const ;
84 ///< Returns the 1..31 month-day value.
85
86 int hour() const ;
87 ///< Returns the 0..23 hour value.
88
89 int min() const ;
90 ///< Returns the 0..59 minute value.
91
92 int sec() const ;
93 ///< Returns the 0..59 or 0..60 seconds value.
94
95 int wday() const ;
96 ///< Returns week day where sunday=0 and saturday=6.
97
98 std::time_t epochTimeFromUtc() const ;
99 ///< Searches std::mktime() over the range of all timezones
100 ///< to convert this utc broken-down time into epoch time.
101
102 std::time_t epochTimeFromLocal() const ;
103 ///< Uses std::mktime() to convert this locale-dependent
104 ///< local broken-down time into epoch time.
105
106 bool sameMinute( const BrokenDownTime & other ) const ;
107 ///< Returns true if this and the other broken-down
108 ///< times are the same, at minute resolution with
109 ///< no rounding.
110
111 private:
112 BrokenDownTime() ;
113 std::time_t epochTimeFromUtcImp( bool & , std::time_t & ) const ;
114 std::time_t epochTimeFromUtcImp() const ;
115
116 private:
117 friend class G::DateTimeTest ;
118 struct std::tm m_tm{} ;
119} ;
120
121//| \class G::SystemTime
122/// Represents a unix-epoch time with microsecond resolution.
123///
124 class G::SystemTime
125{
126 public:
127 static SystemTime now() ;
128 ///< Factory function for the current time.
129
130 static SystemTime zero() ;
131 ///< Factory function for the start of the epoch.
132
133 explicit SystemTime( std::time_t , unsigned long us = 0UL ) noexcept ;
134 ///< Constructor. The first parameter should be some
135 ///< large positive number. The second parameter can be
136 ///< more than 10^6.
137
138 bool sameSecond( const SystemTime & other ) const noexcept ;
139 ///< Returns true if this time and the other time are the same,
140 ///< at second resolution.
141
142 BrokenDownTime local() const ;
143 ///< Returns the locale-dependent local broken-down time.
144
145 BrokenDownTime utc() const ;
146 ///< Returns the utc broken-down time.
147
148 unsigned int ms() const ;
149 ///< Returns the millisecond fraction.
150
151 unsigned int us() const ;
152 ///< Returns the microsecond fraction.
153
154 std::time_t s() const noexcept ;
155 ///< Returns the number of seconds since the start of the epoch.
156
157 bool operator<( const SystemTime & ) const ;
158 ///< Comparison operator.
159
160 bool operator<=( const SystemTime & ) const ;
161 ///< Comparison operator.
162
163 bool operator==( const SystemTime & ) const ;
164 ///< Comparison operator.
165
166 bool operator!=( const SystemTime & ) const ;
167 ///< Comparison operator.
168
169 bool operator>( const SystemTime & ) const ;
170 ///< Comparison operator.
171
172 bool operator>=( const SystemTime & ) const ;
173 ///< Comparison operator.
174
175 void operator+=( TimeInterval ) ;
176 ///< Adds the given interval. Throws on overflow.
177
178 SystemTime operator+( TimeInterval ) const ;
179 ///< Returns this time with given interval added.
180 ///< Throws on overflow.
181
182 TimeInterval operator-( const SystemTime & start ) const ;
183 ///< Returns the given start time's interval() compared
184 ///< to this end time. Returns TimeInterval::zero() on
185 ///< underflow or TimeInterval::limit() on overflow of
186 ///< TimeInterval::s_type.
187
188 TimeInterval interval( const SystemTime & end ) const ;
189 ///< Returns the interval between this time and the given
190 ///< end time. Returns TimeInterval::zero() on underflow or
191 ///< TimeInterval::limit() on overflow of TimeInterval::s_type.
192
193 void streamOut( std::ostream & ) const ;
194 ///< Streams out the time comprised of the s() value, a decimal
195 ///< point, and then the six-digit us() value.
196
197 private:
198 friend class G::DateTimeTest ;
199 using duration_type = std::chrono::system_clock::duration ;
200 using time_point_type = std::chrono::time_point<std::chrono::system_clock> ;
201 explicit SystemTime( time_point_type ) ;
202 SystemTime & add( unsigned long us ) ;
203
204 private:
205 time_point_type m_tp ;
206} ;
207
208//| \class G::TimerTime
209/// A monotonically increasing subsecond-resolution timestamp, notionally
210/// unrelated to time_t.
211///
212 class G::TimerTime
213{
214 public:
215 static TimerTime now() ;
216 ///< Factory function for the current steady-clock time.
217
218 static TimerTime zero() ;
219 ///< Factory function for the start of the epoch.
220
221 bool isZero() const noexcept ;
222 ///< Returns true if zero().
223
224 bool sameSecond( const TimerTime & other ) const ;
225 ///< Returns true if this time and the other time are the same,
226 ///< at second resolution.
227
228 bool operator<( const TimerTime & ) const ;
229 ///< Comparison operator.
230
231 bool operator<=( const TimerTime & ) const ;
232 ///< Comparison operator.
233
234 bool operator==( const TimerTime & ) const ;
235 ///< Comparison operator.
236
237 bool operator!=( const TimerTime & ) const ;
238 ///< Comparison operator.
239
240 bool operator>( const TimerTime & ) const ;
241 ///< Comparison operator.
242
243 bool operator>=( const TimerTime & ) const ;
244 ///< Comparison operator.
245
246 TimerTime operator+( const TimeInterval & ) const ;
247 ///< Returns this time with given interval added.
248
249 void operator+=( TimeInterval ) ;
250 ///< Adds an interval.
251
252 TimeInterval operator-( const TimerTime & start ) const ;
253 ///< Returns the given start time's interval() compared
254 ///< to this end time. Returns TimeInterval::zero() on
255 ///< underflow or TimeInterval::limit() if the
256 ///< TimeInterval::s_type value overflows.
257
258 TimeInterval interval( const TimerTime & end ) const ;
259 ///< Returns the interval between this time and the given
260 ///< end time. Returns TimeInterval::zero() on underflow or
261 ///< TimeInterval::limit() if the TimeInterval::s_type
262 ///< value overflows.
263
264 private:
265 friend class G::DateTimeTest ;
266 using duration_type = std::chrono::steady_clock::duration ;
267 using time_point_type = std::chrono::time_point<std::chrono::steady_clock> ;
268 TimerTime( time_point_type , bool ) ;
269 static TimerTime test( int , int ) ;
270 unsigned long test_s() const ;
271 unsigned long test_us() const ;
272
273 private:
274 bool m_is_zero ;
275 time_point_type m_tp ;
276} ;
277
278 inline
279 bool G::TimerTime::isZero() const noexcept
280{
281 return m_is_zero ;
282}
283
284//| \class G::TimeInterval
285/// An interval between two G::SystemTime values or two G::TimerTime
286/// values.
287///
288 class G::TimeInterval
289{
290 public:
291 using s_type = unsigned int ;
292 using us_type = unsigned int ;
293
294 explicit TimeInterval( unsigned int s , unsigned int us = 0U ) ;
295 ///< Constructor.
296
297 TimeInterval( const SystemTime & start , const SystemTime & end ) ;
298 ///< Constructor. Constructs a zero interval if 'end' is before
299 ///< 'start', and the limit() interval if 'end' is too far
300 ///< ahead of 'start' for the underlying type.
301
302 TimeInterval( const TimerTime & start , const TimerTime & end ) ;
303 ///< Constructor. Overload for TimerTime.
304
305 static TimeInterval zero() ;
306 ///< Factory function for the zero interval.
307
308 static TimeInterval limit() ;
309 ///< Factory function for the maximum valid interval.
310
311 unsigned int s() const ;
312 ///< Returns the number of seconds.
313
314 unsigned int us() const ;
315 ///< Returns the fractional microseconds part.
316
317 void streamOut( std::ostream & ) const ;
318 ///< Streams out the interval.
319
320 bool operator<( const TimeInterval & ) const ;
321 ///< Comparison operator.
322
323 bool operator<=( const TimeInterval & ) const ;
324 ///< Comparison operator.
325
326 bool operator==( const TimeInterval & ) const ;
327 ///< Comparison operator.
328
329 bool operator!=( const TimeInterval & ) const ;
330 ///< Comparison operator.
331
332 bool operator>( const TimeInterval & ) const ;
333 ///< Comparison operator.
334
335 bool operator>=( const TimeInterval & ) const ;
336 ///< Comparison operator.
337
338 TimeInterval operator+( const TimeInterval & ) const ;
339 ///< Returns the combined interval. Throws on overflow.
340
341 TimeInterval operator-( const TimeInterval & ) const ;
342 ///< Returns the interval difference. Throws on underflow.
343
344 void operator+=( TimeInterval ) ;
345 ///< Adds the given interval. Throws on overflow.
346
347 void operator-=( TimeInterval ) ;
348 ///< Subtracts the given interval. Throws on underflow.
349
350 private:
351 void normalise() ;
352 static void increase( unsigned int & s , unsigned int ds = 1U ) ;
353 static void decrease( unsigned int & s , unsigned int ds = 1U ) ;
354
355 private:
356 unsigned int m_s ;
357 unsigned int m_us ;
358} ;
359
360 namespace G
361{
362 std::ostream & operator<<( std::ostream & , const SystemTime & ) ;
363 std::ostream & operator<<( std::ostream & , const TimeInterval & ) ;
364}
365
366//| \class G::DateTime
367/// A static class that knows about timezone offsets.
368///
369 class G::DateTime
370{
371 public:
372 G_EXCEPTION_CLASS( Error , "date/time error" ) ;
373 using Offset = std::pair<bool,unsigned int> ;
374
375 static Offset offset( SystemTime ) ;
376 ///< Returns the offset in seconds between UTC and localtime
377 ///< as at the given system time. The returned pair has 'first'
378 ///< set to true if localtime is ahead of (ie. east of) UTC.
379
380 static std::string offsetString( Offset offset ) ;
381 ///< Converts the given utc/localtime offset into a five-character
382 ///< "+/-hhmm" string.
383 ///< See also RFC-2822.
384
385 static std::string offsetString( int hh ) ;
386 ///< Overload for a signed integer timezone.
387
388 public:
389 DateTime() = delete ;
390} ;
391
392#endif
G::BrokenDownTime
An encapsulation of 'struct std::tm'.
Definition: gdatetime.h:45
G::BrokenDownTime::wday
int wday() const
Returns week day where sunday=0 and saturday=6.
Definition: gdatetime.cpp:232
G::BrokenDownTime::day
int day() const
Returns the 1..31 month-day value.
Definition: gdatetime.cpp:227
G::BrokenDownTime::epochTimeFromLocal
std::time_t epochTimeFromLocal() const
Uses std::mktime() to convert this locale-dependent local broken-down time into epoch time.
Definition: gdatetime.cpp:74
G::BrokenDownTime::sameMinute
bool sameMinute(const BrokenDownTime &other) const
Returns true if this and the other broken-down times are the same, at minute resolution with no round...
Definition: gdatetime.cpp:237
G::BrokenDownTime::str
std::string str() const
Returns str() using a "%F %T" format.
Definition: gdatetime.cpp:185
G::BrokenDownTime::sec
int sec() const
Returns the 0..59 or 0..60 seconds value.
Definition: gdatetime.cpp:212
G::BrokenDownTime::utc
static BrokenDownTime utc(SystemTime)
Factory function for the utc time of the given epoch time.
Definition: gdatetime.cpp:145
G::BrokenDownTime::midday
static BrokenDownTime midday(int year, int month, int day)
Factory function for midday on the given date.
Definition: gdatetime.cpp:168
G::BrokenDownTime::month
int month() const
Returns the 1..12 month value.
Definition: gdatetime.cpp:222
G::BrokenDownTime::format
void format(std::vector< char > &out, const char *fmt) const
Puts the formatted date, including a terminating null character, into the given buffer.
Definition: gdatetime.cpp:173
G::BrokenDownTime::local
static BrokenDownTime local(SystemTime)
Factory function for the locale-dependent local time of the given epoch time.
Definition: gdatetime.cpp:136
G::BrokenDownTime::hour
int hour() const
Returns the 0..23 hour value.
Definition: gdatetime.cpp:202
G::BrokenDownTime::year
int year() const
Returns the four-digit year value.
Definition: gdatetime.cpp:217
G::BrokenDownTime::epochTimeFromUtc
std::time_t epochTimeFromUtc() const
Searches std::mktime() over the range of all timezones to convert this utc broken-down time into epoc...
Definition: gdatetime.cpp:84
G::BrokenDownTime::min
int min() const
Returns the 0..59 minute value.
Definition: gdatetime.cpp:207
G::DateTime
A static class that knows about timezone offsets.
Definition: gdatetime.h:370
G::DateTime::offset
static Offset offset(SystemTime)
Returns the offset in seconds between UTC and localtime as at the given system time.
Definition: gdatetime.cpp:651
G::DateTime::offsetString
static std::string offsetString(Offset offset)
Converts the given utc/localtime offset into a five-character "+/-hhmm" string.
Definition: gdatetime.cpp:669
G::SystemTime
Represents a unix-epoch time with microsecond resolution.
Definition: gdatetime.h:125
G::SystemTime::operator-
TimeInterval operator-(const SystemTime &start) const
Returns the given start time's interval() compared to this end time.
Definition: gdatetime.cpp:265
G::SystemTime::now
static SystemTime now()
Factory function for the current time.
Definition: gdatetime.cpp:260
G::SystemTime::s
std::time_t s() const noexcept
Returns the number of seconds since the start of the epoch.
Definition: gdatetime.cpp:308
G::SystemTime::operator+
SystemTime operator+(TimeInterval) const
Returns this time with given interval added.
Definition: gdatetime.cpp:352
G::SystemTime::ms
unsigned int ms() const
Returns the millisecond fraction.
Definition: gdatetime.cpp:296
G::SystemTime::us
unsigned int us() const
Returns the microsecond fraction.
Definition: gdatetime.cpp:302
G::SystemTime::operator!=
bool operator!=(const SystemTime &) const
Comparison operator.
Definition: gdatetime.cpp:337
G::SystemTime::local
BrokenDownTime local() const
Returns the locale-dependent local broken-down time.
Definition: gdatetime.cpp:286
G::SystemTime::operator>
bool operator>(const SystemTime &) const
Comparison operator.
Definition: gdatetime.cpp:342
G::SystemTime::streamOut
void streamOut(std::ostream &) const
Streams out the time comprised of the s() value, a decimal point, and then the six-digit us() value.
Definition: gdatetime.cpp:366
G::SystemTime::interval
TimeInterval interval(const SystemTime &end) const
Returns the interval between this time and the given end time.
Definition: gdatetime.cpp:270
G::SystemTime::sameSecond
bool sameSecond(const SystemTime &other) const noexcept
Returns true if this time and the other time are the same, at second resolution.
Definition: gdatetime.cpp:281
G::SystemTime::operator<=
bool operator<=(const SystemTime &) const
Comparison operator.
Definition: gdatetime.cpp:327
G::SystemTime::operator>=
bool operator>=(const SystemTime &) const
Comparison operator.
Definition: gdatetime.cpp:347
G::SystemTime::zero
static SystemTime zero()
Factory function for the start of the epoch.
Definition: gdatetime.cpp:315
G::SystemTime::SystemTime
SystemTime(std::time_t, unsigned long us=0UL) noexcept
Constructor.
Definition: gdatetime.cpp:254
G::SystemTime::utc
BrokenDownTime utc() const
Returns the utc broken-down time.
Definition: gdatetime.cpp:291
G::SystemTime::operator+=
void operator+=(TimeInterval)
Adds the given interval. Throws on overflow.
Definition: gdatetime.cpp:359
G::SystemTime::operator<
bool operator<(const SystemTime &) const
Comparison operator.
Definition: gdatetime.cpp:322
G::SystemTime::operator==
bool operator==(const SystemTime &) const
Comparison operator.
Definition: gdatetime.cpp:332
G::TimeInterval
An interval between two G::SystemTime values or two G::TimerTime values.
Definition: gdatetime.h:289
G::TimeInterval::TimeInterval
TimeInterval(unsigned int s, unsigned int us=0U)
Constructor.
Definition: gdatetime.cpp:485
G::TimeInterval::operator+
TimeInterval operator+(const TimeInterval &) const
Returns the combined interval. Throws on overflow.
Definition: gdatetime.cpp:578
G::TimeInterval::zero
static TimeInterval zero()
Factory function for the zero interval.
Definition: gdatetime.cpp:533
G::TimeInterval::operator-=
void operator-=(TimeInterval)
Subtracts the given interval. Throws on underflow.
Definition: gdatetime.cpp:620
G::TimeInterval::operator==
bool operator==(const TimeInterval &) const
Comparison operator.
Definition: gdatetime.cpp:548
G::TimeInterval::limit
static TimeInterval limit()
Factory function for the maximum valid interval.
Definition: gdatetime.cpp:527
G::TimeInterval::s
unsigned int s() const
Returns the number of seconds.
Definition: gdatetime.cpp:538
G::TimeInterval::us
unsigned int us() const
Returns the fractional microseconds part.
Definition: gdatetime.cpp:543
G::TimeInterval::operator+=
void operator+=(TimeInterval)
Adds the given interval. Throws on overflow.
Definition: gdatetime.cpp:601
G::TimeInterval::operator>
bool operator>(const TimeInterval &) const
Comparison operator.
Definition: gdatetime.cpp:568
G::TimeInterval::operator-
TimeInterval operator-(const TimeInterval &) const
Returns the interval difference. Throws on underflow.
Definition: gdatetime.cpp:585
G::TimeInterval::operator<
bool operator<(const TimeInterval &) const
Comparison operator.
Definition: gdatetime.cpp:558
G::TimeInterval::operator!=
bool operator!=(const TimeInterval &) const
Comparison operator.
Definition: gdatetime.cpp:553
G::TimeInterval::streamOut
void streamOut(std::ostream &) const
Streams out the interval.
Definition: gdatetime.cpp:632
G::TimeInterval::operator>=
bool operator>=(const TimeInterval &) const
Comparison operator.
Definition: gdatetime.cpp:573
G::TimeInterval::operator<=
bool operator<=(const TimeInterval &) const
Comparison operator.
Definition: gdatetime.cpp:563
G::TimerTime
A monotonically increasing subsecond-resolution timestamp, notionally unrelated to time_t.
Definition: gdatetime.h:213
G::TimerTime::isZero
bool isZero() const noexcept
Returns true if zero().
Definition: gdatetime.h:279
G::TimerTime::now
static TimerTime now()
Factory function for the current steady-clock time.
Definition: gdatetime.cpp:385
G::TimerTime::operator+
TimerTime operator+(const TimeInterval &) const
Returns this time with given interval added.
Definition: gdatetime.cpp:419
G::TimerTime::operator>
bool operator>(const TimerTime &) const
Comparison operator.
Definition: gdatetime.cpp:473
G::TimerTime::interval
TimeInterval interval(const TimerTime &end) const
Returns the interval between this time and the given end time.
Definition: gdatetime.cpp:440
G::TimerTime::operator==
bool operator==(const TimerTime &) const
Comparison operator.
Definition: gdatetime.cpp:463
G::TimerTime::operator!=
bool operator!=(const TimerTime &) const
Comparison operator.
Definition: gdatetime.cpp:468
G::TimerTime::operator-
TimeInterval operator-(const TimerTime &start) const
Returns the given start time's interval() compared to this end time.
Definition: gdatetime.cpp:435
G::TimerTime::sameSecond
bool sameSecond(const TimerTime &other) const
Returns true if this time and the other time are the same, at second resolution.
Definition: gdatetime.cpp:445
G::TimerTime::operator+=
void operator+=(TimeInterval)
Adds an interval.
Definition: gdatetime.cpp:427
G::TimerTime::zero
static TimerTime zero()
Factory function for the start of the epoch.
Definition: gdatetime.cpp:390
G::TimerTime::operator<
bool operator<(const TimerTime &) const
Comparison operator.
Definition: gdatetime.cpp:453
G::TimerTime::operator<=
bool operator<=(const TimerTime &) const
Comparison operator.
Definition: gdatetime.cpp:458
G::TimerTime::operator>=
bool operator>=(const TimerTime &) const
Comparison operator.
Definition: gdatetime.cpp:478
gexception.h
G
Low-level classes.
Definition: galign.h:28