Add routines to convert git_oid to hex strings

[sp: Credit for some of this implementation goes to Pieter, I
     started off a patch he proposed for libgit2 but reworked
     enough of it that I don't want to blame him for any bugs.]

Suggested-by: Pieter de Bie <pdebie@ai.rug.nl>
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>

1 files changed, 41 insertions, 1 deletions

diff --git a/src/git/oid.h b/src/git/oid.h
index 9e90ed0d1..6c1a2d8c3 100644
--- a/src/git/oid.h
+++ b/src/git/oid.h
@@ -13,11 +13,17 @@
  */
 GIT_BEGIN_DECL
 
+/** Size (in bytes) of a raw/binary oid */
+#define GIT_OID_RAWSZ 20
+
+/** Size (in bytes) of a hex formatted oid */
+#define GIT_OID_HEXSZ (GIT_OID_RAWSZ * 2)
+
 /** Unique identity of any object (commit, tree, blob, tag). */
 typedef struct
 {
 	/** raw binary formatted id */
-	unsigned char id[20];
+	unsigned char id[GIT_OID_RAWSZ];
 } git_oid;
 
 /**
@@ -41,6 +47,40 @@ GIT_INLINE(void) git_oid_mkraw(git_oid *out, const unsigned char *raw)
 }
 
 /**
+ * Format a git_oid into a hex string.
+ * @param str output hex string; must be pointing at the start of
+ *        the hex sequence and have at least the number of bytes
+ *        needed for an oid encoded in hex (40 bytes).  Only the
+ *        oid digits are written; a '\0' terminator must be added
+ *        by the caller if it is required.
+ * @param oid oid structure to format.
+ */
+GIT_EXTERN(void) git_oid_fmt(char *str, const git_oid *oid);
+
+/**
+ * Format a git_oid into a loose-object path string.
+ * <p>
+ * The resulting string is "aa/...", where "aa" is the first two
+ * hex digitis of the oid and "..." is the remaining 38 digits.
+ *
+ * @param str output hex string; must be pointing at the start of
+ *        the hex sequence and have at least the number of bytes
+ *        needed for an oid encoded in hex (41 bytes).  Only the
+ *        oid digits are written; a '\0' terminator must be added
+ *        by the caller if it is required.
+ * @param oid oid structure to format.
+ */
+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
+ * @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);
+
+/**
  * Copy an oid from one structure to another.
  * @param out oid structure the result is written into.
  * @param src oid structure to copy from.