include/git2/oid.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   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 {
  34         /** raw binary formatted id */
  35         unsigned char id[GIT_OID_RAWSZ];
  36 } git_oid;
  37
  38 /**
  39  * Parse a hex formatted object id into a git_oid.
  40  *
  41  * @param out oid structure the result is written into.
  42  * @param str input hex string; must be pointing at the start of
  43  *              the hex sequence and have at least the number of bytes
  44  *              needed for an oid encoded in hex (40 bytes).
  45  * @return 0 or an error code
  46  */
  47 GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str);
  48
  49 /**
  50  * Parse a hex formatted null-terminated string into a git_oid.
  51  *
  52  * @param out oid structure the result is written into.
  53  * @param str input hex string; must be null-terminated.
  54  * @return 0 or an error code
  55  */
  56 GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str);
  57
  58 /**
  59  * Parse N characters of a hex formatted object id into a git_oid.
  60  *
  61  * If N is odd, the last byte's high nibble will be read in and the
  62  * low nibble set to zero.
  63  *
  64  * @param out oid structure the result is written into.
  65  * @param str input hex string of at least size `length`
  66  * @param length length of the input string
  67  * @return 0 or an error code
  68  */
  69 GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length);
  70
  71 /**
  72  * Copy an already raw oid into a git_oid structure.
  73  *
  74  * @param out oid structure the result is written into.
  75  * @param raw the raw input bytes to be copied.
  76  * @return 0 on success or error code
  77  */
  78 GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw);
  79
  80 /**
  81  * Format a git_oid into a hex string.
  82  *
  83  * @param out output hex string; must be pointing at the start of
  84  *              the hex sequence and have at least the number of bytes
  85  *              needed for an oid encoded in hex (40 bytes). Only the
  86  *              oid digits are written; a '\\0' terminator must be added
  87  *              by the caller if it is required.
  88  * @param id oid structure to format.
  89  * @return 0 on success or error code
  90  */
  91 GIT_EXTERN(int) git_oid_fmt(char *out, const git_oid *id);
  92
  93 /**
  94  * Format a git_oid into a partial hex string.
  95  *
  96  * @param out output hex string; you say how many bytes to write.
  97  *              If the number of bytes is > GIT_OID_HEXSZ, extra bytes
  98  *              will be zeroed; if not, a '\0' terminator is NOT added.
  99  * @param n number of characters to write into out string
 100  * @param id oid structure to format.
 101  * @return 0 on success or error code
 102  */
 103 GIT_EXTERN(int) git_oid_nfmt(char *out, size_t n, const git_oid *id);
 104
 105 /**
 106  * Format a git_oid into a loose-object path string.
 107  *
 108  * The resulting string is "aa/...", where "aa" is the first two
 109  * hex digits of the oid and "..." is the remaining 38 digits.
 110  *
 111  * @param out output hex string; must be pointing at the start of
 112  *              the hex sequence and have at least the number of bytes
 113  *              needed for an oid encoded in hex (41 bytes). Only the
 114  *              oid digits are written; a '\\0' terminator must be added
 115  *              by the caller if it is required.
 116  * @param id oid structure to format.
 117  * @return 0 on success, non-zero callback return value, or error code
 118  */
 119 GIT_EXTERN(int) git_oid_pathfmt(char *out, const git_oid *id);
 120
 121 /**
 122  * Format a git_oid into a statically allocated c-string.
 123  *
 124  * The c-string is owned by the library and should not be freed
 125  * by the user. If libgit2 is built with thread support, the string
 126  * will be stored in TLS (i.e. one buffer per thread) to allow for
 127  * concurrent calls of the function.
 128  *
 129  * @param oid The oid structure to format
 130  * @return the c-string
 131  */
 132 GIT_EXTERN(char *) git_oid_tostr_s(const git_oid *oid);
 133
 134 /**
 135  * Format a git_oid into a buffer as a hex format c-string.
 136  *
 137  * If the buffer is smaller than GIT_OID_HEXSZ+1, then the resulting
 138  * oid c-string will be truncated to n-1 characters (but will still be
 139  * NUL-byte terminated).
 140  *
 141  * If there are any input parameter errors (out == NULL, n == 0, oid ==
 142  * NULL), then a pointer to an empty string is returned, so that the
 143  * return value can always be printed.
 144  *
 145  * @param out the buffer into which the oid string is output.
 146  * @param n the size of the out buffer.
 147  * @param id the oid structure to format.
 148  * @return the out buffer pointer, assuming no input parameter
 149  *                      errors, otherwise a pointer to an empty string.
 150  */
 151 GIT_EXTERN(char *) git_oid_tostr(char *out, size_t n, const git_oid *id);
 152
 153 /**
 154  * Copy an oid from one structure to another.
 155  *
 156  * @param out oid structure the result is written into.
 157  * @param src oid structure to copy from.
 158  * @return 0 on success or error code
 159  */
 160 GIT_EXTERN(int) git_oid_cpy(git_oid *out, const git_oid *src);
 161
 162 /**
 163  * Compare two oid structures.
 164  *
 165  * @param a first oid structure.
 166  * @param b second oid structure.
 167  * @return <0, 0, >0 if a < b, a == b, a > b.
 168  */
 169 GIT_EXTERN(int) git_oid_cmp(const git_oid *a, const git_oid *b);
 170
 171 /**
 172  * Compare two oid structures for equality
 173  *
 174  * @param a first oid structure.
 175  * @param b second oid structure.
 176  * @return true if equal, false otherwise
 177  */
 178 GIT_EXTERN(int) git_oid_equal(const git_oid *a, const git_oid *b);
 179
 180 /**
 181  * Compare the first 'len' hexadecimal characters (packets of 4 bits)
 182  * of two oid structures.
 183  *
 184  * @param a first oid structure.
 185  * @param b second oid structure.
 186  * @param len the number of hex chars to compare
 187  * @return 0 in case of a match
 188  */
 189 GIT_EXTERN(int) git_oid_ncmp(const git_oid *a, const git_oid *b, size_t len);
 190
 191 /**
 192  * Check if an oid equals an hex formatted object id.
 193  *
 194  * @param id oid structure.
 195  * @param str input hex string of an object id.
 196  * @return 0 in case of a match, -1 otherwise.
 197  */
 198 GIT_EXTERN(int) git_oid_streq(const git_oid *id, const char *str);
 199
 200 /**
 201  * Compare an oid to an hex formatted object id.
 202  *
 203  * @param id oid structure.
 204  * @param str input hex string of an object id.
 205  * @return -1 if str is not valid, <0 if id sorts before str,
 206  *         0 if id matches str, >0 if id sorts after str.
 207  */
 208 GIT_EXTERN(int) git_oid_strcmp(const git_oid *id, const char *str);
 209
 210 /**
 211  * Check is an oid is all zeros.
 212  *
 213  * @return 1 if all zeros, 0 otherwise.
 214  */
 215 GIT_EXTERN(int) git_oid_is_zero(const git_oid *id);
 216
 217 /**
 218  * OID Shortener object
 219  */
 220 typedef struct git_oid_shorten git_oid_shorten;
 221
 222 /**
 223  * Create a new OID shortener.
 224  *
 225  * The OID shortener is used to process a list of OIDs
 226  * in text form and return the shortest length that would
 227  * uniquely identify all of them.
 228  *
 229  * E.g. look at the result of `git log --abbrev`.
 230  *
 231  * @param min_length The minimal length for all identifiers,
 232  *              which will be used even if shorter OIDs would still
 233  *              be unique.
 234  *      @return a `git_oid_shorten` instance, NULL if OOM
 235  */
 236 GIT_EXTERN(git_oid_shorten *) git_oid_shorten_new(size_t min_length);
 237
 238 /**
 239  * Add a new OID to set of shortened OIDs and calculate
 240  * the minimal length to uniquely identify all the OIDs in
 241  * the set.
 242  *
 243  * The OID is expected to be a 40-char hexadecimal string.
 244  * The OID is owned by the user and will not be modified
 245  * or freed.
 246  *
 247  * For performance reasons, there is a hard-limit of how many
 248  * OIDs can be added to a single set (around ~32000, assuming
 249  * a mostly randomized distribution), which should be enough
 250  * for any kind of program, and keeps the algorithm fast and
 251  * memory-efficient.
 252  *
 253  * Attempting to add more than those OIDs will result in a
 254  * GIT_ERROR_INVALID error
 255  *
 256  * @param os a `git_oid_shorten` instance
 257  * @param text_id an OID in text form
 258  * @return the minimal length to uniquely identify all OIDs
 259  *              added so far to the set; or an error code (<0) if an
 260  *              error occurs.
 261  */
 262 GIT_EXTERN(int) git_oid_shorten_add(git_oid_shorten *os, const char *text_id);
 263
 264 /**
 265  * Free an OID shortener instance
 266  *
 267  * @param os a `git_oid_shorten` instance
 268  */
 269 GIT_EXTERN(void) git_oid_shorten_free(git_oid_shorten *os);
 270
 271 /** @} */
 272 GIT_END_DECL
 273 #endif