git2/sys/hashsig.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_sys_hashsig_h__
0008 #define INCLUDE_sys_hashsig_h__
0009
0010 #include "git2/common.h"
0011
0012 GIT_BEGIN_DECL
0013
0014 /**
0015  * Similarity signature of arbitrary text content based on line hashes
0016  */
0017 typedef struct git_hashsig git_hashsig;
0018
0019 /**
0020  * Options for hashsig computation
0021  *
0022  * The options GIT_HASHSIG_NORMAL, GIT_HASHSIG_IGNORE_WHITESPACE,
0023  * GIT_HASHSIG_SMART_WHITESPACE are exclusive and should not be combined.
0024  */
0025 typedef enum {
0026     /**
0027      * Use all data
0028      */
0029     GIT_HASHSIG_NORMAL = 0,
0030
0031     /**
0032      * Ignore whitespace
0033      */
0034     GIT_HASHSIG_IGNORE_WHITESPACE = (1 << 0),
0035
0036     /**
0037      * Ignore \r and all space after \n
0038      */
0039     GIT_HASHSIG_SMART_WHITESPACE = (1 << 1),
0040
0041     /**
0042      * Allow hashing of small files
0043      */
0044     GIT_HASHSIG_ALLOW_SMALL_FILES = (1 << 2)
0045 } git_hashsig_option_t;
0046
0047 /**
0048  * Compute a similarity signature for a text buffer
0049  *
0050  * If you have passed the option GIT_HASHSIG_IGNORE_WHITESPACE, then the
0051  * whitespace will be removed from the buffer while it is being processed,
0052  * modifying the buffer in place. Sorry about that!
0053  *
0054  * @param out The computed similarity signature.
0055  * @param buf The input buffer.
0056  * @param buflen The input buffer size.
0057  * @param opts The signature computation options (see above).
0058  * @return 0 on success, GIT_EBUFS if the buffer doesn't contain enough data to
0059  * compute a valid signature (unless GIT_HASHSIG_ALLOW_SMALL_FILES is set), or
0060  * error code.
0061  */
0062 GIT_EXTERN(int) git_hashsig_create(
0063     git_hashsig **out,
0064     const char *buf,
0065     size_t buflen,
0066     git_hashsig_option_t opts);
0067
0068 /**
0069  * Compute a similarity signature for a text file
0070  *
0071  * This walks through the file, only loading a maximum of 4K of file data at
0072  * a time. Otherwise, it acts just like `git_hashsig_create`.
0073  *
0074  * @param out The computed similarity signature.
0075  * @param path The path to the input file.
0076  * @param opts The signature computation options (see above).
0077  * @return 0 on success, GIT_EBUFS if the buffer doesn't contain enough data to
0078  * compute a valid signature (unless GIT_HASHSIG_ALLOW_SMALL_FILES is set), or
0079  * error code.
0080  */
0081 GIT_EXTERN(int) git_hashsig_create_fromfile(
0082     git_hashsig **out,
0083     const char *path,
0084     git_hashsig_option_t opts);
0085
0086 /**
0087  * Release memory for a content similarity signature
0088  *
0089  * @param sig The similarity signature to free.
0090  */
0091 GIT_EXTERN(void) git_hashsig_free(git_hashsig *sig);
0092
0093 /**
0094  * Measure similarity score between two similarity signatures
0095  *
0096  * @param a The first similarity signature to compare.
0097  * @param b The second similarity signature to compare.
0098  * @return [0 to 100] on success as the similarity score, or error code.
0099  */
0100 GIT_EXTERN(int) git_hashsig_compare(
0101     const git_hashsig *a,
0102     const git_hashsig *b);
0103
0104 GIT_END_DECL
0105
0106 #endif