Algorithms as values¶

Any algorithm through one call, selected by a ph_algorithm_t or its name.

Types¶

ph_algorithm_t¶

Every hash algorithm, as a value – for code that picks the algorithm at run time (a binding, a configuration file, a database column) instead of calling one of the ph_compute_* functions by name.

The values are contiguous from 0 to PH_ALGORITHM_COUNT - 1, so for (a = 0; a <PH_ALGORITHM_COUNT; a++) visits every algorithm. For the four uint64_t algorithms the matching ph_hash_flags_t bit is 1u << value: PH_HASH_DHASH == 1u \<\< PH_ALGO_DHASH. New algorithms are appended; existing values never change.

Constants¶

PH_ALGORITHM_COUNT¶

#define PH_ALGORITHM_COUNT 9

Number of ph_algorithm_t values: every algorithm is in [0, PH_ALGORITHM_COUNT).

Functions¶

ph_compute_digest()¶

ph_error_t ph_compute_digest(
    ph_context_t *ctx,
    ph_algorithm_t algo,
    ph_digest_t *out_digest);

nodiscard · returns ph_error_t

Computes any algorithm's hash into a digest.

Exactly the result of the algorithm's own ph_compute_* function, same errors included (PH_ERR_EMPTY_IMAGE, PH_ERR_REQUIRES_COLOR, ...). The four uint64_t algorithms come back as an 8-byte PH_DIGEST_KIND_BITS digest holding the hash most significant byte first – the order ph_hash_to_hex() writes – so ph_hamming_distance_digest() on two of them equals ph_hamming_distance() on the two hashes, and every algorithm can be stored and compared through the digest functions alone.

Parameters

Returns As the algorithm's ph_compute_* function – PH_SUCCESS, PH_ERR_INVALID_ARGUMENT, PH_ERR_EMPTY_IMAGE, PH_ERR_REQUIRES_COLOR or PH_ERR_ALLOCATION_FAILED – and PH_ERR_INVALID_ARGUMENT for an algo that is not a ph_algorithm_t value.

Used in digest_and_metrics.c

Explained in BMH — Block Mean Hash · ColorHash — Color Histogram · ColorMoments — Color Moments · Comparing hashes · mHash — Marr–Hildreth Hash · Radial — Radial Variance Hash

ph_digest_info()¶

ph_error_t ph_digest_info(
    const ph_context_t *ctx,
    ph_algorithm_t algo,
    size_t *out_size,
    ph_digest_kind_t *out_kind);

nodiscard · returns ph_error_t

Tells what digest an algorithm produces, without an image and without computing anything: its size in bytes and its kind (which decides the comparison metric).

The answer comes from the same code that sets the size and kind of every computed digest, so it cannot disagree with ph_compute_digest() or the ph_compute_* functions. Only BMH's size depends on the configuration (ph_context_set_block_params()); the others are fixed.

Parameters

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for an algo that is not a ph_algorithm_t value (nothing is written then).

Used in configure.c

Explained in Configuring a context

ph_algorithm_name()¶

const char *ph_algorithm_name(ph_algorithm_t algo);

returns const char *

The algorithm's stable lowercase name: "ahash", "dhash", "phash", "whash", "bmh", "mhash", "radial", "color_hash", "color_moments".

Returns A static string, never NULL; "unknown" for a value that is not an algorithm.

Used in digest_and_metrics.c · find_duplicates.c

Explained in Storing and searching hashes

ph_algorithm_from_name()¶

ph_error_t ph_algorithm_from_name(const char *name, ph_algorithm_t *out_algo);

nodiscard · returns ph_error_t

The inverse of ph_algorithm_name(): exact, lowercase match.

Parameters

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for a NULL argument or a name that is not one ph_algorithm_name() returns.

Explained in Storing and searching hashes