nixos/nix
1
1
Fork 0
mirror of https://github.com/NixOS/nix.git synced 2025-11-14 06:22:42 +01:00
Code Activity

Extend internal API docs, part 2

Browse source 
Picking up from #8111.

Co-authored-by: Eelco Dolstra <edolstra@gmail.com>
This commit is contained in:
John Ericson 2023-03-26 21:12:25 -04:00
parent 8ae9d66940
commit abd5e7dec0
32 changed files with 640 additions and 359 deletions
Download patch file Download diff file Expand all files Collapse all files

106
src/libutil/hash.hh
View file

@ -33,62 +33,86 @@ struct Hash
HashType type;
/* Create a zero-filled hash object. */
/**
* Create a zero-filled hash object.
*/
Hash(HashType type);
/* Parse the hash from a string representation in the format
"[<type>:]<base16|base32|base64>" or "<type>-<base64>" (a
Subresource Integrity hash expression). If the 'type' argument
is not present, then the hash type must be specified in the
string. */
/**
* Parse the hash from a string representation in the format
* "[<type>:]<base16|base32|base64>" or "<type>-<base64>" (a
* Subresource Integrity hash expression). If the 'type' argument
* is not present, then the hash type must be specified in the
* string.
*/
static Hash parseAny(std::string_view s, std::optional<HashType> type);
/* Parse a hash from a string representation like the above, except the
type prefix is mandatory is there is no separate arguement. */
/**
* Parse a hash from a string representation like the above, except the
* type prefix is mandatory is there is no separate arguement.
*/
static Hash parseAnyPrefixed(std::string_view s);
/* Parse a plain hash that musst not have any prefix indicating the type.
The type is passed in to disambiguate. */
/**
* Parse a plain hash that musst not have any prefix indicating the type.
* The type is passed in to disambiguate.
*/
static Hash parseNonSRIUnprefixed(std::string_view s, HashType type);
static Hash parseSRI(std::string_view original);
private:
/* The type must be provided, the string view must not include <type>
prefix. `isSRI` helps disambigate the various base-* encodings. */
/**
* The type must be provided, the string view must not include <type>
* prefix. `isSRI` helps disambigate the various base-* encodings.
*/
Hash(std::string_view s, HashType type, bool isSRI);
public:
/* Check whether two hash are equal. */
/**
* Check whether two hash are equal.
*/
bool operator == (const Hash & h2) const;
/* Check whether two hash are not equal. */
/**
* Check whether two hash are not equal.
*/
bool operator != (const Hash & h2) const;
/* For sorting. */
/**
* For sorting.
*/
bool operator < (const Hash & h) const;
/* Returns the length of a base-16 representation of this hash. */
/**
* Returns the length of a base-16 representation of this hash.
*/
size_t base16Len() const
{
return hashSize * 2;
}
/* Returns the length of a base-32 representation of this hash. */
/**
* Returns the length of a base-32 representation of this hash.
*/
size_t base32Len() const
{
return (hashSize * 8 - 1) / 5 + 1;
}
/* Returns the length of a base-64 representation of this hash. */
/**
* Returns the length of a base-64 representation of this hash.
*/
size_t base64Len() const
{
return ((4 * hashSize / 3) + 3) & ~3;
}
/* Return a string representation of the hash, in base-16, base-32
or base-64. By default, this is prefixed by the hash type
(e.g. "sha256:"). */
/**
* Return a string representation of the hash, in base-16, base-32
* or base-64. By default, this is prefixed by the hash type
* (e.g. "sha256:").
*/
std::string to_string(Base base, bool includeType) const;
std::string gitRev() const
@ -104,35 +128,53 @@ public:
static Hash dummy;
};
/* Helper that defaults empty hashes to the 0 hash. */
/**
* Helper that defaults empty hashes to the 0 hash.
*/
Hash newHashAllowEmpty(std::string_view hashStr, std::optional<HashType> ht);
/* Print a hash in base-16 if it's MD5, or base-32 otherwise. */
/**
* Print a hash in base-16 if it's MD5, or base-32 otherwise.
*/
std::string printHash16or32(const Hash & hash);
/* Compute the hash of the given string. */
/**
* Compute the hash of the given string.
*/
Hash hashString(HashType ht, std::string_view s);
/* Compute the hash of the given file. */
/**
* Compute the hash of the given file.
*/
Hash hashFile(HashType ht, const Path & path);
/* Compute the hash of the given path. The hash is defined as
(essentially) hashString(ht, dumpPath(path)). */
/**
* Compute the hash of the given path. The hash is defined as
* (essentially) hashString(ht, dumpPath(path)).
*/
typedef std::pair<Hash, uint64_t> HashResult;
HashResult hashPath(HashType ht, const Path & path,
PathFilter & filter = defaultPathFilter);
/* Compress a hash to the specified number of bytes by cyclically
XORing bytes together. */
/**
* Compress a hash to the specified number of bytes by cyclically
* XORing bytes together.
*/
Hash compressHash(const Hash & hash, unsigned int newSize);
/* Parse a string representing a hash type. */
/**
* Parse a string representing a hash type.
*/
HashType parseHashType(std::string_view s);
/* Will return nothing on parse error */
/**
* Will return nothing on parse error
*/
std::optional<HashType> parseHashTypeOpt(std::string_view s);
/* And the reverse. */
/**
* And the reverse.
*/
std::string_view printHashType(HashType ht);