1 files changed, 43 insertions, 0 deletions
diff --git a/sternenblog/timeutil.h b/sternenblog/timeutil.h
new file mode 100644
index 0000000..7d0270e
--- /dev/null
+++ b/sternenblog/timeutil.h
@@ -0,0 +1,43 @@
+/*!
+ * @file
+ * @brief Utilities for rendering timestamps as strings
+ */
+enum time_format {
+    RSS_TIME_FORMAT,          //!< RFC822 formatted time with 4 instead of 2 year digits
+    ATOM_TIME_FORMAT,         //!< RFC3339 formatted time
+    HTML_TIME_FORMAT_READABLE //!< like `ATOM_TIME_FORMAT`, but with space between date and time
+};
+
+/*!
+ * @brief Maximum size necessary to contain the output of flocaltime()
+ */
+#define MAX_TIMESTR_SIZE 32
+// max HTML/Atom: 24 + NUL byte
+// max RSS:       31 + NUL byte
+
+/*!
+ * @brief Format given timestamp as a string in the local timezone
+ *
+ * flocaltime() is a wrapper around `strftime()` which supports
+ * a specific set of output formats. In contrast to `strftime()`
+ * it can output correct RFC3339 time strings and does localtime
+ * resolution for you.
+ *
+ * Example usage to print a RFC3339 formatted timestamp:
+ *
+ * ```
+ * time_t some_time;
+ * char strtime[MAX_TIMESTR_SIZE];
+ *
+ * if(flocaltime(strtime, ATOM_TIME_FORMAT, MAX_TIMESTR_SIZE, &some_time) > 0) {
+ *   puts(strtime);
+ * }
+ * ```
+ *
+ * @param b output buffer
+ * @param type time format to use for output
+ * @param size number of `char`s the buffer can hold
+ * @param time pointer to timestamp
+ * @return `0` on error, otherwise length of the string placed in `b` excluding terminating `NUL` byte
+ */
+size_t flocaltime(char *b, enum time_format type, size_t size, const time_t *time);