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
25 namespace Poco {
26
27
28 class Timespan;
29
30
31 class 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 {
49 public:
50 using TimeVal = Int64;
51 /// Monotonic UTC time value in microsecond resolution,
52 /// with base time midnight, January 1, 1970.
53
54 using UtcTimeVal = Int64;
55 /// Monotonic UTC time value in 100 nanosecond resolution,
56 /// with base time midnight, October 15, 1582.
57
58 using TimeDiff = Int64;
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
148 private:
149 TimeVal _ts;
150 };
151
152
153 //
154 // inlines
155 //
156 inline bool Timestamp::operator == (const Timestamp& ts) const
157 {
158 return _ts == ts._ts;
159 }
160
161
162 inline bool Timestamp::operator != (const Timestamp& ts) const
163 {
164 return _ts != ts._ts;
165 }
166
167
168 inline bool Timestamp::operator > (const Timestamp& ts) const
169 {
170 return _ts > ts._ts;
171 }
172
173
174 inline bool Timestamp::operator >= (const Timestamp& ts) const
175 {
176 return _ts >= ts._ts;
177 }
178
179
180 inline bool Timestamp::operator < (const Timestamp& ts) const
181 {
182 return _ts < ts._ts;
183 }
184
185
186 inline bool Timestamp::operator <= (const Timestamp& ts) const
187 {
188 return _ts <= ts._ts;
189 }
190
191
192 inline Timestamp Timestamp::operator + (Timestamp::TimeDiff d) const
193 {
194 return Timestamp(_ts + d);
195 }
196
197
198 inline Timestamp Timestamp::operator - (Timestamp::TimeDiff d) const
199 {
200 return Timestamp(_ts - d);
201 }
202
203
204 inline Timestamp::TimeDiff Timestamp::operator - (const Timestamp& ts) const
205 {
206 return _ts - ts._ts;
207 }
208
209
210 inline Timestamp& Timestamp::operator += (Timestamp::TimeDiff d)
211 {
212 _ts += d;
213 return *this;
214 }
215
216
217 inline Timestamp& Timestamp::operator -= (Timestamp::TimeDiff d)
218 {
219 _ts -= d;
220 return *this;
221 }
222
223
epochTime()224 inline std::time_t Timestamp::epochTime() const
225 {
226 return std::time_t(_ts/resolution());
227 }
228
229
utcTime()230 inline Timestamp::UtcTimeVal Timestamp::utcTime() const
231 {
232 return _ts*10 + (TimeDiff(0x01b21dd2) << 32) + 0x13814000;
233 }
234
235
epochMicroseconds()236 inline Timestamp::TimeVal Timestamp::epochMicroseconds() const
237 {
238 return _ts;
239 }
240
241
elapsed()242 inline Timestamp::TimeDiff Timestamp::elapsed() const
243 {
244 Timestamp now;
245 return now - *this;
246 }
247
248
isElapsed(Timestamp::TimeDiff interval)249 inline bool Timestamp::isElapsed(Timestamp::TimeDiff interval) const
250 {
251 Timestamp now;
252 Timestamp::TimeDiff diff = now - *this;
253 return diff >= interval;
254 }
255
256
resolution()257 inline Timestamp::TimeDiff Timestamp::resolution()
258 {
259 return 1000000;
260 }
261
262
swap(Timestamp & s1,Timestamp & s2)263 inline void swap(Timestamp& s1, Timestamp& s2)
264 {
265 s1.swap(s2);
266 }
267
268
raw()269 inline Timestamp::TimeVal Timestamp::raw() const
270 {
271 return _ts;
272 }
273
274
275 } // namespace Poco
276
277
278 #endif // Foundation_Timestamp_INCLUDED
279