`hash_state_protocol`

Protocol for hash functions supporting genuine incremental hash computation via an explicit, caller-driven hashing state. Unlike computing a hash from a single, fully materialized message, this protocol lets the caller feed the message to the hash function one chunk at a time (e.g. as each chunk is read from a file or a network stream), discarding each chunk as soon as it has been folded into the state. Only the current chunk and a small, bounded amount of algorithm state (for block-padded and rate-limited algorithms, a leftover buffer smaller than one block or rate) are ever resident at once, regardless of the total message length.

| Availability: | logtalk_load(hashes(loader))

| Author: Paulo Moura | Version: 1:0:0 | Date: 2026-07-16

| Compilation flags: | static

| Extends: | public :ref:`hash_protocol <hash_protocol/0>`

| Remarks: | (none)

| Inherited public predicates: | Â :ref:hash_protocol/0::hash/2 Â

.. contents:: :local: :backlinks: top

Public predicates

.. index:: new_hash_state/1 .. _hash_state_protocol/0::new_hash_state/1:

new_hash_state/1 ^^^^^^^^^^^^^^^^^^^^

Creates a fresh hashing state, equivalent to having hashed the empty message so far. The state is an opaque, algorithm-specific term; callers should only pass it to update_hash_state/3 and final_hash_state/2, never inspect or construct it directly.

| Compilation flags: | static

| Template: | new_hash_state(State) | Mode and number of proofs: | new_hash_state(--nonvar) - one

.. index:: update_hash_state/3 .. _hash_state_protocol/0::update_hash_state/3:

update_hash_state/3 ^^^^^^^^^^^^^^^^^^^^^^^

Folds one chunk of bytes into a hashing state, returning the updated state. Can be called repeatedly, once per chunk, to fold in an arbitrarily long message without ever holding more than one chunk and the (bounded-size) state in memory at the same time. The chunks do not need to be the same length, and the empty chunk is allowed and is a no-op.

| Compilation flags: | static

| Template: | update_hash_state(State,Bytes,NewState) | Mode and number of proofs: | update_hash_state(+nonvar,+list(byte),--nonvar) - one

.. index:: final_hash_state/2 .. _hash_state_protocol/0::final_hash_state/2:

final_hash_state/2 ^^^^^^^^^^^^^^^^^^^^^^

Finalizes a hashing state and returns the resulting hash, in the same representation as hash/2. The state must not be reused after finalization.

| Compilation flags: | static

| Template: | final_hash_state(State,Hash) | Mode and number of proofs: | final_hash_state(+nonvar,--atom) - one

Protected predicates

(no local declarations; see entity ancestors if any)

Private predicates

(no local declarations; see entity ancestors if any)

Operators

(none)