xtime.h

Go to the documentation of this file.

 
#ifndef XTIME_H
#define XTIME_H
 
#include <stdbool.h>  // for bool
#include <stdint.h>   // for int64_t, uint32_t
#include <time.h>     // for struct tm, time_t
 
// Definition for strptime on windows.
#if defined(_MSC_VER)
#include "./win_strptime.h"
#endif
 
#define XTIME_FMT_ISO8601  "%Y-%m-%dT%H:%M:%S"          // 2024-11-28T14:30:00
#define XTIME_FMT_RFC3339  "%Y-%m-%dT%H:%M:%S%z"        // 2024-11-28T14:30:00+00:00
#define XTIME_FMT_RFC2822  "%a, %d %b %Y %H:%M:%S"      // Thu, 28 Nov 2024 14:30:00
#define XTIME_FMT_HTTP     "%a, %d %b %Y %H:%M:%S GMT"  // HTTP date format
#define XTIME_FMT_UNIX     "%s"                         // Unix timestamp
#define XTIME_FMT_DATE     "%Y-%m-%d"                   // 2024-11-28
#define XTIME_FMT_TIME     "%H:%M:%S"                   // 14:30:00
#define XTIME_FMT_DATETIME "%Y-%m-%d %H:%M:%S"          // 2024-11-28 14:30:00
 
typedef enum {
    XTIME_OK = 0,                 // Operation succeeded
    XTIME_ERR_INVALID_ARG,        // Invalid argument (null pointer, invalid format)
    XTIME_ERR_PARSE_FAILED,       // Failed to parse time string
    XTIME_ERR_DATE_OUT_OF_RANGE,  // Failed to parse time string
    XTIME_ERR_BUFFER_TOO_SMALL,   // Output buffer too small
    XTIME_ERR_INVALID_TIME,       // Time value is invalid or out of range
    XTIME_ERR_SYSTEM              // System call failed (check errno)
} xtime_error_t;
 
typedef struct {
    int64_t seconds;       // Seconds since Unix epoch (can be negative for dates before 1970)
    uint32_t nanoseconds;  // Nanoseconds component [0, 999999999]
    int16_t tz_offset;     // Timezone offset in minutes from UTC [-1439, 1439]
    bool has_tz;           // Whether timezone information is present
} xtime_t;
 
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);
 
// ============== math calculation helpers =======================
//================================================================
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);
 
#endif  // XTIME_H