diff options
Diffstat (limited to 'lib/dynstr.h')
-rw-r--r-- | lib/dynstr.h | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/lib/dynstr.h b/lib/dynstr.h new file mode 100644 index 0000000..302902d --- /dev/null +++ b/lib/dynstr.h @@ -0,0 +1,187 @@ +/* + * 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> + + +/* 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 |