Add the git_oid_to_string() utility function

Signed-off-by: Ramsay Jones <ramsay@ramsay1.demon.co.uk>

src/git/oid.h

@@ -74,13 +74,30 @@ GIT_EXTERN(void) git_oid_pathfmt(char *str, const git_oid *oid);
 
 /**
  * Format a gid_oid into a newly allocated c-string.
- * @param oid theoid structure to format
+ * @param oid the oid structure to format
  * @return the c-string; NULL if memory is exhausted.  Caller must
  *         deallocate the string with free().
  */
 GIT_EXTERN(char *) git_oid_allocfmt(const git_oid *oid);
 
 /**
+ * Format a git_oid into a buffer as a hex format c-string.
+ * <p>
+ * If the buffer is smaller than GIT_OID_HEXSZ+1, then the resulting
+ * oid c-string will be truncated to n-1 characters. If there are
+ * any input parameter errors (out == NULL, n == 0, oid == NULL),
+ * then a pointer to an empty string is returned, so that the return
+ * value can always be printed.
+ *
+ * @param out the buffer into which the oid string is output.
+ * @param n the size of the out buffer.
+ * @param oid the oid structure to format.
+ * @return the out buffer pointer, assuming no input parameter
+ *         errors, otherwise a pointer to an empty string.
+ */
+GIT_EXTERN(char *) git_oid_to_string(char *out, size_t n, const git_oid *oid);
+
+/**
  * Copy an oid from one structure to another.
  * @param out oid structure the result is written into.
  * @param src oid structure to copy from.

src/oid.c

@@ -94,3 +94,23 @@ char *git_oid_allocfmt(const git_oid *oid)
 	str[GIT_OID_HEXSZ] = '\0';
 	return str;
 }
+
+char *git_oid_to_string(char *out, size_t n, const git_oid *oid)
+{
+	char str[GIT_OID_HEXSZ];
+
+	if (!out || n == 0 || !oid)
+		return "";
+
+	n--;  /* allow room for terminating NUL */
+
+	if (n > 0) {
+		git_oid_fmt(str, oid);
+		memcpy(out, str, n > GIT_OID_HEXSZ ? GIT_OID_HEXSZ : n);
+	}
+
+	out[n] = '\0';
+
+	return out;
+}
+

tests/t0101-oid.c

@@ -208,3 +208,47 @@ BEGIN_TEST(cmp_oid_pathfmt)
 	must_pass(strcmp(exp2, out));
 END_TEST
 
+BEGIN_TEST(oid_to_string)
+	const char *exp = "16a0123456789abcdef4b775213c23a8bd74f5e0";
+	git_oid in;
+	char out[GIT_OID_HEXSZ + 1];
+	char *str;
+	int i;
+
+	must_pass(git_oid_mkstr(&in, exp));
+
+	/* NULL buffer pointer, returns static empty string */
+	str = git_oid_to_string(NULL, sizeof(out), &in);
+	must_be_true(str && *str == '\0' && str != out);
+
+	/* zero buffer size, returns static empty string */
+	str = git_oid_to_string(out, 0, &in);
+	must_be_true(str && *str == '\0' && str != out);
+
+	/* NULL oid pointer, returns static empty string */
+	str = git_oid_to_string(out, sizeof(out), NULL);
+	must_be_true(str && *str == '\0' && str != out);
+
+	/* n == 1, returns out as an empty string */
+	str = git_oid_to_string(out, 1, &in);
+	must_be_true(str && *str == '\0' && str == out);
+
+	for (i = 1; i < GIT_OID_HEXSZ; i++) {
+		out[i+1] = 'Z';
+		str = git_oid_to_string(out, i+1, &in);
+		/* returns out containing c-string */
+		must_be_true(str && str == out);
+		/* must be '\0' terminated */
+		must_be_true(*(str+i) == '\0');
+		/* must not touch bytes past end of string */
+		must_be_true(*(str+(i+1)) == 'Z');
+		/* i == n-1 charaters of string */
+		must_pass(strncmp(exp, out, i));
+	}
+
+	/* returns out as hex formatted c-string */
+	str = git_oid_to_string(out, sizeof(out), &in);
+	must_be_true(str && str == out && *(str+GIT_OID_HEXSZ) == '\0');
+	must_pass(strcmp(exp, out));
+END_TEST
+