#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 */