This class holds a time value represented as seconds from the system epoch. More...

#include <trek_time.h>

Public Member Functions
Constructors, Destructor, and Other Basic Methods
	TrekTime ()
	Default constructor of the class.

	TrekTime (TrekTime &input)
	Copy constructor of the class.

virtual	~TrekTime ()
	Class destructor. More...

void	operator= (TrekTime &right_side)
	Provides the equal operator.

Methods for setting time
int32_t	SetTime ()
	Sets the time to the current system time. More...

int32_t	SetTime (uint32_t sec, uint32_t sub=0)
	Sets the time relative the system epoch based on the input. More...

int32_t	SetTime (const char *input_ptr)
	Sets the time based on the input string. More...

int32_t	SetTime (double input)
	Sets the time relative the system epoch based on the input. More...

void	SetSubsecondsPerSecond (uint32_t input)
	Sets the number of subseconds per second. More...

Methods for getting time
void	GetTime (uint32_t &sec, uint32_t &sub)
	Gets the time relative the system epoch. More...

void	GetTime (double &input)
	Gets the time relative the system epoch. More...

int32_t	GetTime (char time_str, uint32_t size_of_output, bool fractional=false, bool file_friendly=false)
	Gets the time as a string. More...

int32_t	GetTime (uint16_t &year, uint16_t &day_of_year, uint8_t &month, uint8_t &day_of_month, uint8_t &hours, uint8_t &minutes, double &seconds)
	Gets the time as value components. More...

Miscellaneous methods
uint32_t	GetSeconds ()
	Returns the current number of seconds since the epoch.

uint32_t	GetSubseconds ()
	Returns the current number of subseconds.

uint32_t	GetSubsecondsPerSecond ()
	Returns the number of subseconds per second.

double	GetDeltaTime (TrekTime &input)
	Gets the difference between two times. More...

int32_t	ShiftTime (double input)
	Shifts the time. More...

Detailed Description

This class holds a time value represented as seconds from the system epoch.

The time may also have an optional fractional second (subsecond) value. The number of subseconds allowed is enforced by the maximum subseconds per second value. The default number of subseconds per second is 1,000,000 (microseconds).

Note: Windows systems can use this class to represent times until 2100-01-01. However, Linux systems can only represent time until 2038-01-19 03:14:07.

Constructor & Destructor Documentation

◆ ~TrekTime()

trek::TrekTime::~TrekTime ( )

virtual

Class destructor.

Removes all resources created with this instance of the class.

Member Function Documentation

◆ GetDeltaTime()

double trek::TrekTime::GetDeltaTime ( TrekTime & input )

Gets the difference between two times.

Calculates a double precision floating point number representing the difference between the input time and the time stored in this class. If the input time is later, the value will be positive. The times are not required to have the same subsecond resolution.

Parameters

[in] input The second time value.

Example:

TrekTime time1, time2;
int32_t ret_value;
 
// skipping check on return values here...you shouldn't
ret_value = time1.SetTime( "1998-12-21 12:23:34" );
ret_value = time2.SetTime( "2007-02-16 00:00:03.544" );
 
ret_value = time1.GetDeltaTime( time2 );
 
if( ret_value )
    ;   // process error

◆ GetTime() [1/4]

int32_t trek::TrekTime::GetTime	(	char *	time_str,
		uint32_t *	size_of_output,
		bool	fractional = `false`,
		bool	file_friendly = `false`
	)

Gets the time as a string.

Gets the time as a string in the format:

    YYYY-MM-SS hh:mm:ss(.fff)

Parameters

[out]	time_str	The time as seconds since epoch.
[in,out]	size_of_output	The number of bytes allocated for the buffer on input. If return code is set to TREK_DATA_NOT_ENOUGH_SPACE, then the value is reset to the number of bytes required for the data to be copied.
[in]	fractional	Include subseconds in returned string
[in]	file_friendly	Uses '-' instead of ':' and ' ' for formatting

Returns: SUCCESS; TREK_DATA_NOT_ENOUGH_SPACE; TREK_DATA_NULL_PTR

Example:

TrekTime my_time;
my_time.SetTime();
 
char the_time[50];
uint32_t size_of_output = 50;
 
my_time.GetTime( the_time, &size_of_output, true, false );

◆ GetTime() [2/4]

void trek::TrekTime::GetTime ( double & input )

Gets the time relative the system epoch.

Parameters

[out] input The time as seconds since epoch.

Example:

TrekTime my_time;
my_time.SetTime();
 
double the_time;
my_time.GetTime( the_time );

◆ GetTime() [3/4]

int32_t trek::TrekTime::GetTime	(	uint16_t &	year,
		uint16_t &	day_of_year,
		uint8_t &	month,
		uint8_t &	day_of_month,
		uint8_t &	hours,
		uint8_t &	minutes,
		double &	seconds
	)

Gets the time as value components.

Parameters

[out]	year	Actual year number (e.g., 1999).
[out]	day_of_year	Day of year (Jan 1 is day 1).
[out]	month	Month of year (Jan is month 1).
[out]	day_of_month	Day of month (1-31).
[out]	hours	Hours of day (0-23).
[out]	minutes	Minutes of hour (0-59).
[out]	seconds	Seconds of minute (0-59.999999...).

