FilesExpand file tree

development

/

oid.h

Copy path

Blame

More file actions

Blame

More file actions

Latest commit

 

History

History

History

218 lines (196 loc) · 6.62 KB

development

/

oid.h

Copy path

Top

File metadata and controls

• Code
• Blame

218 lines (196 loc) · 6.62 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

/*

* Copyright (C) 2009-2011 the libgit2 contributors

*

* This file is part of libgit2, distributed under the GNU GPL v2 with

* a Linking Exception. For full terms see the included COPYING file.

*/

#ifndef INCLUDE_git_oid_h__

#define INCLUDE_git_oid_h__

#include "common.h"

#include "types.h"

/**

* @file git2/oid.h

* @brief Git object id routines

* @defgroup git_oid Git object id routines

* @ingroup Git

* @{

*/

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)

/** Minimum length (in number of hex characters,

* i.e. packets of 4 bits) of an oid prefix */

#define GIT_OID_MINPREFIXLEN 4

/** Unique identity of any object (commit, tree, blob, tag). */

typedef struct _git_oid git_oid;

struct _git_oid {

/** raw binary formatted id */

unsigned char id[GIT_OID_RAWSZ];

};

/**

* Parse a hex formatted object id into a git_oid.

*

* @param out oid structure the result is written into.

* @param str input 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).

* @return GIT_SUCCESS or an error code

*/

GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str);

/**

* Parse N characters of a hex formatted object id into a git_oid

*

* If N is odd, N-1 characters will be parsed instead.

* The remaining space in the git_oid will be set to zero.

*

* @param out oid structure the result is written into.

* @param str input hex string of at least size `length`

* @param length length of the input string

* @return GIT_SUCCESS or an error code

*/

GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length);

/**

* Copy an already raw oid into a git_oid structure.

*

* @param out oid structure the result is written into.

* @param raw the raw input bytes to be copied.

*/

GIT_EXTERN(void) git_oid_fromraw(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.

*

* 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 git_oid into a newly allocated c-string.

*

* @param oid the oid structure to format

* @return the c-string; NULL if memory is exhausted. Caller must

* deallocate the string with git__free().

*/

GIT_EXTERN(char *) git_oid_allocfmt(const git_oid *oid);

/**

* Format a git_oid into a buffer as a hex format c-string.

*

* If the buffer is smaller than GIT_OID_HEXSZ+1, then the resulting

* oid c-string will be truncated to n-1 characters. If there are

* any input parameter errors (out == NULL, n == 0, oid == NULL),

* then a pointer to an empty string is returned, so that the return

* value can always be printed.

*

* @param out the buffer into which the oid string is output.

* @param n the size of the out buffer.

* @param oid the oid structure to format.

* @return the out buffer pointer, assuming no input parameter

* errors, otherwise a pointer to an empty string.

*/

GIT_EXTERN(char *) git_oid_to_string(char *out, size_t n, 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.

*/

GIT_EXTERN(void) git_oid_cpy(git_oid *out, const git_oid *src);

/**

* Compare two oid structures.

*

* @param a first oid structure.

* @param b second oid structure.

* @return <0, 0, >0 if a < b, a == b, a > b.

*/

GIT_EXTERN(int) git_oid_cmp(const git_oid *a, const git_oid *b);

/**

* Compare the first 'len' hexadecimal characters (packets of 4 bits)

* of two oid structures.

*

* @param a first oid structure.

* @param b second oid structure.

* @param len the number of hex chars to compare

* @return 0 in case of a match

*/

GIT_EXTERN(int) git_oid_ncmp(const git_oid *a, const git_oid *b, unsigned int len);

/**

* Check if an oid equals an hex formatted object id.

*

* @param a oid structure.

* @param str input hex string of an object id.

* @return GIT_ENOTOID if str is not a valid hex string,

* GIT_SUCCESS in case of a match, GIT_ERROR otherwise.

*/

GIT_EXTERN(int) git_oid_streq(const git_oid *a, const char *str);

/**

* OID Shortener object

*/

typedef struct git_oid_shorten git_oid_shorten;

/**

* Create a new OID shortener.

*

* The OID shortener is used to process a list of OIDs

* in text form and return the shortest length that would

* uniquely identify all of them.

*

* E.g. look at the result of `git log --abbrev`.

*

* @param min_length The minimal length for all identifiers,

* which will be used even if shorter OIDs would still

* be unique.

* @return a `git_oid_shorten` instance, NULL if OOM

*/

git_oid_shorten *git_oid_shorten_new(size_t min_length);

/**

* Add a new OID to set of shortened OIDs and calculate

* the minimal length to uniquely identify all the OIDs in

* the set.

*

* The OID is expected to be a 40-char hexadecimal string.

* The OID is owned by the user and will not be modified

* or freed.

*

* For performance reasons, there is a hard-limit of how many

* OIDs can be added to a single set (around ~22000, assuming

* a mostly randomized distribution), which should be enough

* for any kind of program, and keeps the algorithm fast and

* memory-efficient.

*

* Attempting to add more than those OIDs will result in a

* GIT_ENOMEM error

*

* @param os a `git_oid_shorten` instance

* @param text_oid an OID in text form

* @return the minimal length to uniquely identify all OIDs

* added so far to the set; or an error code (<0) if an

* error occurs.

*/

int git_oid_shorten_add(git_oid_shorten *os, const char *text_oid);

/**

* Free an OID shortener instance

*

* @param os a `git_oid_shorten` instance

*/

void git_oid_shorten_free(git_oid_shorten *os);

/** @} */

GIT_END_DECL

#endif