.. index:: single: hash_state_protocol
.. _hash_state_protocol/0:

.. rst-class:: right

**protocol**

``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)