Returns: SUCCESS; TREK_DATA_TIME_ERROR

Example:

TrekTime my_time;
my_time.SetTime();
 
uint16_t year, day_of_year;
uin8_t month, day_of_month, hours, minutes;
double seconds;
int32_t ret_value;
ret_value = my_time.GetTime( year, day_of_year, month, day_of_month, hours, minutes, seconds );
 
if( ret_value )
    ;   // process error

◆ GetTime() [4/4]

void trek::TrekTime::GetTime	(	uint32_t &	sec,
		uint32_t &	sub
	)

Gets the time relative the system epoch.

Parameters

[out]	sec	The number of seconds since the system epoch.
[out]	sub	The number of subseconds of the second.

Example:

TrekTime my_time;
my_time.SetTime();
 
uint32_t sec, sub;
my_time.GetTime( sec, sub );

◆ SetSubsecondsPerSecond()

void trek::TrekTime::SetSubsecondsPerSecond ( uint32_t input )

Sets the number of subseconds per second.

Also resets the current subseconds to zero.

Parameters

[in] input The new number of subseconds per second.

Example:

TrekTime my_time;
// change to use milliseconds (default is microseconds)
my_time.SetSubsecondsPerSecond(1000);

◆ SetTime() [1/4]

int32_t trek::TrekTime::SetTime ( )

Sets the time to the current system time.

If the subseconds per second are allowed (see SetSubsecondsPerSecond), fractional seconds will be set as well.

Returns: SUCCESS

Example:

TrekTime my_time;
 
ret_value = my_time.SetTime();
 
if( ret_value )
    ; // process error

◆ SetTime() [2/4]

int32_t trek::TrekTime::SetTime ( const char * input_ptr )

Sets the time based on the input string.

The format of the string is:

    YYYY-MM-DD hh:mm:ss(.fffff)
Where
    YYYY is the year and between 1970 and 2099 inclusive.
    MM is the month between 01 and 12 inclusive
    DD is the day between 01 and 31 inclusive
    hh is the hours between 00 and 23 inclusive
    mm is the minutes between 00 and 59 inclusive
    ss is the seconds between 00 and 59 inclusive
    (.fffff) is the optional fractional seconds without the parentheses.

Parameters

[in] input_ptr The new time.

Returns: SUCCESS; TREK_DATA_TIME_LENGTH_ERROR; TREK_DATA_TIME_STRING_FORMAT_ERROR; TREK_DATA_TIME_TOO_SOON; TREK_DATA_ILLEGAL_MONTH; TREK_DATA_ILLEGAL_DAY; TREK_DATA_ILLEGAL_HOURS; TREK_DATA_ILLEGAL_MINUTES; TREK_DATA_ILLEGAL_SECONDS; TREK_DATA_NULL_PTR

Example:

TrekTime my_time;
 
// set time to a birthday
ret_value = my_time.SetTime( "2005-03-30 07:00:00" );
 
if( ret_value )
    ; // process error

◆ SetTime() [3/4]

int32_t trek::TrekTime::SetTime ( double input )

Sets the time relative the system epoch based on the input.

Parameters

[in] input The new time.

Returns: SUCCESS; TREK_DATA_NEG_TIME_NOT_ALLOWED

Example:

TrekTime my_time;
 
// set time to one hour past epoch plus 100 milliseconds
ret_value = my_time.SetTime( 3600.100 );
 
if( ret_value )
    ; // process error

◆ SetTime() [4/4]

int32_t trek::TrekTime::SetTime	(	uint32_t	sec,
		uint32_t	sub = `0`
	)

Sets the time relative the system epoch based on the input.

Returns: SUCCESS; TREK_DATA_FRACTIONAL_TIME_VALUE_ERROR

Parameters

[in]	sec	The new seconds since the epoch.
[in]	sub	The new subseconds of seconds.

Example:

TrekTime my_time;
 
// set time to one hour past epoch plus 1000 microseconds
ret_value = my_time.SetTime( 3600, 1000 );
 
if( ret_value )
    ; // process error

◆ ShiftTime()

int32_t trek::TrekTime::ShiftTime ( double input )

Shifts the time.

Adds the input time to the current value stored in class.

Parameters

[in] input The number of seconds to shift time. Negative values shift to earlier time.

Returns: SUCCESS; TREK_DATA_NEG_TIME_NOT_ALLOWED

Example:

TrekTime the_time;
int32_t ret_value;
 
// skipping check on return values here...you shouldn't
ret_value = the_time.SetTime( "1970-01-01 00:00:01" );
 
// This will return an error since time would be before Jan. 1, 1970.
ret_value = the_time.ShiftTime( -10.01 );
 
if( ret_value )
    ;   // process error

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~TrekTime()

Member Function Documentation

◆ GetDeltaTime()

◆ GetTime() [1/4]

◆ GetTime() [2/4]

◆ GetTime() [3/4]

◆ GetTime() [4/4]

◆ SetSubsecondsPerSecond()

◆ SetTime() [1/4]

◆ SetTime() [2/4]

◆ SetTime() [3/4]

◆ SetTime() [4/4]

◆ ShiftTime()