chksum_sha2_256/
lib.rs

1//! This crate provides an implementation of the SHA-2 256 hash function with a straightforward interface for computing digests of bytes, files, directories, and more.
2//!
3//! For a low-level interface, you can explore the [`chksum_hash_sha2_256`] crate.
4//!
5//! # Setup
6//!
7//! To use this crate, add the following entry to your `Cargo.toml` file in the `dependencies` section:
8//!
9//! ```toml
10//! [dependencies]
11//! chksum-sha2-256 = "0.1.0"
12//! ```
13//!
14//! Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand:
15//!
16//! ```sh
17//! cargo add chksum-sha2-256
18//! ```     
19//!
20//! # Usage
21//!
22//! Use the [`chksum`] function to calculate digest of file, directory and so on.
23//!
24//! ```rust
25//! # use std::path::Path;
26//! use std::fs::File;
27//!
28//! # use chksum_sha2_256::Result;
29//! use chksum_sha2_256 as sha2_256;
30//!
31//! # fn wrapper(path: &Path) -> Result<()> {
32//! let file = File::open(path)?;
33//! let digest = sha2_256::chksum(file)?;
34//! assert_eq!(
35//!     digest.to_hex_lowercase(),
36//!     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
37//! );
38//! # Ok(())
39//! # }
40//! ```
41//!
42//! ## Asynchronous Runtime
43//!
44//! Use the [`async_chksum`] function to calculate digest of file, directory and so on.
45//!
46//! ```rust
47//! # #[cfg(feature = "async-runtime-tokio")]
48//! # {
49//! # use std::path::Path;
50//! # use chksum_sha2_256::Result;
51//! use chksum_sha2_256 as sha2_256;
52//! use tokio::fs::File;
53//!
54//! # async fn wrapper(path: &Path) -> Result<()> {
55//! let file = File::open(path).await?;
56//! let digest = sha2_256::async_chksum(file).await?;
57//! assert_eq!(
58//!     digest.to_hex_lowercase(),
59//!     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
60//! );
61//! # Ok(())
62//! # }
63//! # }
64//! ```
65//!
66//! # Input Types
67//!
68//! ## Bytes
69//!
70//! ### Array
71//!
72//! ```rust
73//! # use chksum_sha2_256::Result;
74//! use chksum_sha2_256 as sha2_256;
75//!
76//! # fn wrapper() -> Result<()> {
77//! let data = [0, 1, 2, 3];
78//! let digest = sha2_256::chksum(data)?;
79//! assert_eq!(
80//!     digest.to_hex_lowercase(),
81//!     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
82//! );
83//! # Ok(())
84//! # }
85//! ```
86//!
87//! ### Vec
88//!
89//! ```rust
90//! # use chksum_sha2_256::Result;
91//! use chksum_sha2_256 as sha2_256;
92//!
93//! # fn wrapper() -> Result<()> {
94//! let data = vec![0, 1, 2, 3];
95//! let digest = sha2_256::chksum(data)?;
96//! assert_eq!(
97//!     digest.to_hex_lowercase(),
98//!     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
99//! );
100//! # Ok(())
101//! # }
102//! ```
103//!
104//! ### Slice
105//!
106//! ```rust
107//! # use chksum_sha2_256::Result;
108//! use chksum_sha2_256 as sha2_256;
109//!
110//! # fn wrapper() -> Result<()> {
111//! let data = &[0, 1, 2, 3];
112//! let digest = sha2_256::chksum(data)?;
113//! assert_eq!(
114//!     digest.to_hex_lowercase(),
115//!     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
116//! );
117//! # Ok(())
118//! # }
119//! ```
120//!
121//! ## Strings
122//!
123//! ### str
124//!
125//! ```rust
126//! # use chksum_sha2_256::Result;
127//! use chksum_sha2_256 as sha2_256;
128//!
129//! # fn wrapper() -> Result<()> {
130//! let data = "&str";
131//! let digest = sha2_256::chksum(data)?;
132//! assert_eq!(
133//!     digest.to_hex_lowercase(),
134//!     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
135//! );
136//! # Ok(())
137//! # }
138//! ```
139//!
140//! ### String
141//!
142//! ```rust
143//! # use chksum_sha2_256::Result;
144//! use chksum_sha2_256 as sha2_256;
145//!
146//! # fn wrapper() -> Result<()> {
147//! let data = String::from("String");
148//! let digest = sha2_256::chksum(data)?;
149//! assert_eq!(
150//!     digest.to_hex_lowercase(),
151//!     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
152//! );
153//! # Ok(())
154//! # }
155//! ```
156//!
157//! ## File
158//!
159//! ```rust
160//! # use std::path::Path;
161//! use std::fs::File;
162//!
163//! # use chksum_sha2_256::Result;
164//! use chksum_sha2_256 as sha2_256;
165//!
166//! # fn wrapper(path: &Path) -> Result<()> {
167//! let file = File::open(path)?;
168//! let digest = sha2_256::chksum(file)?;
169//! assert_eq!(
170//!     digest.to_hex_lowercase(),
171//!     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
172//! );
173//! # Ok(())
174//! # }
175//! ```
176//!
177//! ## Directory
178//!
179//! ```rust
180//! # use std::path::Path;
181//! use std::fs::read_dir;
182//!
183//! # use chksum_sha2_256::Result;
184//! use chksum_sha2_256 as sha2_256;
185//!
186//! # fn wrapper(path: &Path) -> Result<()> {
187//! let readdir = read_dir(path)?;
188//! let digest = sha2_256::chksum(readdir)?;
189//! assert_eq!(
190//!     digest.to_hex_lowercase(),
191//!     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
192//! );
193//! # Ok(())
194//! # }
195//! ```
196//!
197//! ## Path
198//!
199//! ```rust
200//! # use std::path::Path;
201//! use std::path::PathBuf;
202//!
203//! # use chksum_sha2_256::Result;
204//! use chksum_sha2_256 as sha2_256;
205//!
206//! # fn wrapper(path: &Path) -> Result<()> {
207//! let path = PathBuf::from(path);
208//! let digest = sha2_256::chksum(path)?;
209//! assert_eq!(
210//!     digest.to_hex_lowercase(),
211//!     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
212//! );
213//! # Ok(())
214//! # }
215//! ```
216//!
217//! ## Standard Input
218//!
219//! ```rust
220//! use std::io::stdin;
221//!
222//! # use chksum_sha2_256::Result;
223//! use chksum_sha2_256 as sha2_256;
224//!
225//! # fn wrapper() -> Result<()> {
226//! let stdin = stdin();
227//! let digest = sha2_256::chksum(stdin)?;
228//! assert_eq!(
229//!     digest.to_hex_lowercase(),
230//!     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
231//! );
232//! # Ok(())
233//! # }
234//! ```
235//!
236//! # Features
237//!
238//! Cargo features are utilized to enable extra options.
239//!
240//! * `reader` enables the [`reader`] module with the [`Reader`] struct.
241//! * `writer` enables the [`writer`] module with the [`Writer`] struct.
242//!
243//! By default, neither of these features is enabled.
244//!
245//! To customize your setup, disable the default features and enable only those that you need in your `Cargo.toml` file:
246//!
247//! ```toml
248//! [dependencies]
249//! chksum-sha2-256 = { version = "0.1.0", features = ["reader", "writer"] }
250//! ```
251//!
252//! Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand:
253//!
254//! ```shell
255//! cargo add chksum-sha2-256 --features reader,writer
256//! ```
257//!
258//! ## Asynchronous Runtime
259//!
260//! * `async-runtime-tokio`: Enables async interface for Tokio runtime.
261//!
262//! By default, neither of these features is enabled.
263//!
264//! # License
265//!
266//! This crate is licensed under the MIT License.
267
268#![cfg_attr(docsrs, feature(doc_auto_cfg))]
269#![forbid(unsafe_code)]
270
271#[cfg(feature = "reader")]
272pub mod reader;
273#[cfg(feature = "writer")]
274pub mod writer;
275
276use std::fmt::{self, Display, Formatter, LowerHex, UpperHex};
277
278use chksum_core as core;
279#[cfg(feature = "async-runtime-tokio")]
280#[doc(no_inline)]
281pub use chksum_core::AsyncChksumable;
282#[doc(no_inline)]
283pub use chksum_core::{Chksumable, Error, Hash, Hashable, Result};
284#[doc(no_inline)]
285pub use chksum_hash_sha2_256 as hash;
286
287#[cfg(all(feature = "reader", feature = "async-runtime-tokio"))]
288#[doc(inline)]
289pub use crate::reader::AsyncReader;
290#[cfg(feature = "reader")]
291#[doc(inline)]
292pub use crate::reader::Reader;
293#[cfg(all(feature = "writer", feature = "async-runtime-tokio"))]
294#[doc(inline)]
295pub use crate::writer::AsyncWriter;
296#[cfg(feature = "writer")]
297#[doc(inline)]
298pub use crate::writer::Writer;
299
300/// Creates a new hash.
301///
302/// # Example
303///
304/// ```rust
305/// use chksum_sha2_256 as sha2_256;
306///
307/// let mut hash = sha2_256::new();
308/// hash.update(b"example data");
309/// let digest = hash.digest();
310/// assert_eq!(
311///     digest.to_hex_lowercase(),
312///     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
313/// );
314/// ```
315#[must_use]
316pub fn new() -> SHA2_256 {
317    SHA2_256::new()
318}
319
320/// Creates a default hash.
321///
322/// # Example
323///
324/// ```rust
325/// use chksum_sha2_256 as sha2_256;
326///
327/// let mut hash = sha2_256::default();
328/// hash.update(b"example data");
329/// let digest = hash.digest();
330/// assert_eq!(
331///     digest.to_hex_lowercase(),
332///     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
333/// );
334/// ```
335#[must_use]
336pub fn default() -> SHA2_256 {
337    core::default()
338}
339
340/// Computes the hash of the given input.
341///
342/// # Example
343///
344/// ```rust
345/// use chksum_sha2_256 as sha2_256;
346///
347/// let data = b"example data";
348/// let digest = sha2_256::hash(data);
349/// assert_eq!(
350///     digest.to_hex_lowercase(),
351///     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
352/// );
353/// ```
354pub fn hash(data: impl core::Hashable) -> Digest {
355    core::hash::<SHA2_256>(data)
356}
357
358/// Computes the hash of the given input.
359///
360/// # Example
361///
362/// ```rust
363/// use chksum_sha2_256 as sha2_256;
364///
365/// let data = b"example data";
366/// if let Ok(digest) = sha2_256::chksum(data) {
367///     assert_eq!(
368///         digest.to_hex_lowercase(),
369///         "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
370///     );
371/// }
372/// ```
373pub fn chksum(data: impl core::Chksumable) -> Result<Digest> {
374    core::chksum::<SHA2_256>(data)
375}
376
377/// Computes the hash of the given input.
378///
379/// # Example
380///
381/// ```rust
382/// use chksum_sha2_256 as sha2_256;
383///
384/// # async fn wrapper() {
385/// let data = b"example data";
386/// if let Ok(digest) = sha2_256::async_chksum(data).await {
387///     assert_eq!(
388///         digest.to_hex_lowercase(),
389///         "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
390///     );
391/// }
392/// # }
393/// ```
394#[cfg(feature = "async-runtime-tokio")]
395pub async fn async_chksum(data: impl core::AsyncChksumable) -> Result<Digest> {
396    core::async_chksum::<SHA2_256>(data).await
397}
398
399/// The SHA-2 256 hash instance.
400#[derive(Clone, Debug, Default, PartialEq, Eq)]
401pub struct SHA2_256 {
402    inner: hash::Update,
403}
404
405impl SHA2_256 {
406    /// Calculates the hash digest of an input data.
407    ///
408    /// # Example
409    ///
410    /// ```rust
411    /// use chksum_sha2_256::SHA2_256;
412    ///
413    /// let data = b"example data";
414    /// let digest = SHA2_256::hash(data);
415    /// assert_eq!(
416    ///     digest.to_hex_lowercase(),
417    ///     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
418    /// );
419    /// ```
420    #[must_use]
421    pub fn hash<T>(data: T) -> Digest
422    where
423        T: AsRef<[u8]>,
424    {
425        let mut hash = Self::new();
426        hash.update(data);
427        hash.digest()
428    }
429
430    /// Creates a new hash.
431    ///
432    /// # Example
433    ///
434    /// ```rust
435    /// use chksum_sha2_256::SHA2_256;
436    ///
437    /// let mut hash = SHA2_256::new();
438    /// hash.update(b"example data");
439    /// let digest = hash.digest();
440    /// assert_eq!(
441    ///     digest.to_hex_lowercase(),
442    ///     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
443    /// );
444    /// ```
445    #[must_use]
446    pub fn new() -> Self {
447        let inner = hash::Update::new();
448        Self { inner }
449    }
450
451    /// Updates the hash state with an input data.
452    ///
453    /// # Example
454    ///
455    /// ```rust
456    /// use chksum_sha2_256::SHA2_256;
457    ///
458    /// let mut hash = SHA2_256::new();
459    /// hash.update(b"example");
460    /// hash.update(" ");
461    /// hash.update("data");
462    /// let digest = hash.digest();
463    /// assert_eq!(
464    ///     digest.to_hex_lowercase(),
465    ///     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
466    /// );
467    /// ```
468    pub fn update<T>(&mut self, data: T)
469    where
470        T: AsRef<[u8]>,
471    {
472        self.inner.update(data);
473    }
474
475    /// Resets the hash state to its initial state.
476    ///
477    /// # Example
478    ///
479    /// ```rust
480    /// use chksum_sha2_256::SHA2_256;
481    ///
482    /// let mut hash = SHA2_256::new();
483    /// hash.update(b"example data");
484    /// hash.reset();
485    /// let digest = hash.digest();
486    /// assert_eq!(
487    ///     digest.to_hex_lowercase(),
488    ///     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
489    /// );
490    /// ```
491    pub fn reset(&mut self) {
492        self.inner.reset();
493    }
494
495    /// Produces the hash digest.
496    ///
497    /// # Example
498    ///
499    /// ```
500    /// use chksum_sha2_256::SHA2_256;
501    ///
502    /// let mut hash = SHA2_256::new();
503    /// let digest = hash.digest();
504    /// assert_eq!(
505    ///     digest.to_hex_lowercase(),
506    ///     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
507    /// );
508    /// ```
509    #[must_use]
510    pub fn digest(&self) -> Digest {
511        self.inner.digest().into()
512    }
513}
514
515impl core::Hash for SHA2_256 {
516    type Digest = Digest;
517
518    fn update<T>(&mut self, data: T)
519    where
520        T: AsRef<[u8]>,
521    {
522        self.update(data);
523    }
524
525    fn reset(&mut self) {
526        self.reset();
527    }
528
529    fn digest(&self) -> Self::Digest {
530        self.digest()
531    }
532}
533
534/// A hash digest.
535pub struct Digest(hash::Digest);
536
537impl Digest {
538    /// Creates a new digest.
539    #[must_use]
540    pub const fn new(digest: [u8; hash::DIGEST_LENGTH_BYTES]) -> Self {
541        let inner = hash::Digest::new(digest);
542        Self(inner)
543    }
544
545    /// Returns a byte slice of the digest's contents.
546    #[must_use]
547    pub const fn as_bytes(&self) -> &[u8] {
548        let Self(inner) = self;
549        inner.as_bytes()
550    }
551
552    /// Consumes the digest, returning the digest bytes.
553    #[must_use]
554    pub fn into_inner(self) -> [u8; hash::DIGEST_LENGTH_BYTES] {
555        let Self(inner) = self;
556        inner.into_inner()
557    }
558
559    /// Returns a string in the lowercase hexadecimal representation.
560    ///
561    /// # Example
562    ///
563    /// ```rust
564    /// use chksum_sha2_256 as sha2_256;
565    ///
566    /// #[rustfmt::skip]
567    /// let digest = [
568    ///     0xE3, 0xB0, 0xC4, 0x42,
569    ///     0x98, 0xFC, 0x1C, 0x14,
570    ///     0x9A, 0xFB, 0xF4, 0xC8,
571    ///     0x99, 0x6F, 0xB9, 0x24,
572    ///     0x27, 0xAE, 0x41, 0xE4,
573    ///     0x64, 0x9B, 0x93, 0x4C,
574    ///     0xA4, 0x95, 0x99, 0x1B,
575    ///     0x78, 0x52, 0xB8, 0x55,
576    /// ];
577    /// let digest = sha2_256::Digest::new(digest);
578    /// assert_eq!(
579    ///     digest.to_hex_lowercase(),
580    ///     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
581    /// );
582    /// ```
583    #[must_use]
584    pub fn to_hex_lowercase(&self) -> String {
585        let Self(inner) = self;
586        inner.to_hex_lowercase()
587    }
588
589    /// Returns a string in the uppercase hexadecimal representation.
590    ///
591    /// # Example
592    ///
593    /// ```rust
594    /// use chksum_sha2_256 as sha2_256;
595    ///
596    /// #[rustfmt::skip]
597    /// let digest = [
598    ///     0xE3, 0xB0, 0xC4, 0x42,
599    ///     0x98, 0xFC, 0x1C, 0x14,
600    ///     0x9A, 0xFB, 0xF4, 0xC8,
601    ///     0x99, 0x6F, 0xB9, 0x24,
602    ///     0x27, 0xAE, 0x41, 0xE4,
603    ///     0x64, 0x9B, 0x93, 0x4C,
604    ///     0xA4, 0x95, 0x99, 0x1B,
605    ///     0x78, 0x52, 0xB8, 0x55,
606    /// ];
607    /// let digest = sha2_256::Digest::new(digest);
608    /// assert_eq!(
609    ///     digest.to_hex_uppercase(),
610    ///     "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855"
611    /// );
612    /// ```
613    #[must_use]
614    pub fn to_hex_uppercase(&self) -> String {
615        let Self(inner) = self;
616        inner.to_hex_uppercase()
617    }
618}
619
620impl core::Digest for Digest {}
621
622impl AsRef<[u8]> for Digest {
623    fn as_ref(&self) -> &[u8] {
624        let Self(inner) = self;
625        inner.as_bytes()
626    }
627}
628
629impl Display for Digest {
630    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
631        let Self(inner) = self;
632        Display::fmt(inner, f)
633    }
634}
635
636impl LowerHex for Digest {
637    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
638        let Self(inner) = self;
639        LowerHex::fmt(inner, f)
640    }
641}
642
643impl UpperHex for Digest {
644    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
645        let Self(inner) = self;
646        UpperHex::fmt(inner, f)
647    }
648}
649
650impl From<[u8; hash::DIGEST_LENGTH_BYTES]> for Digest {
651    fn from(digest: [u8; hash::DIGEST_LENGTH_BYTES]) -> Self {
652        Self::new(digest)
653    }
654}
655
656impl From<hash::Digest> for Digest {
657    fn from(digest: hash::Digest) -> Self {
658        Self(digest)
659    }
660}
chksum_sha2_256/lib.rs

chksum_sha2_256/
lib.rs
