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.

5 files changed, 34 insertions, 37 deletions

diff --git a/src/win32/findfile.c b/src/win32/findfile.c
index 40d2d518a..caa79398a 100644
--- a/src/win32/findfile.c
+++ b/src/win32/findfile.c
@@ -34,7 +34,7 @@ static int git_win32__expand_path(_findfile_path *dest, const wchar_t *src)
 	return 0;
 }
 
-static int win32_path_to_8(git_buf *dest, const wchar_t *src)
+static int win32_path_to_8(git_str *dest, const wchar_t *src)
 {
 	git_win32_utf8_path utf8_path;
 
@@ -46,7 +46,7 @@ static int win32_path_to_8(git_buf *dest, const wchar_t *src)
 	/* Convert backslashes to forward slashes */
 	git_path_mkposix(utf8_path);
 
-	return git_buf_sets(dest, utf8_path);
+	return git_str_sets(dest, utf8_path);
 }
 
 static wchar_t *win32_walkpath(wchar_t *path, wchar_t *buf, size_t buflen)
@@ -70,7 +70,7 @@ static wchar_t *win32_walkpath(wchar_t *path, wchar_t *buf, size_t buflen)
 	return (path != base) ? path : NULL;
 }
 
-static int win32_find_git_in_path(git_buf *buf, const wchar_t *gitexe, const wchar_t *subdir)
+static int win32_find_git_in_path(git_str *buf, const wchar_t *gitexe, const wchar_t *subdir)
 {
 	wchar_t *env = _wgetenv(L"PATH"), lastch;
 	_findfile_path root;
@@ -106,7 +106,7 @@ static int win32_find_git_in_path(git_buf *buf, const wchar_t *gitexe, const wch
 }
 
 static int win32_find_git_in_registry(
-	git_buf *buf, const HKEY hive, const wchar_t *key, const wchar_t *subdir)
+	git_str *buf, const HKEY hive, const wchar_t *key, const wchar_t *subdir)
 {
 	HKEY hKey;
 	int error = GIT_ENOTFOUND;
@@ -141,12 +141,12 @@ static int win32_find_git_in_registry(
 }
 
 static int win32_find_existing_dirs(
-	git_buf *out, const wchar_t *tmpl[])
+	git_str *out, const wchar_t *tmpl[])
 {
 	_findfile_path path16;
-	git_buf buf = GIT_BUF_INIT;
+	git_str buf = GIT_STR_INIT;
 
-	git_buf_clear(out);
+	git_str_clear(out);
 
 	for (; *tmpl != NULL; tmpl++) {
 		if (!git_win32__expand_path(&path16, *tmpl) &&
@@ -156,43 +156,43 @@ static int win32_find_existing_dirs(
 			win32_path_to_8(&buf, path16.path);
 
 			if (buf.size)
-				git_buf_join(out, GIT_PATH_LIST_SEPARATOR, out->ptr, buf.ptr);
+				git_str_join(out, GIT_PATH_LIST_SEPARATOR, out->ptr, buf.ptr);
 		}
 	}
 
-	git_buf_dispose(&buf);
+	git_str_dispose(&buf);
 
-	return (git_buf_oom(out) ? -1 : 0);
+	return (git_str_oom(out) ? -1 : 0);
 }
 
-int git_win32__find_system_dirs(git_buf *out, const wchar_t *subdir)
+int git_win32__find_system_dirs(git_str *out, const wchar_t *subdir)
 {
-	git_buf buf = GIT_BUF_INIT;
+	git_str buf = GIT_STR_INIT;
 
 	/* directories where git.exe & git.cmd are found */
 	if (!win32_find_git_in_path(&buf, L"git.exe", subdir) && buf.size)
-		git_buf_set(out, buf.ptr, buf.size);
+		git_str_set(out, buf.ptr, buf.size);
 	else
-		git_buf_clear(out);
+		git_str_clear(out);
 
 	if (!win32_find_git_in_path(&buf, L"git.cmd", subdir) && buf.size)
-		git_buf_join(out, GIT_PATH_LIST_SEPARATOR, out->ptr, buf.ptr);
+		git_str_join(out, GIT_PATH_LIST_SEPARATOR, out->ptr, buf.ptr);
 
 	/* directories where git is installed according to registry */
 	if (!win32_find_git_in_registry(
 			&buf, HKEY_CURRENT_USER, REG_MSYSGIT_INSTALL_LOCAL, subdir) && buf.size)
-		git_buf_join(out, GIT_PATH_LIST_SEPARATOR, out->ptr, buf.ptr);
+		git_str_join(out, GIT_PATH_LIST_SEPARATOR, out->ptr, buf.ptr);
 
 	if (!win32_find_git_in_registry(
 			&buf, HKEY_LOCAL_MACHINE, REG_MSYSGIT_INSTALL, subdir) && buf.size)
-		git_buf_join(out, GIT_PATH_LIST_SEPARATOR, out->ptr, buf.ptr);
+		git_str_join(out, GIT_PATH_LIST_SEPARATOR, out->ptr, buf.ptr);
 
-	git_buf_dispose(&buf);
+	git_str_dispose(&buf);
 
-	return (git_buf_oom(out) ? -1 : 0);
+	return (git_str_oom(out) ? -1 : 0);
 }
 
-int git_win32__find_global_dirs(git_buf *out)
+int git_win32__find_global_dirs(git_str *out)
 {
 	static const wchar_t *global_tmpls[4] = {
 		L"%HOME%\\",
@@ -204,7 +204,7 @@ int git_win32__find_global_dirs(git_buf *out)
 	return win32_find_existing_dirs(out, global_tmpls);
 }
 
-int git_win32__find_xdg_dirs(git_buf *out)
+int git_win32__find_xdg_dirs(git_str *out)
 {
 	static const wchar_t *global_tmpls[7] = {
 		L"%XDG_CONFIG_HOME%\\git",
@@ -219,7 +219,7 @@ int git_win32__find_xdg_dirs(git_buf *out)
 	return win32_find_existing_dirs(out, global_tmpls);
 }
 
-int git_win32__find_programdata_dirs(git_buf *out)
+int git_win32__find_programdata_dirs(git_str *out)
 {
 	static const wchar_t *programdata_tmpls[2] = {
 		L"%PROGRAMDATA%\\Git",
diff --git a/src/win32/findfile.h b/src/win32/findfile.h
index e7bcf948a..e11ccebc5 100644
--- a/src/win32/findfile.h
+++ b/src/win32/findfile.h
@@ -10,10 +10,10 @@
 
 #include "common.h"
 
-extern int git_win32__find_system_dirs(git_buf *out, const wchar_t *subpath);
-extern int git_win32__find_global_dirs(git_buf *out);
-extern int git_win32__find_xdg_dirs(git_buf *out);
-extern int git_win32__find_programdata_dirs(git_buf *out);
+extern int git_win32__find_system_dirs(git_str *out, const wchar_t *subpath);
+extern int git_win32__find_global_dirs(git_str *out);
+extern int git_win32__find_xdg_dirs(git_str *out);
+extern int git_win32__find_programdata_dirs(git_str *out);
 
 #endif
 
diff --git a/src/win32/posix_w32.c b/src/win32/posix_w32.c
index 8af07e6fa..f26983d97 100644
--- a/src/win32/posix_w32.c
+++ b/src/win32/posix_w32.c
@@ -14,7 +14,6 @@
 #include "utf-conv.h"
 #include "repository.h"
 #include "reparse.h"
-#include "buffer.h"
 #include <errno.h>
 #include <io.h>
 #include <fcntl.h>
@@ -415,7 +414,7 @@ int p_readlink(const char *path, char *buf, size_t bufsiz)
 
 static bool target_is_dir(const char *target, const char *path)
 {
-	git_buf resolved = GIT_BUF_INIT;
+	git_str resolved = GIT_STR_INIT;
 	git_win32_path resolved_w;
 	bool isdir = true;
 
@@ -429,7 +428,7 @@ static bool target_is_dir(const char *target, const char *path)
 	isdir = GetFileAttributesW(resolved_w) & FILE_ATTRIBUTE_DIRECTORY;
 
 out:
-	git_buf_dispose(&resolved);
+	git_str_dispose(&resolved);
 	return isdir;
 }
 
@@ -1003,7 +1002,7 @@ ssize_t p_pread(int fd, void *data, size_t size, off64_t offset)
 	/* Fail if the final offset would have overflowed to match POSIX semantics. */
 	if (!git__is_ssizet(size) || git__add_int64_overflow(&final_offset, offset, (int64_t)size)) {
 		errno = EINVAL;
-		return -1;	
+		return -1;
 	}
 
 	/*
@@ -1038,7 +1037,7 @@ ssize_t p_pwrite(int fd, const void *data, size_t size, off64_t offset)
 	/* Fail if the final offset would have overflowed to match POSIX semantics. */
 	if (!git__is_ssizet(size) || git__add_int64_overflow(&final_offset, offset, (int64_t)size)) {
 		errno = EINVAL;
-		return -1;	
+		return -1;
 	}
 
 	/*
diff --git a/src/win32/w32_buffer.c b/src/win32/w32_buffer.c
index f270a1e6a..6fee8203c 100644
--- a/src/win32/w32_buffer.c
+++ b/src/win32/w32_buffer.c
@@ -7,7 +7,6 @@
 
 #include "w32_buffer.h"
 
-#include "../buffer.h"
 #include "utf-conv.h"
 
 GIT_INLINE(int) handle_wc_error(void)
@@ -20,7 +19,7 @@ GIT_INLINE(int) handle_wc_error(void)
 	return -1;
 }
 
-int git_buf_put_w(git_buf *buf, const wchar_t *string_w, size_t len_w)
+int git_str_put_w(git_str *buf, const wchar_t *string_w, size_t len_w)
 {
 	int utf8_len, utf8_write_len;
 	size_t new_size;
@@ -43,7 +42,7 @@ int git_buf_put_w(git_buf *buf, const wchar_t *string_w, size_t len_w)
 	GIT_ERROR_CHECK_ALLOC_ADD(&new_size, buf->size, (size_t)utf8_len);
 	GIT_ERROR_CHECK_ALLOC_ADD(&new_size, new_size, 1);
 
-	if (git_buf_grow(buf, new_size) < 0)
+	if (git_str_grow(buf, new_size) < 0)
 		return -1;
 
 	if ((utf8_write_len = WideCharToMultiByte(
diff --git a/src/win32/w32_buffer.h b/src/win32/w32_buffer.h
index 43298e4a7..4227296d8 100644
--- a/src/win32/w32_buffer.h
+++ b/src/win32/w32_buffer.h
@@ -8,13 +8,12 @@
 #define INCLUDE_win32_w32_buffer_h__
 
 #include "common.h"
-
-#include "../buffer.h"
+#include "str.h"
 
 /**
  * Convert a wide character string to UTF-8 and append the results to the
  * buffer.
  */
-int git_buf_put_w(git_buf *buf, const wchar_t *string_w, size_t len_w);
+int git_str_put_w(git_str *buf, const wchar_t *string_w, size_t len_w);
 
 #endif