xtime.h File Reference

Extended time utilities and high-precision timing functions. More...

#include <stdbool.h>
#include <stdint.h>
#include <time.h>

Include dependency graph for xtime.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	xtime_t

Macros
#define	XTIME_FMT_ISO8601   "%Y-%m-%dT%H:%M:%S"

Enumerations
enum	xtime_error_t

Functions
xtime_error_t	xtime_init (xtime_t *t)
xtime_error_t	xtime_now (xtime_t *t)
xtime_error_t	xtime_utc_now (xtime_t *t)
xtime_error_t	xtime_parse (const char *str, const char *format, xtime_t *t)
xtime_error_t	xtime_format (const xtime_t *t, const char *format, char *buf, size_t buflen)
xtime_error_t	xtime_format_utc (const xtime_t *t, const char *format, char *buf, size_t buflen)
int64_t	xtime_to_unix (const xtime_t *t)
xtime_error_t	xtime_to_json (const xtime_t *t, char *buf, size_t buflen)
xtime_error_t	xtime_from_unix (int64_t timestamp, xtime_t *t)
xtime_error_t	xtime_add_seconds (xtime_t *t, int64_t seconds)
int	xtime_compare (const xtime_t *t1, const xtime_t *t2)
xtime_error_t	xtime_diff (const xtime_t *t1, const xtime_t *t2, double *diff)
const char *	xtime_strerror (xtime_error_t err)
xtime_error_t	xtime_add_nanoseconds (xtime_t *t, int64_t nanos)
xtime_error_t	xtime_add_microseconds (xtime_t *t, int64_t micros)
xtime_error_t	xtime_add_milliseconds (xtime_t *t, int64_t millis)
xtime_error_t	xtime_add_minutes (xtime_t *t, int64_t minutes)
xtime_error_t	xtime_add_hours (xtime_t *t, int64_t hours)
xtime_error_t	xtime_add_days (xtime_t *t, int64_t days)
xtime_error_t	xtime_add_years (xtime_t *t, int years)
xtime_error_t	xtime_add_months (xtime_t *t, int months)
xtime_error_t	xtime_diff_nanos (const xtime_t *t1, const xtime_t *t2, int64_t *nanos)
xtime_error_t	xtime_diff_micros (const xtime_t *t1, const xtime_t *t2, int64_t *micros)
xtime_error_t	xtime_diff_millis (const xtime_t *t1, const xtime_t *t2, int64_t *millis)
xtime_error_t	xtime_diff_seconds (const xtime_t *t1, const xtime_t *t2, int64_t *seconds)
xtime_error_t	xtime_diff_minutes (const xtime_t *t1, const xtime_t *t2, int64_t *minutes)
xtime_error_t	xtime_diff_hours (const xtime_t *t1, const xtime_t *t2, int64_t *hours)
xtime_error_t	xtime_diff_days (const xtime_t *t1, const xtime_t *t2, int64_t *days)
bool	xtime_is_leap_year (const xtime_t *t)
xtime_error_t	xtime_truncate_to_day (xtime_t *t)
xtime_error_t	xtime_truncate_to_hour (xtime_t *t)
xtime_error_t	xtime_truncate_to_minute (xtime_t *t)
xtime_error_t	xtime_truncate_to_second (xtime_t *t)
xtime_error_t	xtime_start_of_week (const xtime_t *t, xtime_t *result)
xtime_error_t	xtime_start_of_month (const xtime_t *t, xtime_t *result)
xtime_error_t	xtime_start_of_year (const xtime_t *t, xtime_t *result)
xtime_error_t	xtime_end_of_day (const xtime_t *t, xtime_t *result)
xtime_error_t	xtime_end_of_month (const xtime_t *t, xtime_t *result)
xtime_error_t	xtime_end_of_year (const xtime_t *t, xtime_t *result)

Detailed Description

Extended time utilities and high-precision timing functions.

Cross-platform time parsing and formatting library.

Provides fast, safe time parsing and formatting with comprehensive error handling. All functions are thread-safe when operating on separate xtime_t instances.

Definition in file xtime.h.

Macro Definition Documentation

XTIME_FMT_ISO8601

#define XTIME_FMT_ISO8601   "%Y-%m-%dT%H:%M:%S"

Common time format specifiers

Definition at line 27 of file xtime.h.

