timestamp.h File Reference

Time-stamp utility functions. More...

#include "common.h"
#include <time.h>

Go to the source code of this file.

Macros
#define	QSC_TIMESTAMP_EPOCH_START   1900ULL
	The year starting the epoch.
#define	QSC_TIMESTAMP_SECONDS_PER_MINUTE   60ULL
	The number of seconds in a minute.
#define	QSC_TIMESTAMP_SECONDS_PER_HOUR   (QSC_TIMESTAMP_SECONDS_PER_MINUTE * 60ULL)
	The number of seconds in an hour.
#define	QSC_TIMESTAMP_SECONDS_PER_DAY   (QSC_TIMESTAMP_SECONDS_PER_HOUR * 24ULL)
	The number of seconds in a day.
#define	QSC_TIMESTAMP_STRING_SIZE   20ULL
	The size of the time-stamp string.

Functions
QSC_EXPORT_API void	qsc_timestamp_current_date (char output[QSC_TIMESTAMP_STRING_SIZE])
	Get the calendar date from the current locale.
QSC_EXPORT_API void	qsc_timestamp_current_datetime (char output[QSC_TIMESTAMP_STRING_SIZE])
	Get the calendar date and time from the current locale. Time-stamp string format is YYYY-MM-DD HH-MM-SS.
QSC_EXPORT_API void	qsc_timestamp_current_time (char output[QSC_TIMESTAMP_STRING_SIZE])
	Get the local time.
QSC_EXPORT_API uint64_t	qsc_timestamp_epochtime_seconds (void)
	Get the date and time from the current locale in seconds from epoch.
QSC_EXPORT_API void	qsc_timestamp_time_struct_to_string (char output[QSC_TIMESTAMP_STRING_SIZE], const struct tm *tstruct)
	Convert a time structure to a date and time string. Time-stamp string format is YYYY-MM-DD HH-MM-SS.
QSC_EXPORT_API void	qsc_timestamp_string_to_time_struct (struct tm *tstruct, const char input[QSC_TIMESTAMP_STRING_SIZE])
	Convert a date and time string to a time structure. Time-stamp string format must be YYYY-MM-DD HH-MM-SS.
QSC_EXPORT_API uint64_t	qsc_timestamp_datetime_seconds_remaining (const char basetime[QSC_TIMESTAMP_STRING_SIZE], const char comptime[QSC_TIMESTAMP_STRING_SIZE])
	Compare a base date-time with another future date-time string, and return the difference in seconds. if the comparison date is less than the base date, the return is zero. Time-stamp string format must be YYYY-MM-DD HH-MM-SS.
QSC_EXPORT_API uint64_t	qsc_timestamp_datetime_to_seconds (const char input[QSC_TIMESTAMP_STRING_SIZE])
	Convert the date-time string to a seconds from epoch unsigned 64-bit integer.
QSC_EXPORT_API uint64_t	qsc_timestamp_datetime_utc (void)
	Get the calendar date and time for utc time.
QSC_EXPORT_API void	qsc_timestamp_seconds_to_datetime (uint64_t tsec, char output[QSC_TIMESTAMP_STRING_SIZE])
	Convert a seconds count from epoch-time to a date-time string.

Detailed Description

Time-stamp utility functions.

This header provides a collection of functions for retrieving and formatting time-stamp information from the system clock. It supports operations for obtaining the current calendar date, current local time, and current date-time in a formatted string ("YYYY-MM-DD HH-MM-SS"). In addition, it includes a stopwatch functionality to measure elapsed time in milliseconds and functions to convert between epoch time and human-readable date-time strings.

// Example usage:
#include "timestamp.h"
#include <stdio.h>
 
int main(void)
{
    char date[QSC_TIMESTAMP_STRING_SIZE];
    char datetime[QSC_TIMESTAMP_STRING_SIZE];
    char time_str[QSC_TIMESTAMP_STRING_SIZE];
 
    // Retrieve current date, time, and full datetime strings.
    qsc_timestamp_current_date(date);
    qsc_timestamp_current_datetime(datetime);
    qsc_timestamp_current_time(time_str);
 
    printf("Current Date: %s\n", date);
    printf("Current DateTime: %s\n", datetime);
    printf("Current Time: %s\n", time_str);
 
    // Measure elapsed time using the stopwatch functions.
    uint64_t start = qsc_timestamp_epochtime_seconds();
    // ... perform some operations ...
    uint64_t elapsed = qsc_timestamp_stopwatch_elapsed(start);
    printf("Elapsed time: %llu ms\n", elapsed);
 
    return 0;
}

