ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
timepointbase.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of the \aliblong. It does not belong to an \alibmod and is
4/// included in any \alibbuild.
5///
6/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
7/// Published under \ref mainpage_license "Boost Software License".
8//==================================================================================================
9ALIB_EXPORT namespace alib::time {
10
11#if !DOXYGEN
12# define sc std::chrono::
13#endif
14
15//==================================================================================================
16/// As explained in detail in the documentation of module \alib_time, a steady time model is
17/// supported with class \alib{time;Ticks} and a non-steady one representing the system clock with
18/// class \alib{time;DateTime}.
19/// Both types share this template class as their generic base.
20///
21/// The common features that this class provides to its descendants are:
22/// - Type definition #TTimePoint used to store a point in time.
23/// - Method #Export, which returns the internal value of type #TTimePoint which is of C++
24/// standard type \c std::chrono::time_point.
25/// - Inner class \alib{time::TimePointBase;Duration} that represents the difference type of this
26/// class.
27/// - Static method #Now which creates an instance representing the current point in time.
28/// - Methods #Age and #Since.
29/// - Various overloaded arithmetic and comparison operators.
30///
31/// \note
32/// The resolution and accuracy of the values is platform-dependent. Especially nanoseconds are
33/// deemed to be inaccurate if below several hundreds (this was written and fact in 2013,
34/// reviewed 2019).
35///
36/// \attention
37/// The dates storable in objects of this class are limited to a certain time range. In the
38/// current GNU/Linux and Windows implementations the range is roughly <c>+-292.27</c> years
39/// before and after the point in time that the system that the software is running on was
40/// initialized (bootstrapped). This value results from the following facts for these
41/// implementations:
42/// - the storage resolution is one nanosecond.
43/// - the storage size is 64 bits (63 plus the sign bit).
44/// - system dependent ticks counters are reset to \c 0 with the boot of a system.
45///
46/// Now, dividing <c>2^63</c> by the number of nanoseconds of one year which
47/// consists of roughly 365.25 days, this results in 292.27 years.
48///
49/// @tparam TClock The type of clock to use. This will be
50/// - \c std::chrono::system_clock with descendant class \alib{time;DateTime} and
51/// - \c std::chrono::steady_clock with descendant class \alib{time;Ticks}.
52/// @tparam TDerived The derived type itself, hence either \alib{time;DateTime} or
53/// \alib{time;Ticks}. This template parameter is needed to define the result
54/// type of various methods and operators.
55//==================================================================================================
56template<typename TClock, typename TDerived>
58{
59 public:
60 /// The internal c++ type for time points.
61 using TTimePoint= typename TClock::time_point;
62
63 /// Integral type used for exporting and importing values in raw units.
64 using TRaw= typename TTimePoint::rep;
65
66
67 //==============================================================================================
68 /// This inner class of \b %TimePointBase represents durations, hence difference values of two
69 /// values of the parent class.
70 ///
71 /// Often, objects of this class are generated by the subtraction of \b %TimePointBase values or
72 /// by using methods \alib{time;TimePointBase::Age} and \alib{time;TimePointBase::Since}.
73 /// Furthermore, class \alib{strings::util;CalendarDuration} (found in the module
74 /// \alib_strings) can be used to convert durations to and from human-readable units (days,
75 /// hours, minutes, etc.).
76 ///
77 /// ## Friends ##
78 /// class \alib{time;TimePointBase}
79 //==============================================================================================
81 {
82 #if !DOXYGEN
83 // In C++ inner classes need to be friend to access protected elements of the outer class.
84 friend class TimePointBase;
85 #endif
86
87
88 public:
89 /// The value type for time spans.
90 using TDuration = sc steady_clock::duration;
91
92
93 // #########################################################################################
94 // protected fields
95 // #########################################################################################
96 protected:
97 /// The internal time value.
99
100 // #########################################################################################
101 // Constructors
102 // #########################################################################################
103 public:
104
105 //======================================================================================
106 /// Creates a zero-length time span.
107 //======================================================================================
108 constexpr
110 : span(0)
111 {}
112
113 /// Constructs an instance from C++ library values.
114 /// @see Methods #Import/#Export.
115 /// @param stdLibValue The value to copy into this.
116 Duration( const TDuration& stdLibValue )
117 : span( stdLibValue )
118 {}
119
120 /// Constructs an instance from C++ library values.
121 /// @see Methods #Import/#Export.
122 /// @param stdLibValue The value to copy into this.
123 /// @return A reference to this object.
124 Duration& operator=( const TDuration& stdLibValue ) { span= stdLibValue; return *this; }
125
126 // #########################################################################################
127 // Interface
128 // #########################################################################################
129
130 //======================================================================================
131 /// Returns the internal time span value using the C++ standard library format.
132 /// @return The internal value.
133 //======================================================================================
134 TDuration Export() const { return span; }
135
136 //======================================================================================
137 /// Creates an instance representing the time span given in C++ standard library format.
138 /// @param timeSpan The C++ time point value.
139 /// @return A time span value representing the given externalized \p{timeSpan}.
140 //======================================================================================
141 static
142 Duration Import( const TDuration& timeSpan ) { return Duration ( timeSpan ); }
143
144
145 //======================================================================================
146 /// Sets this object's value to the given duration, in the case the given is shorter.
147 /// @param other The time stamp to compare.
148 /// @return A reference to this object.
149 //======================================================================================
150 Duration& SetMinimum( const Duration& other )
151 {
152 span= (std::min)(span, other.span);
153 return *this;
154 }
155
156 //======================================================================================
157 /// Sets this object's value to the given duration, in the case the given is longer.
158 /// @param other The time stamp to compare.
159 /// @return A reference to this object.
160 //======================================================================================
161 Duration& SetMaximum( const Duration& other )
162 {
163 span= (std::max)(span, other.span);
164 return *this;
165 }
166
167 /// @return \c true if this is a positive duration, \c false otherwise.
168 bool IsPositive() const { return span.count() > 0; }
169
170 /// @return \c true if this is is a zero-length time-span, \c false otherwise.
171 bool IsZero() const { return span.count() == 0; }
172
173 //======================================================================================
174 /// Equal to operator.
175 /// @param other The duration to compare.
176 /// @return The result of the comparison.
177 //======================================================================================
178 bool operator==( const Duration& other ) const { return span == other.span; }
179
180
181 //======================================================================================
182 /// Equal to operator.
183 /// @param other The duration to compare.
184 /// @return The result of the comparison.
185 //======================================================================================
186 bool operator==( const TDuration& other ) const { return span == other; }
187
188 //======================================================================================
189 /// Not equal to operator.
190 /// @param other The duration to compare.
191 /// @return The result of the comparison.
192 //======================================================================================
193 bool operator!=( const Duration& other ) const { return span != other.span; }
194
195 //======================================================================================
196 /// Not equal to operator.
197 /// @param other The duration to compare.
198 /// @return The result of the comparison.
199 //======================================================================================
200 bool operator!=( const TDuration& other ) const { return span != other; }
201
202 //======================================================================================
203 /// Less than operator.
204 /// @param other The duration to compare.
205 /// @return A reference to this object.
206 //======================================================================================
207 bool operator<( const Duration& other ) const { return span < other.span; }
208
209 //======================================================================================
210 /// Less than operator.
211 /// @param other The duration to compare.
212 /// @return A reference to this object.
213 //======================================================================================
214 bool operator<( const TDuration& other ) const { return span < other; }
215
216 //======================================================================================
217 /// Less than or equal to operator.
218 /// @param other The duration to compare.
219 /// @return The result of the comparison.
220 //======================================================================================
221 bool operator<=( const Duration& other ) const { return span <= other.span; }
222
223 //======================================================================================
224 /// Less than or equal to operator.
225 /// @param other The duration to compare.
226 /// @return The result of the comparison.
227 //======================================================================================
228 bool operator<=( const TDuration& other ) const { return span <= other; }
229
230 //======================================================================================
231 /// Greater than operator.
232 /// @param other The duration to compare.
233 /// @return The result of the comparison.
234 //======================================================================================
235 bool operator>( const Duration& other ) const { return span > other.span; }
236
237 //======================================================================================
238 /// Greater than operator.
239 /// @param other The duration to compare.
240 /// @return The result of the comparison.
241 //======================================================================================
242 bool operator>( const TDuration& other ) const { return span > other; }
243
244 //======================================================================================
245 /// Greater than or equal to operator.
246 /// @param other The duration to compare.
247 /// @return The result of the comparison.
248 //======================================================================================
249 bool operator>=( const Duration& other ) const { return span >= other.span; }
250
251 //======================================================================================
252 /// Greater than or equal to operator.
253 /// @param other The duration to compare.
254 /// @return The result of the comparison.
255 //======================================================================================
256 bool operator>=( const TDuration& other ) const { return span >= other; }
257
258 //======================================================================================
259 /// Addition operator.
260 /// @param rhs The right-hand side time span to add.
261 /// @return A time span containing the sum.
262 //======================================================================================
263 Duration operator+( const Duration& rhs ) const { return Duration(span + rhs.span); }
264
265 //======================================================================================
266 /// Addition operator.
267 /// @param rhs The right-hand side time span to add.
268 /// @return A time span containing the sum.
269 //======================================================================================
270 Duration operator+( const TDuration& rhs ) const { return Duration(span + rhs); }
271
272 //======================================================================================
273 /// Assignment by sum operator.
274 /// @param other The time span to subtract.
275 /// @return A reference to this object.
276 //======================================================================================
277 Duration& operator+=( const Duration& other ) { span+= other.span; return *this; }
278
279 //======================================================================================
280 /// Assignment by sum operator.
281 /// @param other The time span to subtract.
282 /// @return A reference to this object.
283 //======================================================================================
284 Duration& operator+=( const TDuration& other ) { span+= other; return *this; }
285
286 //======================================================================================
287 /// Subtraction operator.
288 /// @param rhs The right-hand side time span to subtract.
289 /// @return A time span containing the sum.
290 //======================================================================================
291 Duration operator-( const Duration& rhs ) const { return Duration(span - rhs.span); }
292
293 //======================================================================================
294 /// Subtraction operator.
295 /// @param rhs The right-hand side time span to subtract.
296 /// @return A time span containing the sum.
297 //======================================================================================
298 Duration operator-( const TDuration& rhs ) const { return Duration(span - rhs); }
299
300 //======================================================================================
301 /// Assignment by difference operator.
302 /// @param other The time span subtract.
303 /// @return A reference to this object.
304 //======================================================================================
305 Duration& operator-=( const Duration& other ) { span-= other.span; return *this; }
306
307 //======================================================================================
308 /// Assignment by difference operator.
309 /// @param other The time span subtract.
310 /// @return A reference to this object.
311 //======================================================================================
312 Duration& operator-=( const TDuration& other ) { span-= other; return *this; }
313
314 //======================================================================================
315 /// Multiply operator.
316 /// @param multiplier The multiplier.
317 /// @return A time span containing the sum.
318 //======================================================================================
319 Duration operator*( double multiplier ) const
320 { return sc duration_cast<TDuration>( (span * multiplier) ); }
321
322 //======================================================================================
323 /// Multiply operator.
324 /// @param multiplier The multiplier.
325 /// @return A time span containing the sum.
326 //======================================================================================
327 Duration operator*( int64_t multiplier ) const
328 { return sc duration_cast<TDuration>( (span * multiplier) ); }
329
330 //======================================================================================
331 /// Assignment by product operator.
332 /// @param multiplier The multiplier.
333 /// @return A reference to this object.
334 //======================================================================================
335 Duration& operator*=( double multiplier )
336 { span= sc duration_cast<TDuration>( (span * multiplier) ); return *this; }
337
338 //======================================================================================
339 /// Assignment by product operator.
340 /// @param multiplier The multiplier.
341 /// @return A reference to this object.
342 //======================================================================================
343 Duration& operator*=( int64_t multiplier )
344 { span= sc duration_cast<TDuration>( (span * multiplier) ); return *this; }
345
346 //======================================================================================
347 /// Divide operator.
348 /// @param divisor The divisor.
349 /// @return A time span containing the sum.
350 //======================================================================================
351 Duration operator/( double divisor ) const
352 { return sc duration_cast<TDuration>( (span / divisor) ); }
353
354 //======================================================================================
355 /// Divide operator.
356 /// @param divisor The divisor.
357 /// @return A time span object containing the sum.
358 //======================================================================================
359 Duration operator/( int64_t divisor ) const
360 { return sc duration_cast<TDuration>( (span / divisor) ); }
361
362 //======================================================================================
363 /// Assignment by quotient operator.
364 /// @param divisor The divisor.
365 /// @return A reference to this object.
366 //======================================================================================
367 Duration& operator/=( double divisor )
368 { span= sc duration_cast<TDuration>( (span / divisor) ); return *this; }
369
370
371 //======================================================================================
372 /// Assignment by quotient operator.
373 /// @param divisor The divisor.
374 /// @return A reference to this object.
375 //======================================================================================
376 Duration& operator/=( int64_t divisor )
377 { span= sc duration_cast<TDuration>( (span / divisor) ); return *this; }
378
379
380 // #########################################################################################
381 // Conversion to/from time values (nanoseconds, milliseconds, microseconds, seconds, ...)
382 // #########################################################################################
383 public:
384
385 //======================================================================================
386 /// Converts the internal value to days.
387 /// @return The internal value converted to days.
388 //======================================================================================
389 double InDays() const
390 {
391 return double( sc duration_cast<sc microseconds>( span ).count() )
392 / (1000000. * 3600. * 24. );
393 }
394
395 //======================================================================================
396 /// Converts the internal value to absolute days.
397 /// @return The internal value converted to days.
398 //======================================================================================
400 {
401 return integer( sc duration_cast<sc hours>( span ).count()
402 / 24 );
403 }
404
405 //======================================================================================
406 /// Converts the internal value to hours.
407 /// @return The internal value converted to hours.
408 //======================================================================================
409 double InHours() const
410 {
411 return double( sc duration_cast<sc microseconds>( span ).count() )
412 / (1000000. * 3600. );
413 }
414
415 //======================================================================================
416 /// Converts the internal value to absolute hours.
417 /// @return The internal value converted to hours.
418 //======================================================================================
420 {
421 return integer( sc duration_cast<sc hours>( span ).count() );
422 }
423
424 //======================================================================================
425 /// Converts the internal value to minutes.
426 /// @return The internal value converted to minutes.
427 //======================================================================================
428 double InMinutes() const
429 {
430 return double( sc duration_cast<sc microseconds>( span ).count() )
431 / (1000000. * 60. );
432 }
433
434 //======================================================================================
435 /// Converts the internal value to absolute minutes.
436 /// @return The internal value converted to minutes.
437 //======================================================================================
438 int64_t InAbsoluteMinutes() const
439 {
440 return sc duration_cast<sc minutes>( span ).count();
441 }
442
443 //======================================================================================
444 /// Converts the internal value to seconds.
445 /// @return The internal value converted to seconds.
446 //======================================================================================
447 double InSeconds() const
448 {
449 return double( sc duration_cast<sc nanoseconds>( span ).count() )
450 / (1000000000. );
451 }
452
453 //======================================================================================
454 /// Converts the internal value to absolute seconds.
455 /// @return The internal value converted to seconds.
456 //======================================================================================
457 int64_t InAbsoluteSeconds() const
458 {
459 return sc duration_cast<sc seconds>( span ).count();
460 }
461
462 //======================================================================================
463 /// Converts the internal value to milliseconds.
464 /// @return The internal value converted to milliseconds.
465 //======================================================================================
466 double InMilliseconds() const
467 {
468 return double( sc duration_cast<sc nanoseconds>( span ).count() )
469 / (1000000. );
470 }
471
472 //======================================================================================
473 /// Converts the internal value to absolute milliseconds.
474 /// @return The internal value converted to milliseconds.
475 //======================================================================================
477 {
478 return sc duration_cast<sc milliseconds>( span ).count();
479 }
480
481 //======================================================================================
482 /// Converts the internal value to microseconds.
483 /// @return The internal value converted to microseconds.
484 //======================================================================================
485 double InMicroseconds() const
486 {
487 return double(sc duration_cast<sc nanoseconds>( span ).count())
488 / (1000. );
489 }
490
491 //======================================================================================
492 /// Converts the internal value to absolute microseconds.
493 /// @return The internal value converted to microseconds.
494 //======================================================================================
496 {
497 return sc duration_cast<sc microseconds>( span ).count();
498 }
499
500 //======================================================================================
501 /// Converts the internal value to nanoseconds.
502 /// @return The internal value converted to nanoseconds.
503 //======================================================================================
504 int64_t InNanoseconds() const
505 {
506 return sc duration_cast<sc nanoseconds>( span ).count();
507 }
508
509 //======================================================================================
510 /// Returns 1 divided by internal value in seconds, hence the number of Hertz that this
511 /// object represents when interpreted as a time span.
512 ///
513 /// @param qtyFractionalDigits Number of digits that the return value will be rounded to.
514 /// Defaults to -1 which means no rounding.
515 /// @return double value representing the frequency in hertz.
516 //======================================================================================
517 double InHertz( int qtyFractionalDigits= -1 ) const
518 {
519 // check
520 if ( span.count() == 0)
521 return 0.0;
522
523 // calc hertz
524 double hz= 1000000000.0 / double(InNanoseconds());
525
526 // no rounding? that's it
527 if ( qtyFractionalDigits < 0 )
528 return hz;
529
530 // round
531 double mag= pow( 10, qtyFractionalDigits );
532 return int( hz * mag + ( hz < 0 ? -0.5 : 0.5 ) ) / mag;
533 }
534
535
536 //======================================================================================
537 /// Sets the internal value to a time span provided in days.
538 /// @param days The time span to set in days.
539 /// @return \c *this to allow concatenated calls.
540 //======================================================================================
541 static
542 Duration FromDays( double days )
543 { return sc duration_cast<TDuration>(sc hours(24) * days); }
544
545 //======================================================================================
546 /// Sets the internal value to a time span provided in days.
547 /// @param days The time span to set in days.
548 /// @return \c *this to allow concatenated calls.
549 //======================================================================================
550 static
552 { return sc duration_cast<TDuration>(sc hours(24) * days); }
553
554 //======================================================================================
555 /// Sets the internal value to a time span provided in hours.
556 /// @param hours The time span to set in hours.
557 /// @return \c *this to allow concatenated calls.
558 //======================================================================================
559 static
560 Duration FromHours( double hours )
561 { return sc duration_cast<TDuration>(sc hours(1) * hours); }
562
563 //======================================================================================
564 /// Sets the internal value to a time span provided in hours.
565 /// @param hours The time span to set in hours.
566 /// @return \c *this to allow concatenated calls.
567 //======================================================================================
568 static
570 { return sc duration_cast<TDuration>( sc hours(1) * hours ); }
571
572 //======================================================================================
573 /// Sets the internal value to a time span provided in hours.
574 /// @param minutes The time span to set in minutes.
575 /// @return \c *this to allow concatenated calls.
576 //======================================================================================
577 static
578 Duration FromMinutes(double minutes )
579 { return sc duration_cast<TDuration>( sc minutes(1) * minutes ); }
580
581 //======================================================================================
582 /// Sets the internal value to a time span provided in hours.
583 /// @param minutes The time span to set in minutes.
584 /// @return \c *this to allow concatenated calls.
585 //======================================================================================
586 static
588 { return sc duration_cast<TDuration>( sc minutes(1) * minutes ); }
589
590 //======================================================================================
591 /// Sets the internal value to a time span provided in seconds.
592 /// @param seconds The time span to set in seconds.
593 /// @return \c *this to allow concatenated calls.
594 //======================================================================================
595 static
596 Duration FromSeconds( double seconds )
597 { return sc duration_cast<TDuration>(sc seconds(1) * seconds ); }
598
599 //======================================================================================
600 /// Sets the internal value to a time span provided in seconds.
601 /// @param seconds The time span to set in seconds.
602 /// @return \c *this to allow concatenated calls.
603 //======================================================================================
604 static
605 Duration FromAbsoluteSeconds( int64_t seconds )
606 { return sc duration_cast<TDuration>(sc seconds(1) * seconds); }
607
608 //======================================================================================
609 /// Sets the internal value to a time span provided in milliseconds.
610 /// @param milliseconds The time span to set in milliseconds.
611 /// @return \c *this to allow concatenated calls.
612 //======================================================================================
613 static
614 Duration FromMilliseconds( double milliseconds )
615 { return sc duration_cast<TDuration>(sc milliseconds(1) * milliseconds); }
616
617 //======================================================================================
618 /// Sets the internal value to a time span provided in milliseconds.
619 /// @param milliseconds The time span to set in milliseconds.
620 /// @return \c *this to allow concatenated calls.
621 //======================================================================================
622 static
623 Duration FromAbsoluteMilliseconds( int64_t milliseconds )
624 { return sc duration_cast<TDuration>( sc milliseconds(1) * milliseconds ); }
625
626 //======================================================================================
627 /// Sets the internal value to a time span provided in microseconds.
628 /// @param microseconds The time span to set in microseconds.
629 /// @return \c *this to allow concatenated calls.
630 //======================================================================================
631 static
632 Duration FromMicroseconds( double microseconds )
633 { return sc duration_cast<TDuration>(sc microseconds(1) * microseconds ); }
634
635 //======================================================================================
636 /// Sets the internal value to a time span provided in microseconds.
637 /// @param microseconds The time span to set in microseconds.
638 /// @return \c *this to allow concatenated calls.
639 //======================================================================================
640 static
641 Duration FromAbsoluteMicroseconds( int64_t microseconds )
642 { return sc duration_cast<TDuration>( sc microseconds(1) * microseconds ); }
643
644 //======================================================================================
645 /// Sets the internal value to a time span provided in nanoseconds.
646 /// @param nanoseconds The time span to set in nanoseconds.
647 /// @return \c *this to allow concatenated calls.
648 //======================================================================================
649 static
650 Duration FromNanoseconds( int64_t nanoseconds )
651 { return sc duration_cast<TDuration>(sc nanoseconds( nanoseconds )); }
652 }; // inner class Duration
653
654 // #############################################################################################
655 // protected fields
656 // #############################################################################################
657
658 protected:
659 /// The internal timer value. This value can be accessed using methods #Export and
660 /// #Import.
662
663 // #############################################################################################
664 // Constructors
665 // #############################################################################################
666
667 public:
668 /// Constructor. With parameter \p{init} being defaulted, this constructor acts as
669 /// the default constructor, which creates an instance representing the point in time when
670 /// this constructor was invoked.
671 /// This measures the current point in time, which introduces some effort.
672 ///
673 /// To avoid this in situations where an instance is overwritten after construction
674 /// (i.e., before it is read), parameter \p{init} can be passed to either \b Suppress
675 /// or \b Nulled. Both values set this instance to a \e nulled state, as complete
676 /// suppression is not available. Inn many situations the compiler will optimize out
677 /// a nulled construction.
678 ///
679 /// If not initialized, the method #IsSet will return \c false.
680 ///
681 /// @param init If \c Initialization::Default, the current time is measured and set.
682 /// Defaults to \c Initialization::Default.
683 constexpr
685 {
687 stamp= TClock::now();
688 }
689
690 //==========================================================================================
691 /// Returns an instance representing the actual point in time.
692 /// @return The current point in time time.
693 //==========================================================================================
694 static
695 TDerived Now() { return TDerived(TClock::now()); }
696
697 /// Returns an instance representing the beginning of the epoch.
698 /// No time point represented by this type can be further in the past.
699 /// @return The earliest point in time.
700 static
701 TDerived BeginningOfEpoch() { return TDerived((TClock::time_point::min)()); }
702
703 /// Returns an instance representing the end of the epoch.
704 /// No time point represented by this type can be further in the future.
705 /// @return A maximum point in time.
706 static
707 TDerived EndOfEpoch() { return TDerived((TClock::time_point::max)()); }
708
709 //==========================================================================================
710 /// Resets this instance to the current point in time.
711 /// @return A reference to \c this, (cast to the derived type) to allow concatenated
712 /// operations.
713 //==========================================================================================
714 TDerived& Reset()
715 {
716 stamp= TClock::now();
717 return *static_cast<TDerived*>(this);
718 }
719
720 //==========================================================================================
721 /// Constructor using native C++ library values.
722 /// \see Methods #Import and #Export.
723 ///
724 /// @param internalValue The value to copy into this.
725 //==========================================================================================
726 constexpr
727 TimePointBase( TTimePoint internalValue )
728 : stamp(internalValue)
729 {}
730
731 // #############################################################################################
732 // Interface
733 // #############################################################################################
734 public:
735
736 //==========================================================================================
737 /// Returns \c true if this object is not representing the start of the epoch.
738 /// An uninitialized object that returns \c false can be created with provision of
739 /// \c Initialization::Suppress on construction.
740 ///
741 /// @return \c true if this object is initialized, \c false otherwise.
742 //==========================================================================================
743 bool IsSet()
744 {
745 return stamp != TTimePoint();
746 }
747
748 //==========================================================================================
749 /// Unsets this object, hence makes this object representing the start of the epoch, as if
750 /// it was constructed with parameter value \c Initialization::Suppress.
751 //==========================================================================================
752 void Unset()
753 {
754 stamp= TTimePoint();
755 }
756
757 //==========================================================================================
758 /// Copies the value from the given object.
759 /// @param other The point in time to copy from.
760 //==========================================================================================
761 void SetAs( const TDerived& other )
762 {
763 stamp= other.stamp;
764 }
765
766 //==========================================================================================
767 /// Returns the internal time value in the C++ standard library type.
768 /// @return The internal value.
769 //==========================================================================================
771 {
772 return stamp;
773 }
774
775 //==========================================================================================
776 /// Sets the internal time value given by a value of C++ standard library type.
777 /// @param timePoint The value to set.
778 //==========================================================================================
779 void Import(TTimePoint timePoint)
780 {
781 stamp= timePoint;
782 }
783
784
785 //==========================================================================================
786 /// Returns the internal time value in the C++ standard library's tick unit.
787 ///
788 /// @return The internal value.
789 //==========================================================================================
790 TRaw ToRaw() const
791 { return stamp.time_since_epoch().count(); }
792
793 //==========================================================================================
794 /// Sets the value from a value of C++ standard library's tick unit type.
795 /// @param raw The time span to create in raw units.
796 //==========================================================================================
797 void SetFromRaw( TRaw raw )
798 { stamp= TTimePoint( typename TClock::duration( raw ) ); }
799
800 //==========================================================================================
801 /// Creates an instance from a value of C++ standard library's tick unit type.
802 ///
803 /// @param raw The time span to create in raw units.
804 /// @return The internal value.
805 //==========================================================================================
806 static
807 TDerived FromRaw( TRaw raw )
808 { return TDerived( TTimePoint( typename TClock::duration( raw ) ) ); }
809
810 //==========================================================================================
811 /// Addition operator.
812 /// @param timeSpan The time span to add.
813 /// @return A time stamp object containing the sum.
814 //==========================================================================================
815 TDerived operator+( const Duration& timeSpan ) const
816 { return stamp + sc duration_cast<typename TClock::duration>( timeSpan.span ); }
817
818 //==========================================================================================
819 /// Addition operator.
820 /// @param timeSpan The time span to add.
821 /// @return A time stamp object containing the sum.
822 //==========================================================================================
823 TDerived operator+( const typename Duration::TDuration& timeSpan ) const
824 { return stamp + timeSpan; }
825
826 //==========================================================================================
827 /// Assignment by sum operator.
828 /// @param timeSpan The time span to add.
829 /// @return A reference to this object.
830 //==========================================================================================
831 TDerived operator+=( const Duration& timeSpan )
832 {
833 stamp+= sc duration_cast<typename TClock::duration>( timeSpan.span );
834 return stamp;
835 }
836
837 //==========================================================================================
838 /// Assignment by sum operator.
839 /// @param timeSpan The time span to add.
840 /// @return A reference to this object.
841 //==========================================================================================
842 TDerived operator+=( const typename Duration::TDuration& timeSpan )
843 { stamp+= timeSpan; return stamp; }
844
845 //==========================================================================================
846 /// Subtraction operator.
847 /// @param timeSpan The time span to subtract.
848 /// @return A time stamp object containing the sum.
849 //==========================================================================================
850 TDerived operator-( const Duration& timeSpan ) const
851 { return stamp - sc duration_cast<typename TClock::duration>( timeSpan.span ); }
852
853 //==========================================================================================
854 /// Subtraction operator.
855 /// @param timeSpan The time span to subtract.
856 /// @return A time stamp object containing the sum.
857 //==========================================================================================
858 TDerived operator-( const typename Duration::TDuration& timeSpan ) const
859 { return stamp - timeSpan; }
860
861 //==========================================================================================
862 /// Assignment by difference operator.
863 /// @param timeSpan The time span to subtract.
864 /// @return A reference to this object.
865 //==========================================================================================
866 TDerived operator-=( const Duration& timeSpan )
867 {
868 stamp-= timeSpan.span;
869 return stamp;
870 }
871
872 //==========================================================================================
873 /// Assignment by difference operator.
874 /// @param timeSpan The time span to subtract.
875 /// @return A reference to this object.
876 //==========================================================================================
877 TDerived operator-=( const typename Duration::TDuration& timeSpan )
878 { stamp-= timeSpan; return stamp; }
879
880 //==========================================================================================
881 /// Subtraction operator with other time span argument. If the given time stamp represents
882 /// a point in type earlier than the one this object represents, the result is positive.
883 /// @param other The time stamp to subtract.
884 /// @return A time span object containing the difference.
885 //==========================================================================================
886 Duration operator-( const TDerived& other ) const
887 { return Duration(stamp - other.stamp); }
888
889 // #############################################################################################
890 // Interface Age, Since
891 // #############################################################################################
892
893 //==========================================================================================
894 /// Returns the time span between the value represented by this instance and the current
895 /// system time.
896 /// If the internal value represents a historic point in time, the result is positive.
897 ///
898 /// @return The age of this instance stored in a new Duration.
899 //==========================================================================================
900 Duration Age() const
901 { return Duration( TDerived().stamp - this->stamp ); }
902
903 //==========================================================================================
904 /// Returns the time span between the value represented by this instance and the given
905 /// other time stamp. If the given time stamp represents an earlier point in time, the result
906 /// is positive.
907 ///
908 /// @param other The value to compare this instance with
909 ///
910 /// @return The age of this instance stored in the given or created object.
911 //==========================================================================================
912 Duration Since( const TDerived& other ) const
913 { return (*this) - other; }
914
915 //==========================================================================================
916 /// Determines if this object's age is higher than a given time span.
917 ///
918 /// @param timeSpan A time span to compare.
919 /// @return \c true if the given time span is smaller equal than the age of this object,
920 /// hence to the time span passed since the point in time this object represents.
921 /// \c false otherwise.
922 //==========================================================================================
923 bool IsOlderThan( const Duration& timeSpan ) const
924 { return Age() > timeSpan; }
925
926}; // class TimePointBase
927
928} // namespace [alib::time]
929
930#undef sc
931
double InHertz(int qtyFractionalDigits=-1) const
static Duration FromAbsoluteMicroseconds(int64_t microseconds)
bool operator!=(const TDuration &other) const
Duration & operator=(const TDuration &stdLibValue)
bool operator!=(const Duration &other) const
bool operator<(const TDuration &other) const
Duration & operator/=(int64_t divisor)
TDuration span
The internal time value.
Duration & operator/=(double divisor)
Duration operator/(double divisor) const
Duration & operator*=(double multiplier)
Duration operator+(const Duration &rhs) const
static Duration FromAbsoluteMinutes(int64_t minutes)
bool operator>(const TDuration &other) const
Duration & operator+=(const Duration &other)
static Duration FromMinutes(double minutes)
static Duration FromMicroseconds(double microseconds)
sc steady_clock::duration TDuration
The value type for time spans.
Duration & operator+=(const TDuration &other)
static Duration FromAbsoluteSeconds(int64_t seconds)
bool operator==(const TDuration &other) const
static Duration FromSeconds(double seconds)
Duration operator-(const TDuration &rhs) const
bool operator<(const Duration &other) const
Duration operator+(const TDuration &rhs) const
bool operator<=(const TDuration &other) const
Duration(const TDuration &stdLibValue)
Duration & SetMinimum(const Duration &other)
bool operator>=(const TDuration &other) const
static Duration FromAbsoluteHours(int64_t hours)
static Duration FromDays(double days)
bool operator>=(const Duration &other) const
constexpr Duration()
Creates a zero-length time span.
Duration operator/(int64_t divisor) const
bool operator<=(const Duration &other) const
Duration & SetMaximum(const Duration &other)
Duration operator*(int64_t multiplier) const
static Duration FromMilliseconds(double milliseconds)
Duration & operator-=(const Duration &other)
bool operator>(const Duration &other) const
static Duration Import(const TDuration &timeSpan)
static Duration FromAbsoluteDays(int64_t days)
bool operator==(const Duration &other) const
static Duration FromHours(double hours)
Duration operator-(const Duration &rhs) const
Duration operator*(double multiplier) const
Duration & operator*=(int64_t multiplier)
Duration & operator-=(const TDuration &other)
static Duration FromNanoseconds(int64_t nanoseconds)
static Duration FromAbsoluteMilliseconds(int64_t milliseconds)
Duration operator-(const TDerived &other) const
TTimePoint Export() const
TDerived operator-(const typename Duration::TDuration &timeSpan) const
constexpr TimePointBase(const lang::Initialization init=lang::Initialization::Default)
TDerived operator-=(const typename Duration::TDuration &timeSpan)
constexpr TimePointBase(TTimePoint internalValue)
void Import(TTimePoint timePoint)
static TDerived EndOfEpoch()
TDerived operator+=(const Duration &timeSpan)
static TDerived FromRaw(TRaw raw)
TDerived operator+(const typename Duration::TDuration &timeSpan) const
TDerived operator+(const Duration &timeSpan) const
TDerived operator-=(const Duration &timeSpan)
typename TTimePoint::rep TRaw
Integral type used for exporting and importing values in raw units.
typename TClock::time_point TTimePoint
The internal c++ type for time points.
bool IsOlderThan(const Duration &timeSpan) const
TDerived operator+=(const typename Duration::TDuration &timeSpan)
Duration Since(const TDerived &other) const
TDerived operator-(const Duration &timeSpan) const
static TDerived BeginningOfEpoch()
void SetAs(const TDerived &other)
#define ALIB_EXPORT
Definition alib.inl:488
Initialization
Used for example with constructors that allow to suppress initialization of members.
lang::integer integer
Type alias in namespace alib.
Definition integers.inl:149