1 files changed, 143 insertions, 0 deletions
diff --git a/include/hybbx/util.h b/include/hybbx/util.h
new file mode 100644
index 0000000..de439b4
--- /dev/null
+++ b/include/hybbx/util.h
@@ -0,0 +1,143 @@
+#ifndef HYBBX_UTIL_H
+#define HYBBX_UTIL_H
+
+#include "hybbx/types.h"
+
+#include <stddef.h>
+#include <time.h>
+
+struct tm;
+
+struct hybbx_config;
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Safe string copy (always NUL-terminates when @p dst_size > 0).
+ * Returns bytes copied excluding the terminator.
+ */
+size_t hybbx_strlcpy(char *dst, const char *src, size_t dst_size);
+
+/**
+ * Join @p base and @p name into @p out with a single '/'.
+ * Rejects empty components and path traversal ("..").
+ */
+hybbx_result_t hybbx_path_join(char *out, size_t out_len,
+                               const char *base, const char *name);
+
+/** Default relative storage path (@ref HYBBX_DIR_DATA). */
+hybbx_result_t hybbx_default_user_data_path(char *out, size_t out_len);
+
+/**
+ * Expand a config path: `~` → $HOME, `~/foo` → $HOME/foo.
+ * Empty or NULL @p path → @ref HYBBX_DIR_DATA. Other paths copied unchanged.
+ */
+hybbx_result_t hybbx_path_expand(char *out, size_t out_len, const char *path);
+
+/** Set the HyBBX install root used by @ref hybbx_path_resolve. */
+void hybbx_install_root_set(const char *root);
+
+/** Install root set by @ref hybbx_install_root_set, or NULL when unset. */
+const char *hybbx_install_root_get(void);
+
+/**
+ * Resolve a config path: @ref hybbx_path_expand, then prefix relative paths
+ * with the install root when set.
+ */
+hybbx_result_t hybbx_path_resolve(char *out, size_t out_len, const char *path);
+
+/** Parent directory of @p path (POSIX `/` rules). */
+hybbx_result_t hybbx_path_dirname(const char *path, char *out, size_t out_len);
+
+/**
+ * Host operating system name for display (e.g. Linux, FreeBSD, MacOS, Windows).
+ * Does not include OS version or kernel release.
+ */
+hybbx_result_t hybbx_platform_os_name(char *out, size_t out_len);
+
+/** Return non-zero when @p len is safe for HyBBX allocations. */
+int hybbx_size_ok(size_t len);
+
+/**
+ * HyBBX boolean configuration standard.
+ * Canonical written form: @c yes / @c no (see @ref HYBBX_BOOL_YES / @ref HYBBX_BOOL_NO).
+ * Accepted true:  yes, true, enable, enabled, on, 1
+ * Accepted false: no, false, disable, disabled, off, 0
+ * Matching is case-insensitive.
+ */
+#define HYBBX_BOOL_YES "yes"
+#define HYBBX_BOOL_NO  "no"
+
+/** Return non-zero when @p value is a recognized true token. */
+int hybbx_bool_is_true(const char *value);
+
+/** Return non-zero when @p value is a recognized false token. */
+int hybbx_bool_is_false(const char *value);
+
+/**
+ * Parse a boolean string. Returns 1 or 0 when recognized; otherwise
+ * returns @p default_value (also used when @p value is NULL or empty).
+ */
+int hybbx_parse_bool(const char *value, int default_value);
+
+/** Canonical @c yes / @c no string for a boolean value. */
+const char *hybbx_bool_to_string(int value);
+
+/** Short name for @p rc (logging / tests). */
+const char *hybbx_result_name(hybbx_result_t rc);
+
+/**
+ * HyBBX system-local date/time formatting for logs and text/ tokens.
+ * Default: 24-hour clock with seconds, ISO date YYYY/MM/DD.
+ */
+typedef enum hybbx_date_format {
+    HYBBX_DATE_ISO = 0,
+    HYBBX_DATE_ISO_SHORT = 1,
+    HYBBX_DATE_US = 2,
+    HYBBX_DATE_EU = 3,
+} hybbx_date_format_t;
+
+typedef struct hybbx_time_format {
+    int clock_12h;
+    int seconds;
+    hybbx_date_format_t date_format;
+} hybbx_time_format_t;
+
+void hybbx_time_format_defaults(hybbx_time_format_t *fmt);
+const hybbx_time_format_t *hybbx_time_format_get(void);
+void hybbx_time_config_apply(const struct hybbx_config *config);
+
+/** Local wall-clock time for text tokens and stamps. */
+hybbx_result_t hybbx_time_local_now(struct tm *out);
+
+const char *hybbx_date_format_name(hybbx_date_format_t fmt);
+
+/**
+ * Format @p tm as clock time (default @c HH:MM:SS, 12h when configured).
+ */
+hybbx_result_t hybbx_time_format_time(char *out, size_t out_len,
+                                      const struct tm *tm,
+                                      const hybbx_time_format_t *fmt);
+
+/**
+ * Format @p tm as calendar date (default @c YYYY/MM/DD).
+ */
+hybbx_result_t hybbx_time_format_date(char *out, size_t out_len,
+                                      const struct tm *tm,
+                                      const hybbx_time_format_t *fmt);
+
+/**
+ * Format @p tm as @c yyyymmdd HH:MM per @p fmt (compact log stamp).
+ * @return HYBBX_OK on success.
+ */
+hybbx_result_t hybbx_time_format_stamp(char *out, size_t out_len,
+                                       const struct tm *tm,
+                                       const hybbx_time_format_t *fmt);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* HYBBX_UTIL_H */