The vaqt package offers data types and functions for handling time and duration in C, with nanosecond precision. Works with C99 (C11 is recommended on Windows for higher precision).

Concepts • Features • Getting started • Building from source • API reference

The package works with two types of values: Time and Duration.

Time is a pair (seconds, nanoseconds), where seconds is the 64-bit number of seconds since zero time (0001-01-01 00:00:00 UTC) and nanoseconds is the number of nanoseconds within the current second (0-999999999). Time can represent dates billions of years in the past or future with nanosecond precision.

  since     within
  0-time    second
┌─────────┬─────────────┐
│ seconds │ nanoseconds │
└─────────┴─────────────┘
  64 bit    32 bit

Time is always operated in UTC, but you can convert it from/to a specific timezone.

Duration is a 64-bit number of nanoseconds. It can represent values up to about 290 years.

┌─────────────┐
│ nanoseconds │
└─────────────┘
  64 bit

The package provides functions for common date and time operations.

Creating time values:

time_now()
time_date(year, month, day, hour, min, sec, nsec, offset_sec)

Extracting time fields:

time_get_year(t)
time_get_month(t)
time_get_day(t)
time_get_clock(t)
time_get_hour(t)
time_get_minute(t)
time_get_second(t)
time_get_nano(t)
time_get_weekday(t)
time_get_yearday(t)
time_get_isoweek(t)

Unix time:

time_unix(sec, nsec)
time_unix_milli(msec)
time_unix_micro(usec)
time_unix_nano(nsec)
time_to_unix(t)
time_to_unix_milli(t)
time_to_unix_micro(t)
time_to_unix_nano(t)

Calendar time:

time_tm(tm, offset_sec)
time_to_tm(t, offset_sec)

Time comparison:

time_after(t, u)
time_before(t, u)
time_compare(t, u)
time_equal(t, u)
time_is_zero(t)

Time arithmetic:

time_add(t, d)
time_add_date(t, years, months, days)
time_sub(t, u)
time_since(t)
time_until(t)

Rounding:

time_truncate(t, d)
time_round(t, d)

Formatting:

time_fmt_iso(t, offset_sec)
time_fmt_datetime(t, offset_sec)
time_fmt_date(t, offset_sec)
time_fmt_time(t, offset_sec)
time_parse(s)

Marshaling:

time_unmarshal_binary(b);
time_marshal_binary(t)

Check the API reference for more details.

To use vaqt in your C project:

1. Copy the src/vaqt.h header file and the source files (src/*.c) into your project's vaqt source folder.

2. Include the header in your source files:

#include "vaqt/vaqt.h"

3. Use the types and functions as described in the documentation.

4. Compile your project along with the vaqt source files. For example:

gcc main.c vaqt/*.c -o main -lm

Build and test the package:

make test-all

Run examples:

make run-example

Contributions are welcome. For anything other than bug fixes, please open an issue first to discuss what you want to change.

Make sure to add or update tests as needed.

Created by Anton Zhiyanov.

Based on Go's stdlib time package, available under the BSD 3-Clause License.