/*
 * util.h -- miscellaneous utilities
 *
 * Copyright (c) 2021-2022 David Demelier <markand@malikania.fr>
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

/**
 * \file util.h
 * \brief Miscellaneous utilities.
 *
 * Most of the allocations functions will exit with code 1 on memory
 * exhaustion.
 */

#ifndef SCI_UTIL_H
#define SCI_UTIL_H

#include <stddef.h>
#include <stdio.h>

#include <jansson.h>

/**
 * Compute fixed size array length.
 */
#define UTIL_SIZE(x) (sizeof (x) / sizeof (x[0]))

/**
 * Wrap malloc or exit with code 1.
 *
 * \param w the bytes to allocate
 * \return the pointer to the memory
 */
void *
util_malloc(size_t w);

/**
 * Wrap calloc or exit with code 1.
 *
 * \param n the number of items
 * \param w the bytes per item
 * \return the pointer to the memory
 */
void *
util_calloc(size_t n, size_t w);

/**
 * Wrap realloc or exit with code 1.
 *
 * \param ptr the old memory
 * \param w the bytes to allocate
 * \return the pointer to the memory
 */
void *
util_realloc(void *ptr, size_t w);

/**
 * Wrap reallocarray or exit with code 1.
 *
 * \param ptr the old memory
 * \param n the number of items
 * \param w the bytes per item
 * \return the pointer to the memory
 */
void *
util_reallocarray(void *ptr, size_t n, size_t w);

/**
 * Wrap strdup or exit with code 1.
 *
 * \pre str != NULL
 * \param str the string to duplicate
 * \return the copied string
 */
char *
util_strdup(const char *str);

/**
 * Wrap strndup or exit with code 1.
 *
 * \pre str != NULL
 * \param str the string to duplicate
 * \param n the maximum string to not exceed
 * \return the copied string
 */
char *
util_strndup(const char *str, size_t n);

/**
 * Get the base name component from a path.
 *
 * \pre path != NULL
 * \param path the path to extract
 * \return a static thread local value containing the base name
 */
char *
util_basename(const char *path);

/**
 * Get the directory name component from a path.
 *
 * \pre path != NULL
 * \param path the path to extract
 * \return a static thread local value containing the directory name
 */
char *
util_dirname(const char *path);

/**
 * Wrap open_memstream or exit with code 1.
 *
 * \pre out != NULL
 * \pre outsz != NULL
 * \param out the destination string
 * \param outsz the destination string length
 * \return a non-NULL file pointer
 */
FILE *
util_open_memstream(char **out, size_t *outsz);

/**
 * Read the whole content from the given file.
 *
 * \pre path != NULL
 * \param path the file to read
 * \return the file content or NULL on error (and errno is set)
 */
char *
util_read(const char *);

/**
 * Write an error message to error output and exit with code 1.
 *
 * \pre fmt != NULL
 * \param fmt the format string
 */
void
util_die(const char *fmt, ...);

/**
 * Wrap json_pack or exit with code 1.
 *
 * \pre fmt != NULL
 * \param fmt the json_pack format string and its arguments
 * \return a non-NULL JSON document
 */
json_t *
util_json_pack(const char *fmt, ...);

/**
 * Wrap json_dump or exit with code 1.
 *
 * \pre json != NULL
 * \param json the JSON value to transform to string
 */
char *
util_json_dump(const json_t *json);

/**
 * OpenBSD strlcpy extension builtin.
 *
 * \pre dst != NULL
 * \pre src != NULL
 * \param dst the destination string
 * \param src the source string
 * \param size the maximum size in dst
 * \return the number of bytes written
 */
size_t
util_strlcpy(char *dst, const char *src, size_t size);

/**
 * OpenBSD strtonum extension builtin.
 *
 * \pre str != NULL
 * \param str the string to convert
 * \param min the lower bound (included)
 * \param max the upper bound (included)
 * \param errstr the error string pointer to be set on error (not dynamically allocated)
 * \return the converted value
 */
long long
util_strtonum(const char *str, long long min, long long max, const char **errstr);

/**
 * Wrap getopt(3) but handle invalid option or missing value with a predefined
 * message.
 *
 * \param argc number of arguments
 * \param argv arguments
 * \param optstring the string format
 * \return option or -1 when complete
 */
int
util_getopt(int argc, char * const *argv, const char *optstring);

#endif /* !SCI_UTIL_H */