E-MailRelay
gdatetime.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2023 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
31namespace 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///
45{
46public:
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 null() ;
54 ///< Factory function for an unusable object with bogus
55 ///< component values.
56
57 static BrokenDownTime midday( int year , int month , int day ) ;
58 ///< Factory function for midday on the given date.
59
60 static BrokenDownTime midnight( int year , int month , int day ) ;
61 ///< Factory function for midnight starting the given date.
62
64 ///< Factory function for the locale-dependent local broken-down
65 ///< time of the given epoch time. See also SystemTime::local().
66
67 static BrokenDownTime utc( SystemTime ) ;
68 ///< Factory function for the utc broken-down time of the given
69 ///< epoch time. See also SystemTime::utc().
70
71 bool format( char * out , std::size_t out_size , const char * fmt ) const ;
72 ///< Puts the formatted date, including a terminating null character,
73 ///< into the given output buffer. Returns false if the output buffer
74 ///< is too small. Only simple non-locale-dependent format specifiers
75 ///< are allowed, and these allowed specifiers explicitly exclude
76 ///< '%z' and '%Z'.
77
78 void format( std::vector<char> & out , const char * fmt ) const ;
79 ///< Overload for an output vector. Throws if the vector is
80 ///< too small for the result (with its null terminator).
81
82 std::string str( const char * fmt ) const ;
83 ///< Returns the formatted date, with the same restrictions
84 ///< as format().
85
86 std::string str() const ;
87 ///< Returns str() using a "%F %T" format.
88
89 int year() const ;
90 ///< Returns the four-digit year value.
91
92 int month() const ;
93 ///< Returns the 1..12 month value.
94
95 int day() const ;
96 ///< Returns the 1..31 month-day value.
97
98 int hour() const ;
99 ///< Returns the 0..23 hour value.
100
101 int min() const ;
102 ///< Returns the 0..59 minute value.
103
104 int sec() const ;
105 ///< Returns the 0..59 or 0..60 seconds value.
106
107 int wday() const ;
108 ///< Returns week day where sunday=0 and saturday=6.
109
110 std::time_t epochTimeFromUtc() const ;
111 ///< Converts this utc broken-down time into epoch time.
112
113 std::time_t epochTimeFromLocal() const ;
114 ///< Uses std::mktime() to convert this locale-dependent
115 ///< local broken-down time into epoch time.
116
117 bool sameMinute( const BrokenDownTime & other ) const noexcept ;
118 ///< Returns true if this and the other broken-down
119 ///< times are the same, at minute resolution with
120 ///< no rounding.
121
122private:
124
125private:
126 friend class G::DateTimeTest ;
127 struct std::tm m_tm{} ;
128} ;
129
130//| \class G::SystemTime
131/// Represents a unix-epoch time with microsecond resolution.
132///
134{
135public:
136 static SystemTime now() ;
137 ///< Factory function for the current time.
138
139 static SystemTime zero() ;
140 ///< Factory function for the start of the epoch.
141
142 explicit SystemTime( std::time_t , unsigned long us = 0UL ) noexcept ;
143 ///< Constructor. The first parameter should be some
144 ///< large positive number. The second parameter can be
145 ///< more than 10^6.
146
147 bool isZero() const ;
148 ///< Returns true if zero().
149
150 bool sameSecond( const SystemTime & other ) const noexcept ;
151 ///< Returns true if this time and the other time are the same,
152 ///< at second resolution.
153
154 BrokenDownTime local() const ;
155 ///< Returns the locale-dependent local broken-down time.
156
157 BrokenDownTime utc() const ;
158 ///< Returns the utc broken-down time.
159
160 unsigned int ms() const ;
161 ///< Returns the millisecond fraction.
162
163 unsigned int us() const ;
164 ///< Returns the microsecond fraction.
165
166 std::time_t s() const noexcept ;
167 ///< Returns the number of seconds since the start of the epoch.
168
169 bool operator<( const SystemTime & ) const ;
170 ///< Comparison operator.
171
172 bool operator<=( const SystemTime & ) const ;
173 ///< Comparison operator.
174
175 bool operator==( const SystemTime & ) const ;
176 ///< Comparison operator.
177
178 bool operator!=( const SystemTime & ) const ;
179 ///< Comparison operator.
180
181 bool operator>( const SystemTime & ) const ;
182 ///< Comparison operator.
183
184 bool operator>=( const SystemTime & ) const ;
185 ///< Comparison operator.
186
187 void operator+=( TimeInterval ) ;
188 ///< Adds the given interval. Throws on overflow.
189
191 ///< Returns this time with given interval added.
192 ///< Throws on overflow.
193
194 TimeInterval operator-( const SystemTime & start ) const ;
195 ///< Returns the given start time's interval() compared
196 ///< to this end time. Returns TimeInterval::zero() on
197 ///< underflow or TimeInterval::limit() on overflow of
198 ///< TimeInterval::s_type.
199
200 TimeInterval interval( const SystemTime & end ) const ;
201 ///< Returns the interval between this time and the given
202 ///< end time. Returns TimeInterval::zero() on underflow or
203 ///< TimeInterval::limit() on overflow of TimeInterval::s_type.
204
205 void streamOut( std::ostream & ) const ;
206 ///< Streams out the time comprised of the s() value, a decimal
207 ///< point, and then the six-digit us() value.
208
209private:
210 friend class G::DateTimeTest ;
211 using time_point_type = std::chrono::time_point<std::chrono::system_clock> ;
212 using duration_type = time_point_type::duration ;
213 explicit SystemTime( time_point_type ) ;
214 SystemTime & add( unsigned long us ) ;
215
216private:
217 time_point_type m_tp ;
218} ;
219
220//| \class G::TimerTime
221/// A monotonically increasing subsecond-resolution timestamp, notionally
222/// unrelated to time_t.
223///
225{
226public:
227 using time_point_type = std::chrono::time_point<std::chrono::steady_clock> ;
228
229 static TimerTime now() ;
230 ///< Factory function for the current steady-clock time.
231
232 static TimerTime zero() ;
233 ///< Factory function for the start of the epoch, guaranteed
234 ///< to be less than any now().
235
236 bool isZero() const noexcept ;
237 ///< Returns true if zero().
238
239 bool sameSecond( const TimerTime & other ) const ;
240 ///< Returns true if this time and the other time are the same,
241 ///< at second resolution.
242
243 static constexpr bool less_noexcept = noexcept(time_point_type() < time_point_type()) ; // NOLINT bogus cert-err58-cpp
244
245 static bool less( const TimerTime & , const TimerTime & ) noexcept(less_noexcept) ;
246 ///< Comparison operator.
247
248 bool operator<=( const TimerTime & ) const ;
249 ///< Comparison operator.
250
251 bool operator==( const TimerTime & ) const ;
252 ///< Comparison operator.
253
254 bool operator!=( const TimerTime & ) const ;
255 ///< Comparison operator.
256
257 bool operator>( const TimerTime & ) const ;
258 ///< Comparison operator.
259
260 bool operator>=( const TimerTime & ) const ;
261 ///< Comparison operator.
262
263 TimerTime operator+( const TimeInterval & ) const ;
264 ///< Returns this time with given interval added.
265
266 void operator+=( TimeInterval ) ;
267 ///< Adds an interval.
268
269 TimeInterval operator-( const TimerTime & start ) const ;
270 ///< Returns the given start time's interval() compared
271 ///< to this end time. Returns TimeInterval::zero() on
272 ///< underflow or TimeInterval::limit() if the
273 ///< TimeInterval::s_type value overflows.
274
275 TimeInterval interval( const TimerTime & end ) const ;
276 ///< Returns the interval between this time and the given
277 ///< end time. Returns TimeInterval::zero() on underflow or
278 ///< TimeInterval::limit() if the TimeInterval::s_type
279 ///< value overflows.
280
281private:
282 friend class G::DateTimeTest ;
283 using duration_type = time_point_type::duration ;
284 explicit TimerTime( time_point_type ) ;
285 static TimerTime test( int , int ) ;
286 unsigned long s() const ; // DateTimeTest
287 unsigned long us() const ; // DateTimeTest
288 std::string str() const ; // DateTimeTest
289
290private:
291 time_point_type m_tp ;
292} ;
293
294//| \class G::TimeInterval
295/// An interval between two G::SystemTime values or two G::TimerTime
296/// values.
297///
299{
300public:
301 using s_type = unsigned int ;
302 using us_type = unsigned int ;
303
304 explicit TimeInterval( unsigned int s , unsigned int us = 0U ) ;
305 ///< Constructor.
306
307 TimeInterval( const SystemTime & start , const SystemTime & end ) ;
308 ///< Constructor. Constructs a zero interval if 'end' is before
309 ///< 'start', and the limit() interval if 'end' is too far
310 ///< ahead of 'start' for the underlying type.
311
312 TimeInterval( const TimerTime & start , const TimerTime & end ) ;
313 ///< Constructor. Overload for TimerTime.
314
315 static TimeInterval zero() ;
316 ///< Factory function for the zero interval.
317
318 static TimeInterval limit() ;
319 ///< Factory function for the maximum valid interval.
320
321 unsigned int s() const ;
322 ///< Returns the number of seconds.
323
324 unsigned int us() const ;
325 ///< Returns the fractional microseconds part.
326
327 void streamOut( std::ostream & ) const ;
328 ///< Streams out the interval.
329
330 bool operator<( const TimeInterval & ) const ;
331 ///< Comparison operator.
332
333 bool operator<=( const TimeInterval & ) const ;
334 ///< Comparison operator.
335
336 bool operator==( const TimeInterval & ) const ;
337 ///< Comparison operator.
338
339 bool operator!=( const TimeInterval & ) const ;
340 ///< Comparison operator.
341
342 bool operator>( const TimeInterval & ) const ;
343 ///< Comparison operator.
344
345 bool operator>=( const TimeInterval & ) const ;
346 ///< Comparison operator.
347
348 TimeInterval operator+( const TimeInterval & ) const ;
349 ///< Returns the combined interval. Throws on overflow.
350
351 TimeInterval operator-( const TimeInterval & ) const ;
352 ///< Returns the interval difference. Throws on underflow.
353
354 void operator+=( TimeInterval ) ;
355 ///< Adds the given interval. Throws on overflow.
356
357 void operator-=( TimeInterval ) ;
358 ///< Subtracts the given interval. Throws on underflow.
359
360private:
361 void normalise() ;
362 static void increase( unsigned int & s , unsigned int ds = 1U ) ;
363 static void decrease( unsigned int & s , unsigned int ds = 1U ) ;
364
365private:
366 unsigned int m_s ;
367 unsigned int m_us ;
368} ;
369
370//| \class G::DateTime
371/// A static class that knows about timezone offsets.
372///
374{
375public:
376 G_EXCEPTION_CLASS( Error , tx("date/time error") ) ;
377 using Offset = std::pair<bool,unsigned int> ;
378
379 static Offset offset( SystemTime ) ;
380 ///< Returns the offset in seconds between UTC and localtime
381 ///< as at the given system time. The returned pair has 'first'
382 ///< set to true if localtime is ahead of (ie. east of) UTC.
383
384 static std::string offsetString( Offset offset ) ;
385 ///< Converts the given utc/localtime offset into a five-character
386 ///< "+/-hhmm" string.
387 ///< See also RFC-2822.
388
389 static std::string offsetString( int hh ) ;
390 ///< Overload for a signed integer timezone.
391
392public:
393 DateTime() = delete ;
394} ;
395
396namespace G
397{
398 std::ostream & operator<<( std::ostream & , const SystemTime & ) ;
399 std::ostream & operator<<( std::ostream & , const TimeInterval & ) ;
400 inline bool operator<( const TimerTime & a , const TimerTime & b ) noexcept(TimerTime::less_noexcept)
401 {
402 return TimerTime::less( a , b ) ;
403 }
404}
405
406inline bool G::TimerTime::less( const TimerTime & a , const TimerTime & b ) noexcept(less_noexcept)
407{
408 return a.m_tp < b.m_tp ;
409}
410
411#endif
An encapsulation of 'struct std::tm'.
Definition: gdatetime.h:45
int wday() const
Returns week day where sunday=0 and saturday=6.
Definition: gdatetime.cpp:301
int day() const
Returns the 1..31 month-day value.
Definition: gdatetime.cpp:296
static BrokenDownTime null()
Factory function for an unusable object with bogus component values.
Definition: gdatetime.cpp:200
std::time_t epochTimeFromLocal() const
Uses std::mktime() to convert this locale-dependent local broken-down time into epoch time.
Definition: gdatetime.cpp:169
std::string str() const
Returns str() using a "%F %T" format.
Definition: gdatetime.cpp:253
int sec() const
Returns the 0..59 or 0..60 seconds value.
Definition: gdatetime.cpp:281
static BrokenDownTime utc(SystemTime)
Factory function for the utc broken-down time of the given epoch time.
Definition: gdatetime.cpp:213
static BrokenDownTime midday(int year, int month, int day)
Factory function for midday on the given date.
Definition: gdatetime.cpp:220
static BrokenDownTime midnight(int year, int month, int day)
Factory function for midnight starting the given date.
Definition: gdatetime.cpp:226
int month() const
Returns the 1..12 month value.
Definition: gdatetime.cpp:291
bool sameMinute(const BrokenDownTime &other) const noexcept
Returns true if this and the other broken-down times are the same, at minute resolution with no round...
Definition: gdatetime.cpp:309
static BrokenDownTime local(SystemTime)
Factory function for the locale-dependent local broken-down time of the given epoch time.
Definition: gdatetime.cpp:206
int hour() const
Returns the 0..23 hour value.
Definition: gdatetime.cpp:271
int year() const
Returns the four-digit year value.
Definition: gdatetime.cpp:286
bool format(char *out, std::size_t out_size, const char *fmt) const
Puts the formatted date, including a terminating null character, into the given output buffer.
Definition: gdatetime.cpp:232
std::time_t epochTimeFromUtc() const
Converts this utc broken-down time into epoch time.
Definition: gdatetime.cpp:175
int min() const
Returns the 0..59 minute value.
Definition: gdatetime.cpp:276
A static class that knows about timezone offsets.
Definition: gdatetime.h:374
static Offset offset(SystemTime)
Returns the offset in seconds between UTC and localtime as at the given system time.
Definition: gdatetime.cpp:772
static std::string offsetString(Offset offset)
Converts the given utc/localtime offset into a five-character "+/-hhmm" string.
Definition: gdatetime.cpp:792
Represents a unix-epoch time with microsecond resolution.
Definition: gdatetime.h:134
TimeInterval operator-(const SystemTime &start) const
Returns the given start time's interval() compared to this end time.
Definition: gdatetime.cpp:333
static SystemTime now()
Factory function for the current time.
Definition: gdatetime.cpp:328
std::time_t s() const noexcept
Returns the number of seconds since the start of the epoch.
Definition: gdatetime.cpp:380
SystemTime operator+(TimeInterval) const
Returns this time with given interval added.
Definition: gdatetime.cpp:440
unsigned int ms() const
Returns the millisecond fraction.
Definition: gdatetime.cpp:367
unsigned int us() const
Returns the microsecond fraction.
Definition: gdatetime.cpp:374
bool operator!=(const SystemTime &) const
Comparison operator.
Definition: gdatetime.cpp:420
BrokenDownTime local() const
Returns the locale-dependent local broken-down time.
Definition: gdatetime.cpp:356
bool operator>(const SystemTime &) const
Comparison operator.
Definition: gdatetime.cpp:426
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:455
TimeInterval interval(const SystemTime &end) const
Returns the interval between this time and the given end time.
Definition: gdatetime.cpp:338
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:351
bool operator<=(const SystemTime &) const
Comparison operator.
Definition: gdatetime.cpp:409
bool isZero() const
Returns true if zero().
Definition: gdatetime.cpp:397
bool operator>=(const SystemTime &) const
Comparison operator.
Definition: gdatetime.cpp:433
static SystemTime zero()
Factory function for the start of the epoch.
Definition: gdatetime.cpp:388
SystemTime(std::time_t, unsigned long us=0UL) noexcept
Constructor.
Definition: gdatetime.cpp:322
BrokenDownTime utc() const
Returns the utc broken-down time.
Definition: gdatetime.cpp:361
void operator+=(TimeInterval)
Adds the given interval. Throws on overflow.
Definition: gdatetime.cpp:448
bool operator<(const SystemTime &) const
Comparison operator.
Definition: gdatetime.cpp:403
bool operator==(const SystemTime &) const
Comparison operator.
Definition: gdatetime.cpp:415
An interval between two G::SystemTime values or two G::TimerTime values.
Definition: gdatetime.h:299
TimeInterval(unsigned int s, unsigned int us=0U)
Constructor.
Definition: gdatetime.cpp:594
TimeInterval operator+(const TimeInterval &) const
Returns the combined interval. Throws on overflow.
Definition: gdatetime.cpp:696
static TimeInterval zero()
Factory function for the zero interval.
Definition: gdatetime.cpp:644
void operator-=(TimeInterval)
Subtracts the given interval. Throws on underflow.
Definition: gdatetime.cpp:741
bool operator==(const TimeInterval &) const
Comparison operator.
Definition: gdatetime.cpp:659
static TimeInterval limit()
Factory function for the maximum valid interval.
Definition: gdatetime.cpp:638
unsigned int s() const
Returns the number of seconds.
Definition: gdatetime.cpp:649
unsigned int us() const
Returns the fractional microseconds part.
Definition: gdatetime.cpp:654
void operator+=(TimeInterval)
Adds the given interval. Throws on overflow.
Definition: gdatetime.cpp:722
bool operator>(const TimeInterval &) const
Comparison operator.
Definition: gdatetime.cpp:683
TimeInterval operator-(const TimeInterval &) const
Returns the interval difference. Throws on underflow.
Definition: gdatetime.cpp:705
bool operator<(const TimeInterval &) const
Comparison operator.
Definition: gdatetime.cpp:671
bool operator!=(const TimeInterval &) const
Comparison operator.
Definition: gdatetime.cpp:665
void streamOut(std::ostream &) const
Streams out the interval.
Definition: gdatetime.cpp:753
bool operator>=(const TimeInterval &) const
Comparison operator.
Definition: gdatetime.cpp:689
bool operator<=(const TimeInterval &) const
Comparison operator.
Definition: gdatetime.cpp:677
A monotonically increasing subsecond-resolution timestamp, notionally unrelated to time_t.
Definition: gdatetime.h:225
bool isZero() const noexcept
Returns true if zero().
Definition: gdatetime.cpp:491
static TimerTime now()
Factory function for the current steady-clock time.
Definition: gdatetime.cpp:479
TimerTime operator+(const TimeInterval &) const
Returns this time with given interval added.
Definition: gdatetime.cpp:525
bool operator>(const TimerTime &) const
Comparison operator.
Definition: gdatetime.cpp:579
TimeInterval interval(const TimerTime &end) const
Returns the interval between this time and the given end time.
Definition: gdatetime.cpp:546
bool operator==(const TimerTime &) const
Comparison operator.
Definition: gdatetime.cpp:566
bool operator!=(const TimerTime &) const
Comparison operator.
Definition: gdatetime.cpp:572
static bool less(const TimerTime &, const TimerTime &) noexcept(less_noexcept)
Comparison operator.
Definition: gdatetime.h:406
TimeInterval operator-(const TimerTime &start) const
Returns the given start time's interval() compared to this end time.
Definition: gdatetime.cpp:540
bool sameSecond(const TimerTime &other) const
Returns true if this time and the other time are the same, at second resolution.
Definition: gdatetime.cpp:552
void operator+=(TimeInterval)
Adds an interval.
Definition: gdatetime.cpp:532
static TimerTime zero()
Factory function for the start of the epoch, guaranteed to be less than any now().
Definition: gdatetime.cpp:486
bool operator<=(const TimerTime &) const
Comparison operator.
Definition: gdatetime.cpp:561
bool operator>=(const TimerTime &) const
Comparison operator.
Definition: gdatetime.cpp:586
Low-level classes.
Definition: garg.h:30
constexpr const char * tx(const char *p)
A briefer alternative to G::gettext_noop().
Definition: ggettext.h:84