buf: deprecate git_buf as a public typeethomson/userbuf

The `git_buf` type is now no longer a publicly available structure, and
the `git_buf` family of functions are no longer exported.

The deprecation layer adds a typedef for `git_buf` (as `git_userbuf`)
and macros that define `git_buf` functions as `git_userbuf` functions.
This provides API (but not ABI) compatibility with libgit2 1.0's buffer
functionality.

Within libgit2 itself, we take care to avoid including those deprecated
typedefs and macros, since we want to continue using the `git_buf` type
and functions unmodified.  Therefore, a `GIT_DEPRECATE_BUF` guard now
wraps the buffer deprecation layer.  libgit2 will define that.

1 files changed, 43 insertions, 4 deletions

diff --git a/include/git2/userbuf.h b/include/git2/userbuf.h
index 4fe8ccf47..2e498914a 100644
--- a/include/git2/userbuf.h
+++ b/include/git2/userbuf.h
@@ -28,9 +28,9 @@ GIT_BEGIN_DECL
  * A data buffer for exporting data from libgit2.
  *
  * Sometimes libgit2 wants to return an allocated data buffer to the
- * caller and have the caller take responsibility for freeing that memory.
- * This structure should be freed with `git_userbuf_dispose` when you
- * have finished with it.
+ * caller and allow the caller take responsibility for its lifecycle.
+ * This requires the caller to free the memory with `git_userbuf_dispose`
+ * when they have finished using it.
  */
 typedef struct {
 	/**
@@ -54,6 +54,22 @@ typedef struct {
 } git_userbuf;
 
 /**
+ * Check quickly if buffer looks like it contains binary data
+ *
+ * @param buf Buffer to check
+ * @return 1 if buffer looks like non-text data
+ */
+GIT_EXTERN(int) git_userbuf_is_binary(const git_userbuf *buf);
+
+ /**
+ * Check quickly if buffer contains a NUL byte
+ *
+ * @param buf Buffer to check
+ * @return 1 if buffer contains a NUL byte
+ */
+GIT_EXTERN(int) git_userbuf_contains_nul(const git_userbuf *buf);
+
+/**
  * Places the given data in the buffer.  This is necessary for some
  * callback functions that take user data.  If there is already data in
  * the buffer, you should call `git_userbuf_dispose` before setting the
@@ -63,7 +79,30 @@ typedef struct {
  * @param ptr The data to place in the buffer
  * @param len The length of the data in bytes
  */
-GIT_EXTERN(int) git_userbuf_set(git_userbuf *buf, const char *ptr, size_t len);
+GIT_EXTERN(int) git_userbuf_set(git_userbuf *buf, const void *ptr, size_t len);
+
+/**
+ * Resize the buffer allocation to make more space.
+ *
+ * This will attempt to grow the buffer to accommodate the target size.
+ *
+ * If the buffer refers to memory that was not allocated by libgit2 (i.e.
+ * the `asize` field is zero), then `ptr` will be replaced with a newly
+ * allocated block of data.  Be careful so that memory allocated by the
+ * caller is not lost.  As a special variant, if you pass `target_size` as
+ * 0 and the memory is not allocated by libgit2, this will allocate a new
+ * buffer of size `size` and copy the external data into it.
+ *
+ * Currently, this will never shrink a buffer, only expand it.
+ *
+ * If the allocation fails, this will return an error and the buffer will be
+ * marked as invalid for future operations, invaliding the contents.
+ *
+ * @param buffer The buffer to be resized; may or may not be allocated yet
+ * @param target_size The desired available size
+ * @return 0 on success, -1 on allocation failure
+ */
+GIT_EXTERN(int) git_userbuf_grow(git_userbuf *buffer, size_t target_size);
 
 /**
  * Free the memory referred to by the git_userbuf.