NanoTime¶

Utilities for handling time periods at nanosecond resolution.

namespace NanoTime¶

Enums

enum Unit¶

Identify units for a scalar quantity of time.

Note: Ordered in increasing unit size, e.g. days > seconds

Values:

Nanoseconds¶

Microseconds¶

Milliseconds¶

Seconds¶

Minutes¶

Hours¶

Days¶

UnitMax = Days¶

Functions

const char *unitToString(Unit unit)¶: Get a string identifying the given time units, e.g. “ns”.

const char *unitToLongString(Unit unit)¶: Get a long string identifying the given time units, e.g. “seconds”.

template <uint64_t time, Unit unitsFrom, Unit unitsTo, typename R = std::ratio_divide<UnitTickRatio<unitsTo>, UnitTickRatio<unitsFrom>>> constexpr uint64_t convert()¶

Function template to convert a constant time quantity from one unit to another.

Note

example:

uint32_t micros = convert<50, Milliseconds, Microseconds>();

Template Parameters

time: The time to convert
unitsFrom: Units for time parameter
unitsTo: Units for return value

Return Value

TimeType: Converted time

template <typename TimeType> TimeType convert(const TimeType &time, Unit unitsFrom, Unit unitsTo)¶

Function template to convert a time quantity from one unit to another.

Template Parameters

TimeType: Variable type to use for calculation

Parameters

time: The time to convert
unitsFrom: Units for time parameter
unitsTo: Units for return value

Return Value

TimeType: Converted time, returns TimeType(-1) if calculation overflowed

template <typename T> Time<T> time(Unit unit, T value)¶: Helper function to create a Time and deduce the type.

template <Unit unitsFrom, Unit unitsTo, typename TimeType> TimeType convert(const TimeType &time)¶

Function template to convert a time quantity from one unit to another.

Template Parameters

unitsFrom: Units for time parameter
unitsTo: Units for return value
TimeType: Variable type to use for calculation

Parameters

time: The time to convert

Return Value

TimeType: Converted time, returns TimeType(-1) if calculation overflowed

Variables

constexpr BasicRatio32 unitTicks[UnitMax + 1] = { {1000000000, 1}, {1000000, 1}, {1000, 1}, {1, 1}, {1, 60}, {1, 60 * 60}, {1, 24 * 60 * 60}, } ¶: List of clock ticks for each supported unit of time.

template <typename ClockDef, uint32_t frequency_, typename TickType_, TickType_ maxTicks_> struct Clock¶

#include <NanoTime.h>

Class template representing a physical Clock with fixed timing characteristics.

Note

Physical clocks are implemented using this as a base. The provided frequency accounts for any prescaler setting in force. Fixing this at compile time helps to avoid expensive runtime calculations and permits static range checks.

See

Use TimeSource to work with a Clock in specific time units

Template Parameters

ClockDef: The actual Clock being constructed (so we can query its properties)
frequency_: Clock frequency in Hz
TickType_: Variable type representing the clock’s tick value
maxTicks_: Maximum count value for the clock

Subclassed by NanoTime::TimeSource< Clock, unit_, TimeType >

Public Types

template<> using TickType = TickType_¶

template<> using TicksConst = TicksConst<Clock, ticks>¶

template<> using TimeConst = TimeConst<Clock, unit, time>¶

template<> using TicksPerUnit = std::ratio_divide<std::ratio<frequency_>, UnitTickRatio<unit>>¶

template<> using TimeSource = TimeSource<Clock, unit, TimeType>¶

template<> using Ticks = Ticks<Clock, T>¶

template<> using MaxTicks = TicksConst<maxTicks_>¶

template<> using MaxTime = typename MaxTicks::template TimeConst<unit>¶

Public Static Functions

static constexpr const char *typeName()¶

static constexpr uint32_t frequency()

static constexpr MaxTicks maxTicks()

template <Unit unit> static constexpr MaxTime<unit> maxTime()

static Ratio32 ticksPerUnit(Unit unit)

Get ticks per unit as a Ratio object.

Return Value

BasicRatio32:

template <Unit unit, uint64_t time> static constexpr TimeConst<unit, time> timeConst()

Class template defining a fixed time quantity.

Template Parameters

time:

Return Value

TimeConst:

template <uint64_t ticks> static constexpr TicksConst<ticks> ticksConst()

Class template defining a fixed tick quantity.

Template Parameters

ticks:

