#ifndef STRHELP_H
#define STRHELP_H

#include <stdbool.h>

/**
 * @file  strhelp.h
 * @brief Helper functions for c strings and memory management
 * @details strhelp contains terminating memory allocation functions and
 * some conveniance functions to work with c strings or arrays of c
 * strings.
 */

void *xmalloc( size_t n );
void *xrealloc( void *a, size_t n );
void *xcalloc( size_t n, size_t m );
char *xstrndup( const char *string, const size_t len );

/**
 * @brief Returns the length of the given %NULL-terminated
 * string array str_array.
 * @param[in] str_array a %NULL-terminated array of strings
 * @returns length of str_array.
 */
unsigned int strv_length (char **str_array);

/**
 * @brief append a string to a NULL terminated array of strings.
 *
 * @param[inout] pArray pointer to the NULL terminated list of string pointers.
 * @param[in] string pointer to the string to append to the list.
 * @param[in] len length of the string to append to the list
 */
void strv_append (char ***pArray, const char *string, const size_t len);

/**
 * @brief append a string to another string.
 *
 * @param[inout] pDst pointer to the string to be extended.
 * @param[inout] dst_len length of the dst string. Will be modified.
 * @param[in] appendage pointer to the string to append.
 * @param[in] len length of the string to append.
 */
void str_append_str (char **pDst, size_t *dst_len, const char *appendage,
                    const size_t len);

/**
 * @brief Frees the given %NULL-terminated string array.
 * @param[inout] str_array a %NULL-terminated array of strings
 */
void strv_free (char **str_array);

/**
 * @brief Checks whether two strings exactly match
 * @param[in] s1 the first string
 * @param[in] s2 the second string
 * @returns true if s1 and s2 are equal
 */
bool str_equal (char *s1, char *s2);

/**
 * @brief Checks whether s2 exactly matches the beginning of s1.
 * @param[in] s1 the string who's beginning is searched
 * @param[in] s2 the string which is searched for
 * @returns true if s1 starts with s2, false otherwise
 */
bool str_starts_with (char *s1, char *s2);

/**
 * @brief Trims all white space from the start and end of string.
 * @details the start of the string is trimmed by setting *s to the
 * first non white space character.  The end is trimmed by setting the
 * first character after the last non white space character to \0.
 * @param[inout] s ponter to the string to strip
 */
bool str_trim (char **s);

#endif