Class Time

Class Documentation

class Time

Provides functionality for time stamps and conversion between different formats.

Public Functions

Time() = default

Construct a new Time object initialized to the unix epoch.

explicit Time(const char *timestamp, uint64_t picoseconds = 0)

Construct a new Time object from a timestamp with optional picoseconds precision.

Parameters

  • timestamp – timestamp in form YYYY-MM-DD-HH:MM:SS +tz

  • picoseconds – the fractional seconds of time in picoseconds, defaults to 0.

explicit Time(const std::string &timestamp, uint64_t picoseconds = 0)

Construct a new Time object from a timestamp with optional picoseconds precision.

Parameters

  • timestamp – timestamp in form YYYY-MM-DD-HH:MM:SS +tz

  • picoseconds – the fractional seconds of time in picoseconds, defaults to 0.

explicit Time(time_t timestamp)

Construct a new Time object from a time epoch.

Parameters

timestamp – timestamp to initialise with

explicit Time(uint64_t samples_since_ska_epoch, uint16_t sample_period_numerator, uint16_t sample_period_denominator)

Construct a new Time object given number of samples since SKA Epoch and a given sample period.

Parameters

  • samples_since_ska_epoch – the number of samples since SKA epoch.

  • sample_period_numerator – the numerator of the sample period, in microseconds.

  • sample_period_denominator – the denominator of the sample period, in microseconds.

~Time() = default

Destroy the Time object.

void set_time(const std::string &timestamp)

Set the time of the object.

Parameters

timestamp – in form YYYY-MM-DD-HH:MM:SS +tz

inline void set_time(time_t timestamp)

Set the time of the object.

Parameters

timestamp – in form YYYY-MM-DD-HH:MM:SS +tz

inline auto get_time() -> time_t

Return the time of the object.

Returns

time_t epoch to return

void set_fractional_time(double seconds)

Set the fractional seconds part of the timestamp.

Parameters

seconds – of the fractional part of the timestamp

void set_fractional_time_attoseconds(uint64_t attoseconds)

Set the fractional seconds part of the timestamp, in attoseconds.

Parameters

attoseconds – of the fractional part of the timestamp, in attoseconds.

auto get_fractional_time() const -> double

Get the fractional time of the timestamp in seconds.

Returns

double fractional time in seconds

auto get_fractional_time_attoseconds() const -> uint64_t

Get the fractional time of the timestamp in attoseconds.

Returns

uint64_t fractional time in attoseconds

auto get_fractional_time_picoseconds() const -> uint64_t

Get the fractional time of the timestamp in picoseconds.

Returns

uint64_t fractional time in picoseconds

inline auto get_mjd_day() -> int

Return the timestamp as a Modified Julian Day The return value is an integer day.

Returns

int

auto get_gm_year() -> int

Return the year of the object.

Returns

int

auto get_gm_month() -> int

Return the month of the object.

Returns

int

inline void add_seconds(unsigned n)

Add the specified seconds to the object.

Parameters

n – number of seconds to add

inline void sub_seconds(unsigned n)

Subtract the specified seconds from the object.

Parameters

n – number of seconds to subtract

auto get_localtime() -> std::string

Return a string representation of the timestamp in the local time zone.

Returns

std::string localtime timestamp in YYYY-MM-DD-HH:MM:SS format

auto get_gmtime() -> std::string

Return a string representation of the timestamp in the UTC time zone.

Returns

std::string gmtime timestamp in YYYY-MM-DD-HH:MM:SS format

auto get_iso8601_utc() -> std::string

Return a string representation of the timestamp in ISO 8601 format in UTC timezone.

Returns

std::string gmtime timestamp in YYYY-MM-DDTHH:MM:SS.ssssss+00:00 format

void set_samples_since_ska_epoch(uint64_t samples_since_ska_epoch, uint16_t sample_period_numerator, uint16_t sample_period_denominator)

set the time to be equivalent of the number of packets since SKA epoch.

Parameters

  • samples_since_ska_epoch – the number of samples since SKA epoch.

  • sample_period_numerator – the numerator of the sample period, in microseconds.

  • sample_period_denominator – the denominator of the sample period, in microseconds.

auto adjust_to_nearest_sample(uint16_t sample_period_numerator, uint16_t sample_period_denominator) -> uint64_t

adjust the time to nearest sample period from SKA Epoch that the current time is closest to.

Parameters

  • sample_period_numerator – the numerator of the sample period, in microseconds.

  • sample_period_denominator – the denominator of the sample period, in microseconds.

Returns

the nearest sample packet sequence number from SKA epoch that the current time is closest to.

auto get_samples_since_ska_epoch(uint16_t sample_period_numerator, uint16_t sample_period_denominator) -> uint64_t

get the sample sequence number from SKA Epoch given a sample period that the current time is closest to.

Parameters

  • sample_period_numerator – the numerator of the sample period, in microseconds.

  • sample_period_denominator – the denominator of the sample period, in microseconds.

inline bool operator==(const Time &rhs) const

check if two timestamps are equal.

This checks the time relative to UNIX epoch are the same for both instances and the fractional attoseconds are the same.

Parameters

rhs – the other Time object to compare equality against.

Returns

if the two timestamps are equal.

inline bool operator<(const Time &rhs) const

check if the current time object is before another instance

Parameters

rhs – the instance to compare this object against

Returns

true if the current instance is before the other instance

Returns

false if the current instance is not before the other instance

inline bool operator<=(const Time &rhs) const

check if the current time object is before or equal another instance

Parameters

rhs – the instance to compare this object against

Returns

true if the current instance is before or equal to the other instance

Returns

false if the current instance is after the other instance

inline bool operator>(const Time &rhs) const

check if the current time object is after another instance

Parameters

rhs – the instance to compare this object against

Returns

true if the current instance is after the other instance

Returns

false if the current instance is not after the other instance

inline bool operator>=(const Time &rhs) const

check if the current time object is after or equal another instance

Parameters

rhs – the instance to compare this object against

Returns

true if the current instance is after or equal to the other instance

Returns

false if the current instance is before the other instance

inline double operator-(const Time &rhs) const

get the difference of the current instance and another instance, in seconds.

Parameters

rhs – the other instance to get difference from

Returns

double the difference of the current instance and another instance, in seconds.

Public Static Functions

static auto now() -> Time

Create an instance of a Time object including fractional seconds to the current microseconds.

Returns

Time

static auto mjd2utctm(double mjd) -> time_t

Convert an MJD to the time_t.

Parameters

mjd –

Returns

time_t

static auto format_localtime(time_t e) -> std::string

Convert the provided epoch into a string timestamp in the local time zone.

Parameters

e – epoch to convert

Returns

std::string timestamp in local time zone

static auto format_gmtime(time_t e) -> std::string

Converted the provided epoch into a string timestamp in the UTC time zone.

Parameters

e – epoch to convert

Returns

std::string timestamp in the UTC time zone

static auto format_iso8601_utc(time_t e, uint64_t microseconds = 0) -> std::string

Converted the provided epoch into a string ISO 8601 in UTC.

This will include microseconds and create a formatted timestamp like “2025-09-15T09:20:03.615307+00:00”

Parameters

  • e – epoch to convert

  • microseconds – microseconds to add to the converted epoch

Returns

std::string timestamp in the UTC time zone