]>
Commit | Line | Data |
---|---|---|
f5918330 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
f5918330 | 3 | * |
bb742ede VM |
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. | |
f5918330 | 6 | */ |
c15648cb SP |
7 | #ifndef INCLUDE_git_oid_h__ |
8 | #define INCLUDE_git_oid_h__ | |
9 | ||
b70e4f8a VM |
10 | #include "common.h" |
11 | #include "types.h" | |
12 | ||
c15648cb | 13 | /** |
f5918330 | 14 | * @file git2/oid.h |
c15648cb SP |
15 | * @brief Git object id routines |
16 | * @defgroup git_oid Git object id routines | |
17 | * @ingroup Git | |
18 | * @{ | |
19 | */ | |
20 | GIT_BEGIN_DECL | |
21 | ||
af795e49 SP |
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 | ||
ac2b94ad MP |
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 | ||
c15648cb | 32 | /** Unique identity of any object (commit, tree, blob, tag). */ |
74f91322 | 33 | typedef struct git_oid { |
c15648cb | 34 | /** raw binary formatted id */ |
af795e49 | 35 | unsigned char id[GIT_OID_RAWSZ]; |
74f91322 | 36 | } git_oid; |
c15648cb SP |
37 | |
38 | /** | |
39 | * Parse a hex formatted object id into a git_oid. | |
f1d01851 | 40 | * |
c15648cb SP |
41 | * @param out oid structure the result is written into. |
42 | * @param str input hex string; must be pointing at the start of | |
87d9869f VM |
43 | * the hex sequence and have at least the number of bytes |
44 | * needed for an oid encoded in hex (40 bytes). | |
e172cf08 | 45 | * @return 0 or an error code |
c15648cb | 46 | */ |
fa48608e | 47 | GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str); |
c15648cb | 48 | |
0c8efb38 X |
49 | /** |
50 | * Parse a hex formatted null-terminated string into a git_oid. | |
51 | * | |
52 | * @param out oid structure the result is written into. | |
921493cc | 53 | * @param str input hex string; must be null-terminated. |
0c8efb38 X |
54 | * @return 0 or an error code |
55 | */ | |
56 | GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str); | |
57 | ||
d5afc039 | 58 | /** |
921493cc | 59 | * Parse N characters of a hex formatted object id into a git_oid. |
d5afc039 | 60 | * |
921493cc MP |
61 | * If N is odd, the last byte's high nibble will be read in and the |
62 | * low nibble set to zero. | |
d5afc039 VM |
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 | |
e172cf08 | 67 | * @return 0 or an error code |
d5afc039 VM |
68 | */ |
69 | GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length); | |
70 | ||
c15648cb SP |
71 | /** |
72 | * Copy an already raw oid into a git_oid structure. | |
f1d01851 | 73 | * |
c15648cb SP |
74 | * @param out oid structure the result is written into. |
75 | * @param raw the raw input bytes to be copied. | |
22a2d3d5 | 76 | * @return 0 on success or error code |
c15648cb | 77 | */ |
22a2d3d5 | 78 | GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw); |
b7c891c6 | 79 | |
af795e49 SP |
80 | /** |
81 | * Format a git_oid into a hex string. | |
f1d01851 | 82 | * |
74f91322 | 83 | * @param out output hex string; must be pointing at the start of |
87d9869f VM |
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. | |
e1967164 | 88 | * @param id oid structure to format. |
22a2d3d5 | 89 | * @return 0 on success or error code |
af795e49 | 90 | */ |
22a2d3d5 | 91 | GIT_EXTERN(int) git_oid_fmt(char *out, const git_oid *id); |
af795e49 | 92 | |
660d59ca RB |
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 | |
e1967164 | 100 | * @param id oid structure to format. |
22a2d3d5 | 101 | * @return 0 on success or error code |
660d59ca | 102 | */ |
22a2d3d5 | 103 | GIT_EXTERN(int) git_oid_nfmt(char *out, size_t n, const git_oid *id); |
660d59ca | 104 | |
af795e49 SP |
105 | /** |
106 | * Format a git_oid into a loose-object path string. | |
f1d01851 | 107 | * |
af795e49 | 108 | * The resulting string is "aa/...", where "aa" is the first two |
d73c94b2 | 109 | * hex digits of the oid and "..." is the remaining 38 digits. |
af795e49 | 110 | * |
74f91322 | 111 | * @param out output hex string; must be pointing at the start of |
87d9869f VM |
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. | |
74f91322 | 116 | * @param id oid structure to format. |
22a2d3d5 | 117 | * @return 0 on success, non-zero callback return value, or error code |
af795e49 | 118 | */ |
22a2d3d5 | 119 | GIT_EXTERN(int) git_oid_pathfmt(char *out, const git_oid *id); |
af795e49 SP |
120 | |
121 | /** | |
4ca0b566 VM |
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. | |
f1d01851 | 128 | * |
ec7e1c93 | 129 | * @param oid The oid structure to format |
4ca0b566 | 130 | * @return the c-string |
af795e49 | 131 | */ |
4ca0b566 | 132 | GIT_EXTERN(char *) git_oid_tostr_s(const git_oid *oid); |
af795e49 | 133 | |
960ca1d7 RJ |
134 | /** |
135 | * Format a git_oid into a buffer as a hex format c-string. | |
f1d01851 | 136 | * |
960ca1d7 | 137 | * If the buffer is smaller than GIT_OID_HEXSZ+1, then the resulting |
660d59ca RB |
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. | |
960ca1d7 RJ |
144 | * |
145 | * @param out the buffer into which the oid string is output. | |
146 | * @param n the size of the out buffer. | |
74f91322 | 147 | * @param id the oid structure to format. |
960ca1d7 | 148 | * @return the out buffer pointer, assuming no input parameter |
87d9869f | 149 | * errors, otherwise a pointer to an empty string. |
960ca1d7 | 150 | */ |
74f91322 | 151 | GIT_EXTERN(char *) git_oid_tostr(char *out, size_t n, const git_oid *id); |
960ca1d7 | 152 | |
b7c891c6 SP |
153 | /** |
154 | * Copy an oid from one structure to another. | |
f1d01851 | 155 | * |
b7c891c6 SP |
156 | * @param out oid structure the result is written into. |
157 | * @param src oid structure to copy from. | |
22a2d3d5 | 158 | * @return 0 on success or error code |
b7c891c6 | 159 | */ |
22a2d3d5 | 160 | GIT_EXTERN(int) git_oid_cpy(git_oid *out, const git_oid *src); |
b7c891c6 SP |
161 | |
162 | /** | |
163 | * Compare two oid structures. | |
f1d01851 | 164 | * |
b7c891c6 SP |
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 | */ | |
b7f167da | 169 | GIT_EXTERN(int) git_oid_cmp(const git_oid *a, const git_oid *b); |
f6b26e77 MS |
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 | */ | |
978a4ed5 | 178 | GIT_EXTERN(int) git_oid_equal(const git_oid *a, const git_oid *b); |
c15648cb | 179 | |
53c0bd81 MP |
180 | /** |
181 | * Compare the first 'len' hexadecimal characters (packets of 4 bits) | |
182 | * of two oid structures. | |
f1d01851 | 183 | * |
53c0bd81 MP |
184 | * @param a first oid structure. |
185 | * @param b second oid structure. | |
f1d01851 | 186 | * @param len the number of hex chars to compare |
da03c9f3 | 187 | * @return 0 in case of a match |
53c0bd81 | 188 | */ |
b8457baa | 189 | GIT_EXTERN(int) git_oid_ncmp(const git_oid *a, const git_oid *b, size_t len); |
53c0bd81 | 190 | |
34aff010 | 191 | /** |
192 | * Check if an oid equals an hex formatted object id. | |
193 | * | |
74f91322 | 194 | * @param id oid structure. |
34aff010 | 195 | * @param str input hex string of an object id. |
e68938e0 | 196 | * @return 0 in case of a match, -1 otherwise. |
34aff010 | 197 | */ |
74f91322 | 198 | GIT_EXTERN(int) git_oid_streq(const git_oid *id, const char *str); |
34aff010 | 199 | |
aa8f0101 RB |
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 | ||
74fa4bfa RB |
210 | /** |
211 | * Check is an oid is all zeros. | |
5f4a61ae RB |
212 | * |
213 | * @return 1 if all zeros, 0 otherwise. | |
74fa4bfa | 214 | */ |
22a2d3d5 | 215 | GIT_EXTERN(int) git_oid_is_zero(const git_oid *id); |
74fa4bfa | 216 | |
26022f07 VM |
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 | */ | |
0c9a5565 | 236 | GIT_EXTERN(git_oid_shorten *) git_oid_shorten_new(size_t min_length); |
26022f07 VM |
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 | |
d45e9480 | 248 | * OIDs can be added to a single set (around ~32000, assuming |
26022f07 VM |
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 | |
ac3d33df | 254 | * GIT_ERROR_INVALID error |
26022f07 VM |
255 | * |
256 | * @param os a `git_oid_shorten` instance | |
74f91322 | 257 | * @param text_id an OID in text form |
26022f07 VM |
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 | */ | |
74f91322 | 262 | GIT_EXTERN(int) git_oid_shorten_add(git_oid_shorten *os, const char *text_id); |
26022f07 VM |
263 | |
264 | /** | |
265 | * Free an OID shortener instance | |
932d1baf | 266 | * |
26022f07 VM |
267 | * @param os a `git_oid_shorten` instance |
268 | */ | |
0c9a5565 | 269 | GIT_EXTERN(void) git_oid_shorten_free(git_oid_shorten *os); |
26022f07 | 270 | |
c15648cb SP |
271 | /** @} */ |
272 | GIT_END_DECL | |
273 | #endif |