Enumeration Type Documentation

xtime_error_t

enum xtime_error_t

Error codes returned by xtime functions

Definition at line 37 of file xtime.h.

Function Documentation

xtime_add_days()

xtime_error_t xtime_add_days	(	xtime_t *	t,
		int64_t	days
	)

Adds a duration in days to the time.

Parameters

t	Pointer to xtime_t to modify.
days	Days to add (can be negative).

Returns

Error code.

Definition at line 584 of file xtime.c.

References xtime_add_seconds().

Referenced by xtime_end_of_month(), xtime_end_of_year(), xtime_start_of_month(), xtime_start_of_week(), and xtime_start_of_year().

Here is the call graph for this function:

Here is the caller graph for this function:

xtime_add_hours()

xtime_error_t xtime_add_hours	(	xtime_t *	t,
		int64_t	hours
	)

Adds a duration in hours to the time.

Parameters

t	Pointer to xtime_t to modify.
hours	Hours to add (can be negative).

Returns

Error code.

Definition at line 576 of file xtime.c.

References xtime_add_seconds().

Here is the call graph for this function:

xtime_add_microseconds()

xtime_error_t xtime_add_microseconds	(	xtime_t *	t,
		int64_t	micros
	)

Adds a duration in microseconds to the time.

Parameters

t	Pointer to xtime_t to modify.
micros	Microseconds to add (can be negative).

Returns

Error code.

Definition at line 552 of file xtime.c.

References xtime_add_nanoseconds().

Here is the call graph for this function:

xtime_add_milliseconds()

xtime_error_t xtime_add_milliseconds	(	xtime_t *	t,
		int64_t	millis
	)

Adds a duration in milliseconds to the time.

Parameters

t	Pointer to xtime_t to modify.
millis	Milliseconds to add (can be negative).

Returns

Error code.

Definition at line 560 of file xtime.c.

References xtime_add_nanoseconds().

Here is the call graph for this function:

xtime_add_minutes()

xtime_error_t xtime_add_minutes	(	xtime_t *	t,
		int64_t	minutes
	)

Adds a duration in minutes to the time.

Parameters

t	Pointer to xtime_t to modify.
minutes	Minutes to add (can be negative).

Returns

Error code.

Definition at line 568 of file xtime.c.

References xtime_add_seconds().

Here is the call graph for this function:

xtime_add_months()

xtime_error_t xtime_add_months	(	xtime_t *	t,
		int	months
	)

Adds months to the time, accounting for varying month lengths. If the resulting date is invalid (e.g., Jan 31 + 1 month = Feb 31), adjusts to the last valid day of that month.

Parameters

t	Pointer to xtime_t to modify.
months	Months to add (can be negative).

Returns

Error code.

Definition at line 592 of file xtime.c.

xtime_add_nanoseconds()

xtime_error_t xtime_add_nanoseconds	(	xtime_t *	t,
		int64_t	nanos
	)

Adds a duration in nanoseconds to the time. Handles overflow into seconds automatically.

Parameters

t	Pointer to xtime_t to modify.
nanos	Nanoseconds to add (can be negative).

Returns

Error code.

Definition at line 529 of file xtime.c.

Referenced by xtime_add_microseconds(), and xtime_add_milliseconds().

Here is the caller graph for this function:

xtime_add_seconds()

xtime_error_t xtime_add_seconds	(	xtime_t *	t,
		int64_t	seconds
	)

Adds seconds to a time value.

Parameters

t	Pointer to xtime_t to modify.
seconds	Number of seconds to add (can be negative).

Returns

XTIME_OK on success, XTIME_ERR_INVALID_ARG if t is null.

Definition at line 461 of file xtime.c.

Referenced by xtime_add_days(), xtime_add_hours(), and xtime_add_minutes().

Here is the caller graph for this function:

xtime_add_years()

xtime_error_t xtime_add_years	(	xtime_t *	t,
		int	years
	)

Adds years to the time, accounting for leap years and month boundaries. If the resulting date is invalid (e.g., Feb 29 in non-leap year), adjusts to the last valid day of that month.

Parameters

t	Pointer to xtime_t to modify.
years	Years to add (can be negative).

Returns

Error code.

Definition at line 651 of file xtime.c.

xtime_compare()

int xtime_compare	(	const xtime_t *	t1,
		const xtime_t *	t2
	)