Return Value

TicksConst<Clockticks>:

template <Unit unit, typename TimeType> static constexpr TimeSource<unit, TimeType> timeSource()

Create a Time Source for this Clock.

Template Parameters

unit:
TimeType:

template <Unit unit, typename TimeType> static Ticks<TimeType> timeToTicks(TimeType time)

Get the number of ticks for a given time.

Parameters

time:

Return Value

TimeType: Tick count, rounded to the nearest tick

template <Unit unit, typename TimeType> static Time<TimeType> ticksToTime(TimeType ticks)

Get the time for a given number of clock ticks.

Parameters

ticks:

Return Value

TimeType: Time count, rounded to the nearest unit

static String toString()

struct Frequency¶

#include <NanoTime.h>

Class to represent a frequency.

Public Functions

Frequency(uint32_t frequency)¶

operator uint32_t()¶

String toString() const¶

Get frequency as compact string.

Note: Drop trailing zeroes to produce a more compact string, e.g. 0 -> 0Hz 1000 -> 1KHz 4553000 -> 4553KHz 1000000000 -> 1GHz

Public Members

uint32_t frequency¶

template <typename Clock_, typename T> struct Ticks¶

#include <NanoTime.h>

Class to handle a tick value associated with a clock.

Public Types

template<> using Clock = Clock_¶

Public Functions

Ticks(T ticks)¶

operator T() const¶

String toString() const¶

template <Unit unit> Time<T> as()¶

Public Members

T ticks¶

Public Static Functions

static constexpr Clock clock()¶

template <class Clock_, uint64_t ticks_> struct TicksConst¶

#include <NanoTime.h>

Class template representing a fixed clock tick count.

Note

Includes compile-time range checking

Template Parameters

Source_:
ticks_:

Public Types

template<> using Clock = Clock_¶

template<> using TickType = uint64_t¶

template<> using TimeType = uint64_t¶

template<> using TimeConst = TimeConst<Clock, unit, TimeType(round(double(ticks_) * Clock::template TicksPerUnit<unit>::den / Clock::template TicksPerUnit<unit>::num))>¶

Public Functions

constexpr operator TickType()¶

Public Static Functions

static constexpr TickType ticks()¶

static constexpr void check()¶

Obtain the tick count with a static range check against Clock maxTicks.

Return Value

TimeType:

template <Unit unit> static constexpr TimeConst<unit> as()¶

Get the time for the tick count in a specific time unit.

Template Parameters

unit:

Return Value

Time<TimeType>:

static String toString()¶

template <typename T> struct Time¶

#include <NanoTime.h>

Class to handle a simple time value with associated unit.

Public Functions

Time()¶

Time(Unit unit, T time)¶

void set(Unit unit, T time)¶

operator T() const¶

String toString() const¶

Time &operator+=(Time<T> rhs)¶

TimeValue value() const¶

template <Unit unitTo> Time as() const¶

Time as(Unit unitTo) const¶

Public Members

Unit unit = Seconds ¶

T time = 0¶

Friends

Time &operator+(Time lhs, const Time &rhs)¶

template <class Clock_, Unit unit_, uint64_t time_> struct TimeConst¶

#include <NanoTime.h>

Class template to represent a fixed time value for a specific Clock.

Note

Includes compile-time range checking. Time is taken as reference for conversions.

Template Parameters

Clock_:
unit_:
time_:

Public Types

template<> using Clock = Clock_¶

template<> using TicksPerUnit = typename Clock::template TicksPerUnit<unit_>¶

Public Functions

constexpr operator uint64_t()¶

Public Static Functions

static constexpr Clock clock()¶

static constexpr Unit unit()¶

static constexpr uint64_t time()¶

static Ratio32 ticksPerUnit()¶

Get ticks per unit as a Ratio object.

Return Value

BasicRatio32:

static constexpr uint64_t ticks()¶

Return the corresponding tick value for the time interval.

Return Value

TimeType:

static constexpr void check()¶

Use this function to perform a static (compile-time) range check against Clock maxTicks.

Return Value

TimeType:

static constexpr uint64_t clockTime()¶

Obtain the actual Clock time by converting tick value.

Return Value

TimeType:

template <Unit unit> static constexpr uint64_t as()¶

Obtain the time in a different set of units.

Template Parameters

unit:

Return Value

TimeType:

static TimeValue value()¶

static TimeValue clockValue()¶

static String toString()¶

