buffer.h in escape_utils-0.3.0

- old
+ new
@@ -1,91 +1,113 @@
 /*
- * Copyright (c) 2008, Natacha Porté
- * Copyright (c) 2011, Vicent Martí
+ * Copyright (C) the libgit2 contributors. All rights reserved.
  *
- * Permission to use, copy, modify, and 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.
+ * This file is part of libgit2, distributed under the GNU GPL v2 with
+ * a Linking Exception. For full terms see the included COPYING file.
  */
+#ifndef INCLUDE_buffer_h__
+#define INCLUDE_buffer_h__
 
-#ifndef __GEN_BUFFER_H__
-#define __GEN_BUFFER_H__
-
+#include <stdbool.h>
 #include <stddef.h>
 #include <stdarg.h>
+#include <sys/types.h>
 #include <stdint.h>
 
-#if defined(_MSC_VER)
-#define __attribute__(x)
-#define inline
-#endif
+typedef struct {
+	char *ptr;
+	size_t asize, size;
+} gh_buf;
 
-typedef enum {
-	BUF_OK = 0,
-	BUF_ENOMEM = -1,
-} buferror_t;
+extern char gh_buf__initbuf[];
+extern char gh_buf__oom[];
 
-/* struct buf: character array buffer */
-struct buf {
-	uint8_t *data;		/* actual character data */
-	size_t size;	/* size of the string */
-	size_t asize;	/* allocated size (0 = volatile buffer) */
-	size_t unit;	/* reallocation unit size (0 = read-only buffer) */
-};
+#define GH_BUF_INIT { gh_buf__initbuf, 0, 0 }
 
-/* CONST_BUF: global buffer from a string litteral */
-#define BUF_STATIC(string) \
-	{ (uint8_t *)string, sizeof string -1, sizeof string, 0, 0 }
+/**
+ * Initialize a gh_buf structure.
+ *
+ * For the cases where GH_BUF_INIT cannot be used to do static
+ * initialization.
+ */
+extern void gh_buf_init(gh_buf *buf, size_t initial_size);
 
-/* VOLATILE_BUF: macro for creating a volatile buffer on the stack */
-#define BUF_VOLATILE(strname) \
-	{ (uint8_t *)strname, strlen(strname), 0, 0, 0 }
+/**
+ * Attempt to grow the buffer to hold at least `target_size` bytes.
+ *
+ * If the allocation fails, this will return an error.  If mark_oom is true,
+ * this will mark the buffer as invalid for future operations; if false,
+ * existing buffer content will be preserved, but calling code must handle
+ * that buffer was not expanded.
+ */
+extern int gh_buf_try_grow(gh_buf *buf, size_t target_size, bool mark_oom);
 
-/* BUFPUTSL: optimized bufputs of a string litteral */
-#define BUFPUTSL(output, literal) \
-	bufput(output, literal, sizeof literal - 1)
+/**
+ * Grow the buffer to hold at least `target_size` bytes.
+ *
+ * If the allocation fails, this will return an error and the buffer will be
+ * marked as invalid for future operations, invaliding contents.
+ *
+ * @return 0 on success or -1 on failure
+ */
+static inline int gh_buf_grow(gh_buf *buf, size_t target_size)
+{
+	return gh_buf_try_grow(buf, target_size, true);
+}
 
-/* bufgrow: increasing the allocated size to the given value */
-int bufgrow(struct buf *, size_t);
+extern void gh_buf_free(gh_buf *buf);
+extern void gh_buf_swap(gh_buf *buf_a, gh_buf *buf_b);
 
-/* bufnew: allocation of a new buffer */
-struct buf *bufnew(size_t) __attribute__ ((malloc));
+/**
+ * Test if there have been any reallocation failures with this gh_buf.
+ *
+ * Any function that writes to a gh_buf can fail due to memory allocation
+ * issues.  If one fails, the gh_buf will be marked with an OOM error and
+ * further calls to modify the buffer will fail.  Check gh_buf_oom() at the
+ * end of your sequence and it will be true if you ran out of memory at any
+ * point with that buffer.
+ *
+ * @return false if no error, true if allocation error
+ */
+static inline bool gh_buf_oom(const gh_buf *buf)
+{
+	return (buf->ptr == gh_buf__oom);
+}
 
-/* bufnullterm: NUL-termination of the string array (making a C-string) */
-const char *bufcstr(struct buf *);
 
-/* bufprefix: compare the beginning of a buffer with a string */
-int bufprefix(const struct buf *buf, const char *prefix);
+static inline size_t gh_buf_len(const gh_buf *buf)
+{
+	return buf->size;
+}
 
-/* bufput: appends raw data to a buffer */
-void bufput(struct buf *, const void *, size_t);
+extern int gh_buf_cmp(const gh_buf *a, const gh_buf *b);
 
-/* bufputs: appends a NUL-terminated string to a buffer */
-void bufputs(struct buf *, const char *);
+extern void gh_buf_attach(gh_buf *buf, char *ptr, size_t asize);
+extern char *gh_buf_detach(gh_buf *buf);
+extern void gh_buf_copy_cstr(char *data, size_t datasize, const gh_buf *buf);
 
-/* bufputc: appends a single char to a buffer */
-void bufputc(struct buf *, int);
+static inline const char *gh_buf_cstr(const gh_buf *buf)
+{
+	return buf->ptr;
+}
 
-/* bufrelease: decrease the reference count and free the buffer if needed */
-void bufrelease(struct buf *);
+/*
+ * Functions below that return int value error codes will return 0 on
+ * success or -1 on failure (which generally means an allocation failed).
+ * Using a gh_buf where the allocation has failed with result in -1 from
+ * all further calls using that buffer.  As a result, you can ignore the
+ * return code of these functions and call them in a series then just call
+ * gh_buf_oom at the end.
+ */
+extern int gh_buf_set(gh_buf *buf, const char *data, size_t len);
+extern int gh_buf_sets(gh_buf *buf, const char *string);
+extern int gh_buf_putc(gh_buf *buf, char c);
+extern int gh_buf_put(gh_buf *buf, const void *data, size_t len);
+extern int gh_buf_puts(gh_buf *buf, const char *string);
+extern int gh_buf_printf(gh_buf *buf, const char *format, ...)
+	__attribute__((format (printf, 2, 3)));
+extern int gh_buf_vprintf(gh_buf *buf, const char *format, va_list ap);
+extern void gh_buf_clear(gh_buf *buf);
 
-/* bufreset: frees internal data of the buffer */
-void bufreset(struct buf *);
-
-/* bufslurp: removes a given number of bytes from the head of the array */
-void bufslurp(struct buf *, size_t);
-
-/* bufprintf: formatted printing to a buffer */
-void bufprintf(struct buf *, const char *, ...) __attribute__ ((format (printf, 2, 3)));
-
-/* vbufprintf: stdarg variant of formatted printing into a buffer */
-void vbufprintf(struct buf *, const char * , va_list);
+#define gh_buf_PUTS(buf, str) gh_buf_put(buf, str, sizeof(str) - 1)
 
 #endif