str: introduce `git_str` for internal, `git_buf` is externalethomson/gitstr

libgit2 has two distinct requirements that were previously solved by
`git_buf`.  We require:

1. A general purpose string class that provides a number of utility APIs
   for manipulating data (eg, concatenating, truncating, etc).
2. A structure that we can use to return strings to callers that they
   can take ownership of.

By using a single class (`git_buf`) for both of these purposes, we have
confused the API to the point that refactorings are difficult and
reasoning about correctness is also difficult.

Move the utility class `git_buf` to be called `git_str`: this represents
its general purpose, as an internal string buffer class.  The name also
is an homage to Junio Hamano ("gitstr").

The public API remains `git_buf`, and has a much smaller footprint.  It
is generally only used as an "out" param with strict requirements that
follow the documentation.  (Exceptions exist for some legacy APIs to
avoid breaking callers unnecessarily.)

Utility functions exist to convert a user-specified `git_buf` to a
`git_str` so that we can call internal functions, then converting it
back again.

1 files changed, 18 insertions, 78 deletions

diff --git a/include/git2/buffer.h b/include/git2/buffer.h
index 926f1332d..9fa972034 100644
--- a/include/git2/buffer.h
+++ b/include/git2/buffer.h
@@ -23,110 +23,50 @@ GIT_BEGIN_DECL
  *
  * Sometimes libgit2 wants to return an allocated data buffer to the
  * caller and have the caller take responsibility for freeing that memory.
- * This can be awkward if the caller does not have easy access to the same
- * allocation functions that libgit2 is using.  In those cases, libgit2
- * will fill in a `git_buf` and the caller can use `git_buf_dispose()` to
- * release it when they are done.
+ * To make ownership clear in these cases, libgit2 uses  `git_buf` to
+ * return this data.  Callers should use `git_buf_dispose()` to release
+ * the memory when they are done.
  *
- * A `git_buf` may also be used for the caller to pass in a reference to
- * a block of memory they hold.  In this case, libgit2 will not resize or
- * free the memory, but will read from it as needed.
- *
- * Some APIs may occasionally do something slightly unusual with a buffer,
- * such as setting `ptr` to a value that was passed in by the user.  In
- * those cases, the behavior will be clearly documented by the API.
+ * A `git_buf` contains a pointer to a NUL-terminated C string, and
+ * the length of the string (not including the NUL terminator).
  */
 typedef struct {
 	/**
-	 * The buffer contents.
-	 *
-	 * `ptr` points to the start of the allocated memory.  If it is NULL,
-	 * then the `git_buf` is considered empty and libgit2 will feel free
-	 * to overwrite it with new data.
+	 * The buffer contents.  `ptr` points to the start of the buffer
+	 * being returned.  The buffer's length (in bytes) is specified
+	 * by the `size` member of the structure, and contains a NUL
+	 * terminator at position `(size + 1)`.
 	 */
-	char   *ptr;
+	char *ptr;
 
 	/**
-	 * `asize` holds the known total amount of allocated memory if the `ptr`
-	 *  was allocated by libgit2.  It may be larger than `size`.  If `ptr`
-	 *  was not allocated by libgit2 and should not be resized and/or freed,
-	 *  then `asize` will be set to zero.
+	 * This field is reserved and unused.
 	 */
-	size_t asize;
+	size_t reserved;
 
 	/**
-	 * `size` holds the size (in bytes) of the data that is actually used.
+	 * The length (in bytes) of the buffer pointed to by `ptr`,
+	 * not including a NUL terminator.
 	 */
 	size_t size;
 } git_buf;
 
 /**
- * Static initializer for git_buf from static buffer
+ * Use to initialize a `git_buf` before passing it to a function that
+ * will populate it.
  */
-#define GIT_BUF_INIT_CONST(STR,LEN) { (char *)(STR), 0, (size_t)(LEN) }
+#define GIT_BUF_INIT { NULL, 0, 0 }
 
 /**
  * Free the memory referred to by the git_buf.
  *
  * Note that this does not free the `git_buf` itself, just the memory
- * pointed to by `buffer->ptr`.  This will not free the memory if it looks
- * like it was not allocated internally, but it will clear the buffer back
- * to the empty state.
+ * pointed to by `buffer->ptr`.
  *
  * @param buffer The buffer to deallocate
  */
 GIT_EXTERN(void) git_buf_dispose(git_buf *buffer);
 
-/**
- * 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_buf_grow(git_buf *buffer, size_t target_size);
-
-/**
- * Set buffer to a copy of some raw data.
- *
- * @param buffer The buffer to set
- * @param data The data to copy into the buffer
- * @param datalen The length of the data to copy into the buffer
- * @return 0 on success, -1 on allocation failure
- */
-GIT_EXTERN(int) git_buf_set(
-	git_buf *buffer, const void *data, size_t datalen);
-
-/**
-* 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_buf_is_binary(const git_buf *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_buf_contains_nul(const git_buf *buf);
-
 GIT_END_DECL
 
 /** @} */