template <class Clock_, Unit unit_, typename TimeType_> struct TimeSource : public Clock_¶

#include <NanoTime.h>

Class template for accessing a Clock in specific time units.

Note

Includes compile-time range checking. Time is taken as reference for conversions.

Template Parameters

Clock_:
units_:
TimeType_: Limits range of calculations

Public Types

template<> using Clock = Clock_¶

template<> using TimeType = TimeType_¶

template<> using TicksPerUnit = typename Clock::template TicksPerUnit<unit_>¶

template<> using TimeConst = TimeConst<Clock, unit_, time>¶

template<> using TicksConst = TicksConst<Clock, ticks>¶

template<> using MaxClockTime = typename Clock::template MaxTime<unit_>¶: Get the time corresponding to the maximum clock tick value.

Public Static Functions

static constexpr Unit unit()¶

static constexpr BasicRatio32 ticksPerUnit()¶

Number of clock ticks per unit of time.

Return Value

BasicRatio32: Result as a rational fraction

static constexpr MaxClockTime maxClockTime()¶

template <uint64_t time> static constexpr TimeConst<time> timeConst()¶

Obtain a TimeConst type representing the given time quantity.

Note

Use methods of TimeConst to obtain corresponding tick count, etc.

Template Parameters

time:

Return Value

TimeConst:

template <uint64_t ticks> static constexpr TicksConst<ticks> ticksConst()¶

Class template defining a fixed tick quantity.

Note

Use methods of TickConst to obtain corresponding time values, etc.

Template Parameters

ticks:

Return Value

TicksConst:

static constexpr Time<TimeType_> maxCalcTime()¶

The maximum time value supported by timeToTicks without overflowing.

Return Value

TimeType: Passing values larger than this to timeToTicks() will truncate at maximum value

static constexpr Ticks<Clock_, TimeType_> maxCalcTicks()¶

The maximum tick value supported by ticksToTime without overflowing.

Return Value

TimeType: Passing values larger than this to ticksToTime() will truncate at maximum value

static Ticks<Clock_, TimeType_> timeToTicks(TimeType time)¶

Get the number of ticks for a given time.

Parameters

time:

Return Value

TimeType: Tick count, rounded to the nearest tick

template <uint64_t time> static constexpr uint64_t timeToTicks()¶

Get the number of ticks for a given time.

Template Parameters

time:

Return Value

uint64_t: Tick count, rounded to the nearest tick

template <uint64_t ticks> static constexpr uint64_t ticksToTime()¶

Get the time for a given number of clock ticks.

Template Parameters

ticks:

Return Value

TimeType: Time count, rounded to the nearest unit

static Time<TimeType_> ticksToTime(TimeType ticks)¶

Get the time for a given number of clock ticks.

Parameters

ticks:

Return Value

TimeType: Time count, rounded to the nearest unit

static String toString()¶

struct TimeValue¶

#include <NanoTime.h>

A time time broken into its constituent elements.

Note: Useful for analysing and printing time values

Public Functions

TimeValue()¶

template <typename TimeType> TimeValue(Unit unit, TimeType time)¶

Resolve a time value into constituent components.

Parameters

time: The time to resolve
unit: Units for given time

template <typename TimeType> void set(Unit unit, TimeType time)¶

uint32_t getMicroseconds() const¶: Get sub-second time entirely in microseconds.

uint32_t getNanoseconds() const¶: Get sub-second time entirely in nanoseconds.

String toString() const¶

operator String() const¶

Public Members

bool overflow = false¶

Unit unit = Seconds ¶: Time unit passed to set() call.

uint32_t days = 0¶

uint8_t hours = 0¶

uint8_t minutes = 0¶

uint8_t seconds = 0¶

uint16_t milliseconds = 0¶

uint32_t microseconds = 0¶

uint32_t nanoseconds = 0¶

template <Unit unit> struct UnitTickRatio¶

#include <NanoTime.h>

Class template to define tick std::ratio type.

Note

This would be preferable: template <Unit unit> using UnitTickRatio = std::ratio<unitTicks[unit].num, unitTicks[unit].den>; But GCC 4.8 doesn’t like it (lvalue required as unary ‘&’ operand)

Template Parameters

unit:

Return Value

std::ratio: Ticks per second

Public Static Attributes

constexpr uint64_t num = unitTicks[unit].num¶

constexpr uint64_t den = unitTicks[unit].den¶