#include <stddef.h>

#ifndef UC_STRVEC_H_
#define UC_STRVEC_H_

#ifdef __cplusplus
extern "C" {
#endif
/** A Vector of strings.*/
struct UCStrv
{
    /** number of strings */
    size_t cnt;
    /** allocated room in strings (internal use) */
    size_t allocated;
    /** Array of strings */
    char **strings;
};

/** Initialize a UCStrv
 *
 * @param strv 
 */
void uc_strv_init(struct UCStrv *strv);

/** static initializer. Use as: struct UCStrv foo = UC_STRV_INITIALIZER;
*/
#define UC_STRV_INITIALIZER {0, 0, NULL}

/**
 * Grow the UCStrv so it can hold n more items
 *
 * @param strv UCStrv to grow
 * @param cnt expand strvec to hold this cnt more items
 * @return 0 on success, otherwise failure
 **/ 
int uc_strv_grow(struct UCStrv *strv, size_t cnt);

/**
 * Expand the UCStrv to hold 1 more item
 *
 * @param strv UCStrv to expand
 * @return 0 on success, otherwise failure
 **/ 
int uc_strv_expand(struct UCStrv *strv);

/**
 * Append a string to the UCStrv, the string will be copied in
 *
 * @param strv UCStrv to append to
 * @param str String to append, the string will be copied.
 * @return 0 on success, otherwise failure
 **/ 
int uc_strv_append(struct UCStrv *strv, const char *str);

/**
 * Append a string to the strvec, nocopy variang.  
 * The string shold be dynamically allocated, as 
 * destroying the UCStrv will free() all items.
 *
 * @param strv UCStrv to add to
 * @param str the string to append
 * @return 0 on success, otherwise failure
 **/ 
int uc_strv_append_nocopy(struct UCStrv *strv, char *str);

/**
 * Append a NULL pointer to the UCStrv, (cnt is not increased,
 * so another _appended item will overwrite this NULL terminator)
 *
 * @param strv UCStrv to append to
 * @return 0 on success, otherwise failure
 **/ 
int uc_strv_null_terminate(struct UCStrv *strv);

/**
 * free all strings in this UCStrv, cnt will be 0 after this
 * @param strv UCStrv to clear
 */
void uc_strv_clear(struct UCStrv *strv);

/**
 * free all elements as well as the underlying array, the UCStrv is
 * unusable after this call
 *
 * @param strv UCStrv to destroy
 */
void uc_strv_destroy(struct UCStrv *strv);

#ifdef __cplusplus
}
#endif

#endif