/*
 * dynstr.h - dynamic C string library
 *
 * This is a library for managing dynamic C strings of bytes (not
 * multibyte characters).
 *
 * Each dynamic string is immutable: once created, it cannot be modified.
 * To achieve changes, create new strings. This allows an implementation
 * of the API to make use of copy-on-write techniques to save memory,
 * and avoid unnecessary copying.
 *
 * Dynamic allocation can fail. By default, the routines in this library
 * return NULL for failures. The caller may use the 
 * dynstr_set_malloc_error_handler function to set a function that gets
 * called before NULL is returned. This function can, for example, abort
 * the program (see dynstr_malloc_error_abort), or use longjmp to jump
 * some error handling routine.
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef DYNSTR_H
#define DYNSTR_H

#include <stdarg.h>
#include <stdbool.h>
#include <stdio.h>
#include <stddef.h>
#include <unistd.h>


/* Version number of the shared library. */
#define DYNSTR_VERSION_MAJOR 0
#define DYNSTR_VERSION_MINOR 0
#define DYNSTR_VERSION_PATCH 0


/* Magic value returned by functions that search for things within
 * dynamic strings, to indicate 'not found'. */
#define DYNSTR_NOT_FOUND (~(size_t)0)


/* The abstract type for dynamic strings. The type is opaque: the caller
 * may only operate on it using the functions declared in this header. */
typedef struct Dynstr Dynstr;


/* Initialize or re-initialize the library. This sets all global variables
 * used internally to their defaults. This is mainly useful for unit
 * tests. */
void dynstr_init(void);

/* Set the memory allocator to use, instead of malloc. This is mainly
 * useful for unit tests. */
void dynstr_set_malloc(void *(*allocator)(size_t));

/* Get the memory allocator being used. This is mainly useful for unit 
 * tests. */
void *(*dynstr_get_malloc(void))(size_t);

/* Type of callback functions for handling malloc failures. */
typedef void dynstr_error_handler(int error, size_t size, void *oldptr);

/* Get and set malloc error handler. */
dynstr_error_handler *dynstr_get_malloc_error_handler(void);
void dynstr_set_malloc_error_handler(dynstr_error_handler *handler);

/* Malloc error handler that aborts the program (using abort, not exit). */
void dynstr_malloc_error_abort(int error, size_t size, void *oldptr);

/* Malloc error handler that does nothing. This is the default handler.
 * It causes NULL to be returned. */
void dynstr_malloc_error_indicate(int error, size_t size, void *oldptr);


/* Create a new, empty string. */
Dynstr *dynstr_new_empty(void);

/* Create a new string, copy contents from a NUL-terminated C string. */
Dynstr *dynstr_new_from_cstring(const char *cstring);

/* Create a new string, copy contents from an arbitrary memory area. */
Dynstr *dynstr_new_from_memory(const void *mem, size_t size);

/* Create a new string, use contents from a constant C string. The caller
 * MUST make sure the contents of the C string do not change while the
 * dynamic string exists, since the dynamic string will not copy the
 * contents, but use it directly. */
Dynstr *dynstr_new_from_constant_cstring(const char *cstring);

/* Create a new string, use contents from an arbitrary memory area. The caller
 * MUST make sure the contents of the memory area do not change while the
 * dynamic string exists, since the dynamic string will not copy the
 * contents, but use it directly. */
Dynstr *dynstr_new_from_constant_memory(const void *mem, size_t size);

/* Free a dynamic string. */
void dynstr_free(Dynstr *dynstr);

/* Return length of dynamic string, in bytes. */
size_t dynstr_len(Dynstr *dynstr);

/* Is the dynamic string empty? In other words, is its length 0? */
bool dynstr_is_empty(Dynstr *dynstr);

/* Create a new string, copying its contents from an existing one. */
Dynstr *dynstr_substr(Dynstr *dynstr, size_t offset, size_t size);

/* Create a new string by catenating two existing ones. Return NULL on
 * failure. */
Dynstr *dynstr_cat(Dynstr *dynstr1, Dynstr *dynstr2);

/* Create a new string by catenating zero or more existing ones. The
 * argument list has zero or more pointers to dynamic strings, and
 * then a NULL pointer. */
Dynstr *dynstr_cat_many(Dynstr *dynstr, ...);

/* Return value of byte at a given offset. The value is non-negative. If
 * the offset is past the end of the string, -1 is returned. */
int dynstr_byte_at(Dynstr *dynstr, size_t offset);

/* Copy contents of a dynamic string into a memory area. If the offset or 
 * size extends past the end of the string, only as much as actually exists 
 * in the string is actually copied. The rest of the output memory area will 
 * be filled with garbage. Return number of bytes actually copied, which may 
 * be less than requested, and may be zero. */
size_t dynstr_memcpy(void *mem, Dynstr *dynstr, size_t offset, size_t size);

/* Create a dynamically allocated C string copy of the dynamic string.
 * This is like strdup. If the dynamic string contains NUL bytes, then
 * that is the caller's problem. Return pointer to the C string. The
 * caller is responsible for freeing it. Return NULL on error. */
char *dynstr_strdup(Dynstr *dynstr);

/* Search for first or last byte with a given value in a string, 
 * starting at a given offset and until the end of the string. Return offset 
 * of matching byte, or DYNSTR_NOT_FOUND if not found. Offset is from 
 * beginning of string. */
size_t dynstr_first_byte(Dynstr *dynstr, size_t offset, int byte);
size_t dynstr_last_byte(Dynstr *dynstr, size_t offset, int byte);

/* Search for first or last occurrence of a substring in a string, 
 * starting at a given offset and until the end of the string. Return 
 * offset of match, or DYNSTR_NOT_FOUND if not found. Offset is from 
 * beginning of string. */
size_t dynstr_first_string(Dynstr *dynstr, size_t offset, Dynstr *pattern);
size_t dynstr_last_string(Dynstr *dynstr, size_t offset, Dynstr *pattern);

/* Compare two strings, return 0 if they are equal, negative if the
 * first comes before the second, and positive if second comes first.
 * Comparisons are done byte-by-byte using unsigned values. */
int dynstr_cmp(Dynstr *dynstr1, Dynstr *dynstr2);

/* Write a dynamic string into an open file (using stdio). Return value is 
 * number of bytes written, just like for fwrite(3).
 * If an error occurs, the size is less than the length of the string,
 * and errno has been set by fwrite(3). */
size_t dynstr_fwrite(FILE *file, Dynstr *dynstr);

/* Write a dynamic string into an open Unix file handle. Return value is 
 * number of bytes written, or -1. */
ssize_t dynstr_write(int file, Dynstr *dynstr);

/* Read a number of bytes from an open file, either FILE or a Unix file
 * handle. Return value is the string that was read. The string is empty
 * to indicate EOF, or NULL for error. */
Dynstr *dynstr_fread(FILE *file, size_t size);
Dynstr *dynstr_read(int file, size_t size);

/* Read a line from an open file, either a FILE or a Unix file handle.
 * The line ends with the first newline byte, or at the end of the file.
 * If there was an error, NULL is returned, and errno is set, and the
 * partially read line is discarded. */
Dynstr *dynstr_freadline(FILE *file);
Dynstr *dynstr_readline(int file);

#endif