Compares two time values.

Parameters

t1	First time value.
t2	Second time value.

Returns

-1 if t1 < t2, 0 if t1 == t2, 1 if t1 > t2, or -2 if either pointer is null.

Definition at line 470 of file xtime.c.

xtime_diff()

xtime_error_t xtime_diff	(	const xtime_t *	t1,
		const xtime_t *	t2,
		double *	diff
	)

Calculates difference between two times in seconds.

Parameters

t1	First time value.
t2	Second time value.
diff	Pointer to store difference (t1 - t2) in seconds.

Returns

XTIME_OK on success, XTIME_ERR_INVALID_ARG if any pointer is null.

Definition at line 493 of file xtime.c.

xtime_diff_days()

xtime_error_t xtime_diff_days	(	const xtime_t *	t1,
		const xtime_t *	t2,
		int64_t *	days
	)

Calculates the duration between two times in days. Returns t1 - t2 (positive if t1 is after t2).

Parameters

t1	First time.
t2	Second time.
days	Output: difference in days.

Returns

Error code.

Definition at line 778 of file xtime.c.

xtime_diff_hours()

xtime_error_t xtime_diff_hours	(	const xtime_t *	t1,
		const xtime_t *	t2,
		int64_t *	hours
	)

Calculates the duration between two times in hours. Returns t1 - t2 (positive if t1 is after t2).

Parameters

t1	First time.
t2	Second time.
hours	Output: difference in hours.

Returns

Error code.

Definition at line 768 of file xtime.c.

xtime_diff_micros()

xtime_error_t xtime_diff_micros	(	const xtime_t *	t1,
		const xtime_t *	t2,
		int64_t *	micros
	)

Calculates the duration between two times in microseconds. Returns t1 - t2 (positive if t1 is after t2).

Parameters

t1	First time.
t2	Second time.
micros	Output: difference in microseconds.

Returns

Error code.

Definition at line 716 of file xtime.c.

References xtime_diff_nanos().

Here is the call graph for this function:

xtime_diff_millis()

xtime_error_t xtime_diff_millis	(	const xtime_t *	t1,
		const xtime_t *	t2,
		int64_t *	millis
	)

Calculates the duration between two times in milliseconds. Returns t1 - t2 (positive if t1 is after t2).

Parameters

t1	First time.
t2	Second time.
millis	Output: difference in milliseconds.

Returns

Error code.

Definition at line 732 of file xtime.c.

References xtime_diff_nanos().

Here is the call graph for this function:

xtime_diff_minutes()

xtime_error_t xtime_diff_minutes	(	const xtime_t *	t1,
		const xtime_t *	t2,
		int64_t *	minutes
	)

Calculates the duration between two times in minutes. Returns t1 - t2 (positive if t1 is after t2).

Parameters

t1	First time.
t2	Second time.
minutes	Output: difference in minutes.

Returns

Error code.

Definition at line 758 of file xtime.c.

xtime_diff_nanos()

xtime_error_t xtime_diff_nanos	(	const xtime_t *	t1,
		const xtime_t *	t2,
		int64_t *	nanos
	)

Calculates the duration between two times in nanoseconds. Returns t1 - t2 (positive if t1 is after t2).

Parameters

t1	First time.
t2	Second time.
nanos	Output: difference in nanoseconds.

Returns

Error code.

Definition at line 703 of file xtime.c.

Referenced by xtime_diff_micros(), and xtime_diff_millis().

Here is the caller graph for this function:

xtime_diff_seconds()

xtime_error_t xtime_diff_seconds	(	const xtime_t *	t1,
		const xtime_t *	t2,
		int64_t *	seconds
	)

Calculates the duration between two times in seconds (integer). Returns t1 - t2 (positive if t1 is after t2).

Parameters

t1	First time.
t2	Second time.
seconds	Output: difference in seconds.

Returns

Error code.

Definition at line 748 of file xtime.c.

xtime_end_of_day()

xtime_error_t xtime_end_of_day	(	const xtime_t *	t,
		xtime_t *	result
	)

Returns a new time representing the end of the day (23:59:59.999999999). Does not modify the original time.

Parameters

t	Input time.
result	Output: end of day.

Returns

Error code.

Definition at line 934 of file xtime.c.

References xtime_truncate_to_day().

Here is the call graph for this function:

xtime_end_of_month()

xtime_error_t xtime_end_of_month	(	const xtime_t *	t,
		xtime_t *	result
	)

Returns a new time representing the end of the month (last day, 23:59:59.999999999). Does not modify the original time.

Parameters

t	Input time.
result	Output: end of month.

Returns

Error code.

Definition at line 954 of file xtime.c.

References xtime_add_days(), and xtime_truncate_to_day().

Here is the call graph for this function:

xtime_end_of_year()

xtime_error_t xtime_end_of_year	(	const xtime_t *	t,
		xtime_t *	result
	)

Returns a new time representing the end of the year (Dec 31, 23:59:59.999999999). Does not modify the original time.

Parameters

t	Input time.
result	Output: end of year.

Returns

Error code.

Definition at line 993 of file xtime.c.

References xtime_add_days(), and xtime_truncate_to_day().

Here is the call graph for this function:

xtime_format()

xtime_error_t xtime_format	(	const xtime_t *	t,
		const char *	format,
		char *	buf,
		size_t	buflen
	)

Formats time according to the specified format string. Uses local timezone if time has timezone info, otherwise uses UTC.

Parameters

t	Pointer to xtime_t containing time to format.
format	Format specifier (supports standard strftime formats).
buf	Output buffer for formatted string.
buflen	Size of output buffer.

Returns

XTIME_OK on success, appropriate error code on failure.

Note

Buffer must be large enough to hold formatted string including null terminator.

Thread-safe when operating on different xtime_t instances.

Definition at line 303 of file xtime.c.

xtime_format_utc()

xtime_error_t xtime_format_utc	(	const xtime_t *	t,
		const char *	format,
		char *	buf,
		size_t	buflen
	)

Formats time in UTC regardless of timezone information.

Parameters

t	Pointer to xtime_t containing time to format.
format	Format specifier (supports standard strftime formats).
buf	Output buffer for formatted string.
buflen	Size of output buffer.

Returns

XTIME_OK on success, appropriate error code on failure.

Definition at line 353 of file xtime.c.

xtime_from_unix()

xtime_error_t xtime_from_unix	(	int64_t	timestamp,
		xtime_t *	t
	)

Creates xtime_t from Unix timestamp.

Parameters

timestamp	Unix timestamp (seconds since epoch).
t	Pointer to xtime_t to store result.

Returns

XTIME_OK on success, XTIME_ERR_INVALID_ARG if t is null.

Definition at line 448 of file xtime.c.

xtime_init()

xtime_error_t xtime_init

(

xtime_t *

t

)

Initializes an xtime_t structure to zero.

Parameters

t	Pointer to xtime_t to initialize.

Returns

XTIME_OK on success, XTIME_ERR_INVALID_ARG if t is null.

Definition at line 48 of file xtime.c.

References xtime_init().

Referenced by xtime_init(), and xtime_parse().

Here is the call graph for this function:

Here is the caller graph for this function:

xtime_is_leap_year()

bool xtime_is_leap_year

(

const xtime_t *

t

)

Returns true if the time represents a leap year.

Parameters

t	Pointer to xtime_t.

Returns

true if leap year, false otherwise.

Definition at line 788 of file xtime.c.

xtime_now()

xtime_error_t xtime_now

(

xtime_t *

t

)

Gets current system time with nanosecond precision where available. Automatically captures local timezone offset.

Parameters

t	Pointer to xtime_t to store current time.

Returns

XTIME_OK on success, XTIME_ERR_INVALID_ARG if t is null, XTIME_ERR_SYSTEM on system error.

Definition at line 94 of file xtime.c.

Referenced by xtime_utc_now().

Here is the caller graph for this function:

xtime_parse()

xtime_error_t xtime_parse	(	const char *	str,
		const char *	format,
		xtime_t *	t
	)

Parses a time string according to the specified format. Supports strptime-style format specifiers plus extensions for nanoseconds and timezone.

Parameters

str	The time string to parse.
format	Format specifier (supports standard strptime formats).
t	Pointer to xtime_t to store parsed time.

Returns

XTIME_OK on success, appropriate error code on failure.

Note

Supports common formats automatically. For custom formats, use strptime specifiers.

Thread-safe when operating on different xtime_t instances.

Definition at line 220 of file xtime.c.

References xtime_init().

Here is the call graph for this function:

