TimePoint Class Reference

Overview

Represents a point in time.

More specifically, stores the number of milliseconds elapsed since an arbitrary point in the past. This number is stored as a 32-bit unsigned integer and thus wraps every 4,294,967,295 milliseconds, or approximately 49.7 days. Because of this, it's recommended to only compare TimePoints on a time scale which is shorter than that by at least an order of magnitude. This reduces the likelihood that wrapping will be an issue.

auto start_time = etcpal::TimePoint::Now();
 
// Do some work...
 
auto end_time = etcpal::TimePoint::Now();
EXPECT_GT(end_time, start_time);
int32_t interval = end_time - start_time; // How long did it take, in milliseconds?

TimePoints are compared by comparing the signed difference of their respective values with 0. This creates a "half the range" rule of thumb for comparison; TimePoints will compare accurately as long as they were sampled during the same process execution and within 2^31 milliseconds (24.9 days) of each other.

This can be unintuitive to understand since TimePoints are based on unsigned 32-bit values which are compared as if they are signed. Here are some examples:

etcpal::TimePoint(0u) < etcpal::TimePoint(0x7fffffffu) // true
etcpal::TimePoint(0u) < etcpal::TimePoint(0x80000000u) // true
etcpal::TimePoint(0u) < etcpal::TimePoint(0x80000001u) // false
 
// You can shift both of these points by any constant interval and it will still hold true. For
// example:
 
etcpal::TimePoint(0xc0000000u) < etcpal::TimePoint(0x3fffffffu) // true
etcpal::TimePoint(0xc0000000u) < etcpal::TimePoint(0x40000000u) // true
etcpal::TimePoint(0xc0000000u) < etcpal::TimePoint(0x40000001u) // false
 
// And the same principle applies to using operator-:
 
etcpal::TimePoint(0x7fffffffu) - etcpal::TimePoint(0u) // 2,147,483,647; makes sense
etcpal::TimePoint(0x80000000u) - etcpal::TimePoint(0u) // -2,147,483,648; doesn't make sense
etcpal::TimePoint(0x80000001u) - etcpal::TimePoint(0u) // -2,147,483,647; doesn't make sense

In order to avoid headaches of the kind that often arise when thinking about two's complement, again, it's recommended to only compare TimePoints on a scale much less than days.

Public Member Functions
	TimePoint ()=default
	Construct a TimePoint with a value of 0 by default. More...
constexpr	TimePoint (uint32_t ms)
	Construct a TimePoint from a number of milliseconds elapsed since a point in the past.
constexpr uint32_t	value () const noexcept
	Get the raw millisecond value from a TimePoint.
ETCPAL_CONSTEXPR_14 TimePoint &	operator+= (uint32_t duration) noexcept
	Add a millisecond duration to a TimePoint.
ETCPAL_CONSTEXPR_14 TimePoint &	operator-= (uint32_t duration) noexcept
	Subtract a millisecond duration from a TimePoint.

Static Public Member Functions
static TimePoint	Now () noexcept
	Get a TimePoint representing the current time.

Constructor & Destructor Documentation

TimePoint()

TimePoint ( )

default

Construct a TimePoint with a value of 0 by default.

Be careful when default-constructing TimePoints; since TimePoints store the number of milliseconds elapsed since an arbitrary point in the past, a default-constructed TimePoint will compare equal to etcpal::TimePoint::Now() every 49.7 days.

---

The documentation for this class was generated from the following file:

• include/etcpal/cpp/timer.h