Reference Links:

• Microsoft Time Documentation
• POSIX Time Documentation

Function Documentation

qsc_timestamp_current_date()

QSC_EXPORT_API void qsc_timestamp_current_date

(

char

output[QSC_TIMESTAMP_STRING_SIZE]

)

Get the calendar date from the current locale.

Parameters

output

[char*] The output date string

qsc_timestamp_current_datetime()

QSC_EXPORT_API void qsc_timestamp_current_datetime

(

char

output[QSC_TIMESTAMP_STRING_SIZE]

)

Get the calendar date and time from the current locale. Time-stamp string format is YYYY-MM-DD HH-MM-SS.

Parameters

output

[char*] The output time and date string

qsc_timestamp_current_time()

QSC_EXPORT_API void qsc_timestamp_current_time

(

char

output[QSC_TIMESTAMP_STRING_SIZE]

)

Get the local time.

Parameters

output

[char*] The output time string

qsc_timestamp_datetime_seconds_remaining()

QSC_EXPORT_API uint64_t qsc_timestamp_datetime_seconds_remaining	(	const char	basetime[QSC_TIMESTAMP_STRING_SIZE],
		const char	comptime[QSC_TIMESTAMP_STRING_SIZE] )

Compare a base date-time with another future date-time string, and return the difference in seconds. if the comparison date is less than the base date, the return is zero. Time-stamp string format must be YYYY-MM-DD HH-MM-SS.

Parameters

basetime	[const char*] The base time string
comptime	[const char*] The future time string

Returns

[uint64_t] Returns the number of seconds remaining

qsc_timestamp_datetime_to_seconds()

QSC_EXPORT_API uint64_t qsc_timestamp_datetime_to_seconds

(

const char

input[QSC_TIMESTAMP_STRING_SIZE]

)

Convert the date-time string to a seconds from epoch unsigned 64-bit integer.

Parameters

input

[const char*] The input date-time string

Returns

[uint64_t] The number of seconds in the date-time string

qsc_timestamp_datetime_utc()

QSC_EXPORT_API uint64_t qsc_timestamp_datetime_utc

(

void

)

Get the calendar date and time for utc time.

Returns

[uint64_t] The number of seconds

qsc_timestamp_epochtime_seconds()

QSC_EXPORT_API uint64_t qsc_timestamp_epochtime_seconds

(

void

)

Get the date and time from the current locale in seconds from epoch.

Returns

[uint64_t] Return the date/time in seconds from epoch

qsc_timestamp_seconds_to_datetime()

QSC_EXPORT_API void qsc_timestamp_seconds_to_datetime	(	uint64_t	tsec,
		char	output[QSC_TIMESTAMP_STRING_SIZE] )

Convert a seconds count from epoch-time to a date-time string.

Parameters

tsec	[uint64_t] The number of seconds between the clock epoch time and now
output	[char*] The output time and date string

qsc_timestamp_string_to_time_struct()

QSC_EXPORT_API void qsc_timestamp_string_to_time_struct	(	struct tm *	tstruct,
		const char	input[QSC_TIMESTAMP_STRING_SIZE] )

Convert a date and time string to a time structure. Time-stamp string format must be YYYY-MM-DD HH-MM-SS.

Parameters

tstruct	[struct tm*] The time struct to be populated
input	[const char*] The input time and date string

qsc_timestamp_time_struct_to_string()

QSC_EXPORT_API void qsc_timestamp_time_struct_to_string	(	char	output[QSC_TIMESTAMP_STRING_SIZE],
		const struct tm *	tstruct )

Convert a time structure to a date and time string. Time-stamp string format is YYYY-MM-DD HH-MM-SS.

Parameters

output	[char*] The output time and date string
tstruct	[const struct tm*] The populated time structure