xtime_start_of_month()

xtime_error_t xtime_start_of_month	(	const xtime_t *	t,
		xtime_t *	result
	)

Returns a new time representing the start of the month (day 1, 00:00:00). Does not modify the original time.

Parameters

t	Input time.
result	Output: start of month.

Returns

Error code.

Definition at line 880 of file xtime.c.

References xtime_add_days(), and xtime_truncate_to_day().

Here is the call graph for this function:

xtime_start_of_week()

xtime_error_t xtime_start_of_week	(	const xtime_t *	t,
		xtime_t *	result
	)

Returns a new time representing the start of the week (Monday 00:00:00). Does not modify the original time.

Parameters

t	Input time.
result	Output: start of week.

Returns

Error code.

Definition at line 852 of file xtime.c.

References xtime_add_days(), and xtime_truncate_to_day().

Here is the call graph for this function:

xtime_start_of_year()

xtime_error_t xtime_start_of_year	(	const xtime_t *	t,
		xtime_t *	result
	)

Returns a new time representing the start of the year (Jan 1, 00:00:00). Does not modify the original time.

Parameters

t	Input time.
result	Output: start of year.

Returns

Error code.

Definition at line 907 of file xtime.c.

References xtime_add_days(), and xtime_truncate_to_day().

Here is the call graph for this function:

xtime_strerror()

const char * xtime_strerror

(

xtime_error_t

err

)

Returns human-readable error message for error code.

Parameters

err	Error code.

Returns

Static error message string.

Definition at line 506 of file xtime.c.

xtime_to_json()

xtime_error_t xtime_to_json	(	const xtime_t *	t,
		char *	buf,
		size_t	buflen
	)

Formats time into a JSON-compatible ISO 8601 string (RFC 3339). Format: "YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ" (or +HH:MM)

Parameters

t	Pointer to xtime_t to convert.
buf	Output buffer.
buflen	Size of output buffer (Recommended: at least 40 chars).

Returns

XTIME_OK on success, appropriate error code on failure.

Definition at line 384 of file xtime.c.

xtime_to_unix()

int64_t xtime_to_unix

(

const xtime_t *

t

)

Converts xtime_t to Unix timestamp (seconds since epoch).

Parameters

t	Pointer to xtime_t to convert.

Returns

Unix timestamp, or -1 if t is null.

Definition at line 441 of file xtime.c.

xtime_truncate_to_day()

xtime_error_t xtime_truncate_to_day

(

xtime_t *

t

)

Rounds time down to the start of the current day (00:00:00.000000000). Preserves timezone information.

Parameters

t	Pointer to xtime_t to modify.

Returns

Error code.

Definition at line 839 of file xtime.c.

Referenced by xtime_end_of_day(), xtime_end_of_month(), xtime_end_of_year(), xtime_start_of_month(), xtime_start_of_week(), and xtime_start_of_year().

Here is the caller graph for this function:

xtime_truncate_to_hour()

xtime_error_t xtime_truncate_to_hour

(

xtime_t *

t

)

Rounds time down to the start of the current hour (XX:00:00.000000000). Preserves timezone information.

Parameters

t	Pointer to xtime_t to modify.

Returns

Error code.

Definition at line 826 of file xtime.c.

xtime_truncate_to_minute()

xtime_error_t xtime_truncate_to_minute

(

xtime_t *

t

)

Rounds time down to the start of the current minute (XX:XX:00.000000000). Preserves timezone information.

Parameters

t	Pointer to xtime_t to modify.

Returns

Error code.

Definition at line 813 of file xtime.c.

xtime_truncate_to_second()

xtime_error_t xtime_truncate_to_second

(

xtime_t *

t

)

Rounds time down to the start of the current second (XX:XX:XX.000000000). Preserves timezone information.

Parameters

t	Pointer to xtime_t to modify.

Returns

Error code.

Definition at line 803 of file xtime.c.

xtime_utc_now()

xtime_error_t xtime_utc_now

(

xtime_t *

t

)

Gets current system time in UTC (no timezone offset).

Parameters

t	Pointer to xtime_t to store current time.

Returns

XTIME_OK on success, XTIME_ERR_INVALID_ARG if t is null, XTIME_ERR_SYSTEM on system error.

Definition at line 150 of file xtime.c.

References xtime_now().

Here is the call graph for this function: