include/git2/oid.h - third_party/libgit2 - Git at Google

 /*
  * Copyright (C) the libgit2 contributors. All rights reserved.
  *
  * 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 {
 	/** raw binary formatted id */
 	unsigned char id[GIT_OID_RAWSZ];
 } git_oid;

 /**
  * 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 0 or an error code
  */
 GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str);

 /**
  * Parse a hex formatted null-terminated string into a git_oid.
  *
  * @param out oid structure the result is written into.
  * @param str input hex string; must be null-terminated.
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str);

 /**
  * Parse N characters of a hex formatted object id into a git_oid.
  *
  * If N is odd, the last byte's high nibble will be read in and the
  * low nibble 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 0 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 out 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 id oid structure to format.
  */
 GIT_EXTERN(void) git_oid_fmt(char *out, const git_oid *id);

 /**
  * Format a git_oid into a partial hex string.
  *
  * @param out output hex string; you say how many bytes to write.
  *		If the number of bytes is > GIT_OID_HEXSZ, extra bytes
  *		will be zeroed; if not, a '\0' terminator is NOT added.
  * @param n number of characters to write into out string
  * @param id oid structure to format.
  */
 GIT_EXTERN(void) git_oid_nfmt(char *out, size_t n, const git_oid *id);

 /**
  * Format a git_oid into a loose-object path string.
  *
  * The resulting string is "aa/...", where "aa" is the first two
  * hex digits of the oid and "..." is the remaining 38 digits.
  *
  * @param out 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 id oid structure to format.
  */
 GIT_EXTERN(void) git_oid_pathfmt(char *out, const git_oid *id);

 /**
  * Format a git_oid into a statically allocated c-string.
  *
  * The c-string is owned by the library and should not be freed
  * by the user. If libgit2 is built with thread support, the string
  * will be stored in TLS (i.e. one buffer per thread) to allow for
  * concurrent calls of the function.
  *
  * @param oid The oid structure to format
  * @return the c-string
  */
 GIT_EXTERN(char *) git_oid_tostr_s(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 (but will still be
  * NUL-byte terminated).
  *
  * 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 id 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_tostr(char *out, size_t n, const git_oid *id);

 /**
  * 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 two oid structures for equality
  *
  * @param a first oid structure.
  * @param b second oid structure.
  * @return true if equal, false otherwise
  */
 GIT_EXTERN(int) git_oid_equal(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, size_t len);

 /**
  * Check if an oid equals an hex formatted object id.
  *
  * @param id oid structure.
  * @param str input hex string of an object id.
  * @return 0 in case of a match, -1 otherwise.
  */
 GIT_EXTERN(int) git_oid_streq(const git_oid *id, const char *str);

 /**
  * Compare an oid to an hex formatted object id.
  *
  * @param id oid structure.
  * @param str input hex string of an object id.
  * @return -1 if str is not valid, <0 if id sorts before str,
  *         0 if id matches str, >0 if id sorts after str.
  */
 GIT_EXTERN(int) git_oid_strcmp(const git_oid *id, const char *str);

 /**
  * Check is an oid is all zeros.
  *
  * @return 1 if all zeros, 0 otherwise.
  */
 GIT_EXTERN(int) git_oid_iszero(const git_oid *id);

 /**
  * 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_EXTERN(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 ~32000, 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
  * GITERR_INVALID error
  *
  * @param os a `git_oid_shorten` instance
  * @param text_id 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.
  */
 GIT_EXTERN(int) git_oid_shorten_add(git_oid_shorten *os, const char *text_id);

 /**
  * Free an OID shortener instance
  *
  * @param os a `git_oid_shorten` instance
  */
 GIT_EXTERN(void) git_oid_shorten_free(git_oid_shorten *os);

 /** @} */
 GIT_END_DECL
 #endif
	/*
	* Copyright (C) the libgit2 contributors. All rights reserved.
	*
	* 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 {
	/** raw binary formatted id */
	unsigned char id[GIT_OID_RAWSZ];
	} git_oid;

	/**
	* 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 0 or an error code
	*/
	GIT_EXTERN(int) git_oid_fromstr(git_oid out, const char str);

	/**
	* Parse a hex formatted null-terminated string into a git_oid.
	*
	* @param out oid structure the result is written into.
	* @param str input hex string; must be null-terminated.
	* @return 0 or an error code
	*/
	GIT_EXTERN(int) git_oid_fromstrp(git_oid out, const char str);

	/**
	* Parse N characters of a hex formatted object id into a git_oid.
	*
	* If N is odd, the last byte's high nibble will be read in and the
	* low nibble 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 0 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 out 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 id oid structure to format.
	*/
	GIT_EXTERN(void) git_oid_fmt(char out, const git_oid id);

	/**
	* Format a git_oid into a partial hex string.
	*
	* @param out output hex string; you say how many bytes to write.
	* If the number of bytes is > GIT_OID_HEXSZ, extra bytes
	* will be zeroed; if not, a '\0' terminator is NOT added.
	* @param n number of characters to write into out string
	* @param id oid structure to format.
	*/
	GIT_EXTERN(void) git_oid_nfmt(char out, size_t n, const git_oid id);

	/**
	* Format a git_oid into a loose-object path string.
	*
	* The resulting string is "aa/...", where "aa" is the first two
	* hex digits of the oid and "..." is the remaining 38 digits.
	*
	* @param out 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 id oid structure to format.
	*/
	GIT_EXTERN(void) git_oid_pathfmt(char out, const git_oid id);

	/**
	* Format a git_oid into a statically allocated c-string.
	*
	* The c-string is owned by the library and should not be freed
	* by the user. If libgit2 is built with thread support, the string
	* will be stored in TLS (i.e. one buffer per thread) to allow for
	* concurrent calls of the function.
	*
	* @param oid The oid structure to format
	* @return the c-string
	*/
	GIT_EXTERN(char ) git_oid_tostr_s(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 (but will still be
	* NUL-byte terminated).
	*
	* 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 id 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_tostr(char out, size_t n, const git_oid *id);

	/**
	* 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 two oid structures for equality
	*
	* @param a first oid structure.
	* @param b second oid structure.
	* @return true if equal, false otherwise
	*/
	GIT_EXTERN(int) git_oid_equal(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, size_t len);

	/**
	* Check if an oid equals an hex formatted object id.
	*
	* @param id oid structure.
	* @param str input hex string of an object id.
	* @return 0 in case of a match, -1 otherwise.
	*/
	GIT_EXTERN(int) git_oid_streq(const git_oid id, const char str);

	/**
	* Compare an oid to an hex formatted object id.
	*
	* @param id oid structure.
	* @param str input hex string of an object id.
	* @return -1 if str is not valid, <0 if id sorts before str,
	* 0 if id matches str, >0 if id sorts after str.
	*/
	GIT_EXTERN(int) git_oid_strcmp(const git_oid id, const char str);

	/**
	* Check is an oid is all zeros.
	*
	* @return 1 if all zeros, 0 otherwise.
	*/
	GIT_EXTERN(int) git_oid_iszero(const git_oid *id);

	/**
	* 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_EXTERN(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 ~32000, 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
	* GITERR_INVALID error
	*
	* @param os a `git_oid_shorten` instance
	* @param text_id 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.
	*/
	GIT_EXTERN(int) git_oid_shorten_add(git_oid_shorten os, const char text_id);

	/**
	* Free an OID shortener instance
	*
	* @param os a `git_oid_shorten` instance
	*/
	GIT_EXTERN(void) git_oid_shorten_free(git_oid_shorten *os);

	/** @} */
	GIT_END_DECL
	#endif