include/git2/oid.h

   1 /*
   2  * Copyright (C) 2009-2011 the libgit2 contributors
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7 #ifndef INCLUDE_git_oid_h__
   8 #define INCLUDE_git_oid_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12
  13 /**
  14  * @file git2/oid.h
  15  * @brief Git object id routines
  16  * @defgroup git_oid Git object id routines
  17  * @ingroup Git
  18  * @{
  19  */
  20 GIT_BEGIN_DECL
  21
  22 /** Size (in bytes) of a raw/binary oid */
  23 #define GIT_OID_RAWSZ 20
  24
  25 /** Size (in bytes) of a hex formatted oid */
  26 #define GIT_OID_HEXSZ (GIT_OID_RAWSZ * 2)
  27
  28 /** Minimum length (in number of hex characters,
  29  * i.e. packets of 4 bits) of an oid prefix */
  30 #define GIT_OID_MINPREFIXLEN 4
  31
  32 /** Unique identity of any object (commit, tree, blob, tag). */
  33 typedef struct _git_oid git_oid;
  34 struct _git_oid {
  35         /** raw binary formatted id */
  36         unsigned char id[GIT_OID_RAWSZ];
  37 };
  38
  39 /**
  40  * Parse a hex formatted object id into a git_oid.
  41  *
  42  * @param out oid structure the result is written into.
  43  * @param str input hex string; must be pointing at the start of
  44  *        the hex sequence and have at least the number of bytes
  45  *        needed for an oid encoded in hex (40 bytes).
  46  * @return GIT_SUCCESS or an error code
  47  */
  48 GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str);
  49
  50 /**
  51  * Parse N characters of a hex formatted object id into a git_oid
  52  *
  53  * If N is odd, N-1 characters will be parsed instead.
  54  * The remaining space in the git_oid will be set to zero.
  55  *
  56  * @param out oid structure the result is written into.
  57  * @param str input hex string of at least size `length`
  58  * @param length length of the input string
  59  * @return GIT_SUCCESS or an error code
  60  */
  61 GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length);
  62
  63 /**
  64  * Copy an already raw oid into a git_oid structure.
  65  *
  66  * @param out oid structure the result is written into.
  67  * @param raw the raw input bytes to be copied.
  68  */
  69 GIT_EXTERN(void) git_oid_fromraw(git_oid *out, const unsigned char *raw);
  70
  71 /**
  72  * Format a git_oid into a hex string.
  73  *
  74  * @param str output hex string; must be pointing at the start of
  75  *        the hex sequence and have at least the number of bytes
  76  *        needed for an oid encoded in hex (40 bytes).  Only the
  77  *        oid digits are written; a '\\0' terminator must be added
  78  *        by the caller if it is required.
  79  * @param oid oid structure to format.
  80  */
  81 GIT_EXTERN(void) git_oid_fmt(char *str, const git_oid *oid);
  82
  83 /**
  84  * Format a git_oid into a loose-object path string.
  85  *
  86  * The resulting string is "aa/...", where "aa" is the first two
  87  * hex digitis of the oid and "..." is the remaining 38 digits.
  88  *
  89  * @param str output hex string; must be pointing at the start of
  90  *        the hex sequence and have at least the number of bytes
  91  *        needed for an oid encoded in hex (41 bytes).  Only the
  92  *        oid digits are written; a '\\0' terminator must be added
  93  *        by the caller if it is required.
  94  * @param oid oid structure to format.
  95  */
  96 GIT_EXTERN(void) git_oid_pathfmt(char *str, const git_oid *oid);
  97
  98 /**
  99  * Format a git_oid into a newly allocated c-string.
 100  *
 101  * @param oid the oid structure to format
 102  * @return the c-string; NULL if memory is exhausted.  Caller must
 103  *         deallocate the string with free().
 104  */
 105 GIT_EXTERN(char *) git_oid_allocfmt(const git_oid *oid);
 106
 107 /**
 108  * Format a git_oid into a buffer as a hex format c-string.
 109  *
 110  * If the buffer is smaller than GIT_OID_HEXSZ+1, then the resulting
 111  * oid c-string will be truncated to n-1 characters. If there are
 112  * any input parameter errors (out == NULL, n == 0, oid == NULL),
 113  * then a pointer to an empty string is returned, so that the return
 114  * value can always be printed.
 115  *
 116  * @param out the buffer into which the oid string is output.
 117  * @param n the size of the out buffer.
 118  * @param oid the oid structure to format.
 119  * @return the out buffer pointer, assuming no input parameter
 120  *         errors, otherwise a pointer to an empty string.
 121  */
 122 GIT_EXTERN(char *) git_oid_to_string(char *out, size_t n, const git_oid *oid);
 123
 124 /**
 125  * Copy an oid from one structure to another.
 126  *
 127  * @param out oid structure the result is written into.
 128  * @param src oid structure to copy from.
 129  */
 130 GIT_EXTERN(void) git_oid_cpy(git_oid *out, const git_oid *src);
 131
 132 /**
 133  * Compare two oid structures.
 134  *
 135  * @param a first oid structure.
 136  * @param b second oid structure.
 137  * @return <0, 0, >0 if a < b, a == b, a > b.
 138  */
 139 GIT_EXTERN(int) git_oid_cmp(const git_oid *a, const git_oid *b);
 140
 141 /**
 142  * Compare the first 'len' hexadecimal characters (packets of 4 bits)
 143  * of two oid structures.
 144  *
 145  * @param a first oid structure.
 146  * @param b second oid structure.
 147  * @param len the number of hex chars to compare
 148  * @return 0 in case of a match
 149  */
 150 GIT_EXTERN(int) git_oid_ncmp(const git_oid *a, const git_oid *b, unsigned int len);
 151
 152 /**
 153  * OID Shortener object
 154  */
 155 typedef struct git_oid_shorten git_oid_shorten;
 156
 157 /**
 158  * Create a new OID shortener.
 159  *
 160  * The OID shortener is used to process a list of OIDs
 161  * in text form and return the shortest length that would
 162  * uniquely identify all of them.
 163  *
 164  * E.g. look at the result of `git log --abbrev`.
 165  *
 166  * @param min_length The minimal length for all identifiers,
 167  *              which will be used even if shorter OIDs would still
 168  *              be unique.
 169  *      @return a `git_oid_shorten` instance, NULL if OOM
 170  */
 171 git_oid_shorten *git_oid_shorten_new(size_t min_length);
 172
 173 /**
 174  * Add a new OID to set of shortened OIDs and calculate
 175  * the minimal length to uniquely identify all the OIDs in
 176  * the set.
 177  *
 178  * The OID is expected to be a 40-char hexadecimal string.
 179  * The OID is owned by the user and will not be modified
 180  * or freed.
 181  *
 182  * For performance reasons, there is a hard-limit of how many
 183  * OIDs can be added to a single set (around ~22000, assuming
 184  * a mostly randomized distribution), which should be enough
 185  * for any kind of program, and keeps the algorithm fast and
 186  * memory-efficient.
 187  *
 188  * Attempting to add more than those OIDs will result in a
 189  * GIT_ENOMEM error
 190  *
 191  * @param os a `git_oid_shorten` instance
 192  * @param text_oid an OID in text form
 193  * @return the minimal length to uniquely identify all OIDs
 194  *              added so far to the set; or an error code (<0) if an
 195  *              error occurs.
 196  */
 197 int git_oid_shorten_add(git_oid_shorten *os, const char *text_oid);
 198
 199 /**
 200  * Free an OID shortener instance
 201  *
 202  * @param os a `git_oid_shorten` instance
 203  */
 204 void git_oid_shorten_free(git_oid_shorten *os);
 205
 206 /** @} */
 207 GIT_END_DECL
 208 #endif