1//
2// Timestamp.h
3//
4// Library: Foundation
5// Package: DateTime
6// Module: Timestamp
7//
8// Definition of the Timestamp 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_Timestamp_INCLUDED
18#define Foundation_Timestamp_INCLUDED
19
20
21#include "Poco/Foundation.h"
22#include <ctime>
23
24
25namespace Poco {
26
27
28class Timespan;
29
30
31class Foundation_API Timestamp
32 /// A Timestamp stores a monotonic* time value
33 /// with (theoretical) microseconds resolution.
34 /// Timestamps can be compared with each other
35 /// and simple arithmetic is supported.
36 ///
37 /// [*] Note that Timestamp values are only monotonic as
38 /// long as the systems's clock is monotonic as well
39 /// (and not, e.g. set back due to time synchronization
40 /// or other reasons).
41 ///
42 /// Timestamps are UTC (Coordinated Universal Time)
43 /// based and thus independent of the timezone
44 /// in effect on the system.
45 ///
46 /// The internal reference time is the Unix epoch,
47 /// midnight, January 1, 1970.
48{
49public:
50 typedef Int64 TimeVal;
51 /// Monotonic UTC time value in microsecond resolution,
52 /// with base time midnight, January 1, 1970.
53
54 typedef Int64 UtcTimeVal;
55 /// Monotonic UTC time value in 100 nanosecond resolution,
56 /// with base time midnight, October 15, 1582.
57
58 typedef Int64 TimeDiff;
59 /// Difference between two TimeVal values in microseconds.
60
61 static const TimeVal TIMEVAL_MIN; /// Minimum timestamp value.
62 static const TimeVal TIMEVAL_MAX; /// Maximum timestamp value.
63
64 Timestamp();
65 /// Creates a timestamp with the current time.
66
67 Timestamp(TimeVal tv);
68 /// Creates a timestamp from the given time value
69 /// (microseconds since midnight, January 1, 1970).
70
71 Timestamp(const Timestamp& other);
72 /// Copy constructor.
73
74 ~Timestamp();
75 /// Destroys the timestamp
76
77 Timestamp& operator = (const Timestamp& other);
78 Timestamp& operator = (TimeVal tv);
79
80 void swap(Timestamp& timestamp);
81 /// Swaps the Timestamp with another one.
82
83 void update();
84 /// Updates the Timestamp with the current time.
85
86 bool operator == (const Timestamp& ts) const;
87 bool operator != (const Timestamp& ts) const;
88 bool operator > (const Timestamp& ts) const;
89 bool operator >= (const Timestamp& ts) const;
90 bool operator < (const Timestamp& ts) const;
91 bool operator <= (const Timestamp& ts) const;
92
93 Timestamp operator + (TimeDiff d) const;
94 Timestamp operator + (const Timespan& span) const;
95 Timestamp operator - (TimeDiff d) const;
96 Timestamp operator - (const Timespan& span) const;
97 TimeDiff operator - (const Timestamp& ts) const;
98 Timestamp& operator += (TimeDiff d);
99 Timestamp& operator += (const Timespan& span);
100 Timestamp& operator -= (TimeDiff d);
101 Timestamp& operator -= (const Timespan& span);
102
103 std::time_t epochTime() const;
104 /// Returns the timestamp expressed in time_t.
105 /// time_t base time is midnight, January 1, 1970.
106 /// Resolution is one second.
107
108 UtcTimeVal utcTime() const;
109 /// Returns the timestamp expressed in UTC-based
110 /// time. UTC base time is midnight, October 15, 1582.
111 /// Resolution is 100 nanoseconds.
112
113 TimeVal epochMicroseconds() const;
114 /// Returns the timestamp expressed in microseconds
115 /// since the Unix epoch, midnight, January 1, 1970.
116
117 TimeDiff elapsed() const;
118 /// Returns the time elapsed since the time denoted by
119 /// the timestamp. Equivalent to Timestamp() - *this.
120
121 bool isElapsed(TimeDiff interval) const;
122 /// Returns true iff the given interval has passed
123 /// since the time denoted by the timestamp.
124
125 TimeVal raw() const;
126 /// Returns the raw time value.
127 ///
128 /// Same as epochMicroseconds().
129
130 static Timestamp fromEpochTime(std::time_t t);
131 /// Creates a timestamp from a std::time_t.
132
133 static Timestamp fromUtcTime(UtcTimeVal val);
134 /// Creates a timestamp from a UTC time value
135 /// (100 nanosecond intervals since midnight,
136 /// October 15, 1582).
137
138 static TimeDiff resolution();
139 /// Returns the resolution in units per second.
140 /// Since the timestamp has microsecond resolution,
141 /// the returned value is always 1000000.
142
143#if defined(_WIN32)
144 static Timestamp fromFileTimeNP(UInt32 fileTimeLow, UInt32 fileTimeHigh);
145 void toFileTimeNP(UInt32& fileTimeLow, UInt32& fileTimeHigh) const;
146#endif
147
148private:
149 TimeVal _ts;
150};
151
152
153//
154// inlines
155//
156inline bool Timestamp::operator == (const Timestamp& ts) const
157{
158 return _ts == ts._ts;
159}
160
161
162inline bool Timestamp::operator != (const Timestamp& ts) const
163{
164 return _ts != ts._ts;
165}
166
167
168inline bool Timestamp::operator > (const Timestamp& ts) const
169{
170 return _ts > ts._ts;
171}
172
173
174inline bool Timestamp::operator >= (const Timestamp& ts) const
175{
176 return _ts >= ts._ts;
177}
178
179
180inline bool Timestamp::operator < (const Timestamp& ts) const
181{
182 return _ts < ts._ts;
183}
184
185
186inline bool Timestamp::operator <= (const Timestamp& ts) const
187{
188 return _ts <= ts._ts;
189}
190
191
192inline Timestamp Timestamp::operator + (Timestamp::TimeDiff d) const
193{
194 return Timestamp(_ts + d);
195}
196
197
198inline Timestamp Timestamp::operator - (Timestamp::TimeDiff d) const
199{
200 return Timestamp(_ts - d);
201}
202
203
204inline Timestamp::TimeDiff Timestamp::operator - (const Timestamp& ts) const
205{
206 return _ts - ts._ts;
207}
208
209
210inline Timestamp& Timestamp::operator += (Timestamp::TimeDiff d)
211{
212 _ts += d;
213 return *this;
214}
215
216
217inline Timestamp& Timestamp::operator -= (Timestamp::TimeDiff d)
218{
219 _ts -= d;
220 return *this;
221}
222
223
224inline std::time_t Timestamp::epochTime() const
225{
226 return std::time_t(_ts/resolution());
227}
228
229
230inline Timestamp::UtcTimeVal Timestamp::utcTime() const
231{
232 return _ts*10 + (TimeDiff(0x01b21dd2) << 32) + 0x13814000;
233}
234
235
236inline Timestamp::TimeVal Timestamp::epochMicroseconds() const
237{
238 return _ts;
239}
240
241
242inline Timestamp::TimeDiff Timestamp::elapsed() const
243{
244 Timestamp now;
245 return now - *this;
246}
247
248
249inline bool Timestamp::isElapsed(Timestamp::TimeDiff interval) const
250{
251 Timestamp now;
252 Timestamp::TimeDiff diff = now - *this;
253 return diff >= interval;
254}
255
256
257inline Timestamp::TimeDiff Timestamp::resolution()
258{
259 return 1000000;
260}
261
262
263inline void swap(Timestamp& s1, Timestamp& s2)
264{
265 s1.swap(s2);
266}
267
268
269inline Timestamp::TimeVal Timestamp::raw() const
270{
271 return _ts;
272}
273
274
275} // namespace Poco
276
277
278#endif // Foundation_Timestamp_INCLUDED
279