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 274