chksum_hash_core/
lib.rs

1//! Core traits and functions for batch and stream hash computation.
2//!
3//! # Setup
4//!
5//! To use this crate, add the following entry to your `Cargo.toml` file in the `dependencies` section:
6//!
7//! ```toml
8//! [dependencies]
9//! chksum-hash-core = "0.0.0"
10//! ```
11//!
12//! Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand:
13//!
14//! ```sh
15//! cargo add chksum-hash-core
16//! ```     
17//!
18//! # Example Crates
19//!
20//! For implementation-specific examples, refer to the source code of the following crates:
21//!
22//! * [`chksum-hash-md5`](https://docs.rs/chksum-hash-md5/)
23//! * [`chksum-hash-sha1`](https://docs.rs/chksum-hash-sha1/)
24//! * [`chksum-hash-sha2`](https://docs.rs/chksum-hash-sha2/)
25//!     * [`chksum-hash-sha2-224`](https://docs.rs/chksum-hash-sha2-224)
26//!     * [`chksum-hash-sha2-256`](https://docs.rs/chksum-hash-sha2-256)
27//!     * [`chksum-hash-sha2-384`](https://docs.rs/chksum-hash-sha2-384)
28//!     * [`chksum-hash-sha2-512`](https://docs.rs/chksum-hash-sha2-512)
29//!
30//! # License
31//!
32//! This crate is licensed under the MIT License.
33
34#![cfg_attr(docsrs, feature(doc_auto_cfg))]
35#![forbid(unsafe_code)]
36
37use std::fmt::{Display, LowerHex, UpperHex};
38
39/// Creates a default hash.
40#[must_use]
41pub fn default<U>() -> U
42where
43    U: Update,
44{
45    Default::default()
46}
47
48/// Computes the hash of the given input.
49pub fn hash<U>(data: impl AsRef<[u8]>) -> U::Digest
50where
51    U: Update,
52{
53    let mut hash = default::<U>();
54    hash.update(data);
55    hash.digest()
56}
57
58/// A trait for hash objects in an in-progress state.
59///
60/// This trait defines the common interface for hash objects that are in the process
61/// of being updated with new data. Implementations of this trait typically maintain
62/// an internal state that evolves as new data is added.
63pub trait Update: Default {
64    /// The type representing the digest produced by finalizing the hash.
65    type Digest: Digest;
66
67    /// The type representing the finalized state, which can be converted into a digest.
68    type Finalize: Finalize<Digest = Self::Digest, Update = Self>;
69
70    /// Updates the hash state with an input data.
71    fn update(&mut self, data: impl AsRef<[u8]>);
72
73    /// Finalizes the hash state.
74    fn finalize(&self) -> Self::Finalize;
75
76    /// Resets the hash state to its initial state.
77    fn reset(&mut self);
78
79    /// Produces the hash digest using internal finalization.
80    fn digest(&self) -> Self::Digest {
81        self.finalize().digest()
82    }
83}
84
85/// A trait for hash objects in a finalized state.
86///
87/// This trait defines the common interface for hash objects that have been finalized,
88/// producing the final digest. Implementations of this trait typically provide methods
89/// for obtaining the final digest and resetting the state to perform additional hashing.
90pub trait Finalize {
91    /// The type representing the digest produced by finalizing the hash.
92    type Digest: Digest;
93
94    /// The type representing the in-progress state, which can be finalized again.
95    type Update: Update;
96
97    /// Produces the final digest.
98    fn digest(&self) -> Self::Digest;
99
100    /// Resets the finalized state to the in-progress state.
101    fn reset(&self) -> Self::Update;
102}
103
104/// A trait for hash digests.
105///
106/// This trait defines the common interface for hash digests, providing methods for
107/// converting the digest into various representations.
108pub trait Digest: Display {
109    /// Returns the digest as a byte slice.
110    fn as_bytes(&self) -> &[u8]
111    where
112        Self: AsRef<[u8]>,
113    {
114        self.as_ref()
115    }
116
117    /// Returns the digest as a lowercase hexadecimal string.
118    fn to_hex_lowercase(&self) -> String
119    where
120        Self: LowerHex,
121    {
122        format!("{self:x}")
123    }
124
125    /// Returns the digest as an uppercase hexadecimal string.
126    fn to_hex_uppercase(&self) -> String
127    where
128        Self: UpperHex,
129    {
130        format!("{self:X}")
131    }
132}
chksum_hash_core/lib.rs

chksum_hash_core/
lib.rs
