1 files changed, 125 insertions, 0 deletions
diff --git a/doc/time_functions.rst b/doc/time_functions.rst
new file mode 100644
index 0000000..d9a57a1
--- /dev/null
+++ b/doc/time_functions.rst
@@ -0,0 +1,125 @@
+==============
+Time functions
+==============
+
+Time in POSIX systems is represented in ``struct timespec``. This structure is
+composed of two members: one integer for the number of full seconds in the time
+value, and one integer for the number of nanoseconds that remain when
+subtracting the full seconds from the time value. POSIX leaves it unspecified
+how negative time is to be represented with this structure, so I have devised
+an algebra for use with the same struct that gives negative time support.
+
+Since integers often cannot store negative zero (due to e.g. use of 2s
+complements in the language implementation), we will store the minus sign in
+the nanosecond member if the integral second part is zero. This gives us the
+property that we can test for negative time by looking for whether at least one
+member of the structure is negative. Also, we want to avoid storing the minus
+in both members to somewhat aid the pretty-printing construct often seen,
+
+.. code-block:: c
+
+	printf("%ld.%09ld\n", (long)ts.tv_sec, ts.tv_nsec);
+
+The number of combinations of a (non-zero) negative number, zero and a
+(non-zero) positive number is small, so we can actually just exhaustively list
+them all.
+
++----------------+------------+
+| Representation | Time value |
++================+============+
+| {-1, -1}       |  illegal   |
++----------------+------------+
+| {-1,  0}       |   -1.0 s   |
++----------------+------------+
+| {-1,  1}       |   -1.1 s   |
++----------------+------------+
+| { 0, -1}       |   -0.1 s   |
++----------------+------------+
+| { 0,  0}       |    0.0 s   |
++----------------+------------+
+| { 0,  1}       |    0.1 s   |
++----------------+------------+
+| { 1, -1}       |  illegal   |
++----------------+------------+
+| { 1,  0}       |    1.0 s   |
++----------------+------------+
+| { 1,  1}       |    1.1 s   |
++----------------+------------+
+
+Function list
+=============
+
+.. code-block:: c
+
+	#include <libHX/misc.h>
+
+	bool HX_timespec_isneg(const struct timespec *p);
+
+	struct timespec *HX_timespec_neg(struct timespec *result,
+		const struct timespec *p);
+
+	struct timespec *HX_timespec_add(struct timespec *result,
+		const struct timespec *p, const struct timespec *q);
+
+	struct timespec *HX_timespec_sub(struct timespec *delta,
+		const struct timespec *p, const struct timespec *q);
+
+	struct timespec *HX_timespec_mul(struct timespec *delta,
+		const struct timespec *p, int f);
+
+	struct timespec *HX_timespec_mulf(struct timespec *delta,
+		const struct timespec *p, double f);
+
+	struct timeval *HX_timeval_sub(struct timeval *delta,
+		const struct timeval *p, const struct timeval *q);
+
+	int HX_time_compare(const struct stat *a, const struct stat *b,
+		int mode);
+
+``HX_timespec_isneg``
+	Determines whether a timespec structure represents (non-zero) negative
+	time.
+
+``HX_timespec_neg``
+	Computes the negation of the time specified by ``p``. ``result`` and
+	``p`` may point to the same structure.
+
+``HX_timespec_add``
+	Calculates the sum of the two times specified by ``p`` and ``q``, which
+	are of type ``struct timespec``. Any and all of ``result``, ``p`` and
+	``q`` may point to the same structure.
+
+``HX_timespec_sub``
+	Calculates the difference between the two timepoints ``p`` and ``q``,
+	which are of type ``struct timespec`` (nanosecond granularity).
+
+``HX_timespec_mul``
+	Multiplies the time quantum in ``p`` by ``f``.
+
+``HX_timespec_mulf``
+	Multiplies the time quantum in ``p`` by ``f``.
+
+``HX_timeval_sub``
+	Calculates the difference between the two timepoints ``p`` and ``q``,
+	which are of type ``struct timeval`` (microsecnod granularity).
+
+``HX_time_compare``
+	Compares the timestamps from two struct stats. ``mode`` indicates which
+	field is compared, which can either be ``'a'`` for the access time,
+	``'c'`` for the inode change time, ``'m'`` for the modification time,
+	or ``'o'`` for the creation time (where available). Returns a negative
+	number if the time in ``a`` is less than ``b``, zero when they are
+	equal, or a positive number greater than zero if ``a`` is greater than
+	``b``.
+
+The macros ``HX_TIMESPEC_FMT`` and ``HX_TIMESPEC_EXP`` can be used for passing
+and printing a ``struct timespec`` using the ``*printf`` function family:
+
+.. code-block:: c
+
+	struct timespec p;
+	clock_gettime(CLOCK_MONOTONIC, &p);
+	printf("Now: " HX_TIMESPEC_FMT, HX_TIMESPEC_EXP(&p));
+
+Similarly, ``HX_TIMEVAL_FMT`` and ``HX_TIMEVAL_EXP`` exist for the older
+``struct timeval``.