chksum_sha2_224/
lib.rs

1//! This crate provides an implementation of the SHA-2 224 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_224`] 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-224 = "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-224
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_224::Result;
29//! use chksum_sha2_224 as sha2_224;
30//!
31//! # fn wrapper(path: &Path) -> Result<()> {
32//! let file = File::open(path)?;
33//! let digest = sha2_224::chksum(file)?;
34//! assert_eq!(
35//!     digest.to_hex_lowercase(),
36//!     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
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_224::Result;
51//! use chksum_sha2_224 as sha2_224;
52//! use tokio::fs::File;
53//!
54//! # async fn wrapper(path: &Path) -> Result<()> {
55//! let file = File::open(path).await?;
56//! let digest = sha2_224::async_chksum(file).await?;
57//! assert_eq!(
58//!     digest.to_hex_lowercase(),
59//!     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
60//! );
61//! # Ok(())
62//! # }
63//! # }
64//! ```
65//!
66//! # Input Types
67//!
68//! ## Bytes
69//!
70//! ### Array
71//!
72//! ```rust
73//! # use chksum_sha2_224::Result;
74//! use chksum_sha2_224 as sha2_224;
75//!
76//! # fn wrapper() -> Result<()> {
77//! let data = [0, 1, 2, 3];
78//! let digest = sha2_224::chksum(data)?;
79//! assert_eq!(
80//!     digest.to_hex_lowercase(),
81//!     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
82//! );
83//! # Ok(())
84//! # }
85//! ```
86//!
87//! ### Vec
88//!
89//! ```rust
90//! # use chksum_sha2_224::Result;
91//! use chksum_sha2_224 as sha2_224;
92//!
93//! # fn wrapper() -> Result<()> {
94//! let data = vec![0, 1, 2, 3];
95//! let digest = sha2_224::chksum(data)?;
96//! assert_eq!(
97//!     digest.to_hex_lowercase(),
98//!     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
99//! );
100//! # Ok(())
101//! # }
102//! ```
103//!
104//! ### Slice
105//!
106//! ```rust
107//! # use chksum_sha2_224::Result;
108//! use chksum_sha2_224 as sha2_224;
109//!
110//! # fn wrapper() -> Result<()> {
111//! let data = &[0, 1, 2, 3];
112//! let digest = sha2_224::chksum(data)?;
113//! assert_eq!(
114//!     digest.to_hex_lowercase(),
115//!     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
116//! );
117//! # Ok(())
118//! # }
119//! ```
120//!
121//! ## Strings
122//!
123//! ### str
124//!
125//! ```rust
126//! # use chksum_sha2_224::Result;
127//! use chksum_sha2_224 as sha2_224;
128//!
129//! # fn wrapper() -> Result<()> {
130//! let data = "&str";
131//! let digest = sha2_224::chksum(data)?;
132//! assert_eq!(
133//!     digest.to_hex_lowercase(),
134//!     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
135//! );
136//! # Ok(())
137//! # }
138//! ```
139//!
140//! ### String
141//!
142//! ```rust
143//! # use chksum_sha2_224::Result;
144//! use chksum_sha2_224 as sha2_224;
145//!
146//! # fn wrapper() -> Result<()> {
147//! let data = String::from("String");
148//! let digest = sha2_224::chksum(data)?;
149//! assert_eq!(
150//!     digest.to_hex_lowercase(),
151//!     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
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_224::Result;
164//! use chksum_sha2_224 as sha2_224;
165//!
166//! # fn wrapper(path: &Path) -> Result<()> {
167//! let file = File::open(path)?;
168//! let digest = sha2_224::chksum(file)?;
169//! assert_eq!(
170//!     digest.to_hex_lowercase(),
171//!     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
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_224::Result;
184//! use chksum_sha2_224 as sha2_224;
185//!
186//! # fn wrapper(path: &Path) -> Result<()> {
187//! let readdir = read_dir(path)?;
188//! let digest = sha2_224::chksum(readdir)?;
189//! assert_eq!(
190//!     digest.to_hex_lowercase(),
191//!     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
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_224::Result;
204//! use chksum_sha2_224 as sha2_224;
205//!
206//! # fn wrapper(path: &Path) -> Result<()> {
207//! let path = PathBuf::from(path);
208//! let digest = sha2_224::chksum(path)?;
209//! assert_eq!(
210//!     digest.to_hex_lowercase(),
211//!     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
212//! );
213//! # Ok(())
214//! # }
215//! ```
216//!
217//! ## Standard Input
218//!
219//! ```rust
220//! use std::io::stdin;
221//!
222//! # use chksum_sha2_224::Result;
223//! use chksum_sha2_224 as sha2_224;
224//!
225//! # fn wrapper() -> Result<()> {
226//! let stdin = stdin();
227//! let digest = sha2_224::chksum(stdin)?;
228//! assert_eq!(
229//!     digest.to_hex_lowercase(),
230//!     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
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-224 = { 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-224 --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_224 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_224 as sha2_224;
306///
307/// let mut hash = sha2_224::new();
308/// hash.update(b"example data");
309/// let digest = hash.digest();
310/// assert_eq!(
311///     digest.to_hex_lowercase(),
312///     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
313/// );
314/// ```
315#[must_use]
316pub fn new() -> SHA2_224 {
317    SHA2_224::new()
318}
319
320/// Creates a default hash.
321///
322/// # Example
323///
324/// ```rust
325/// use chksum_sha2_224 as sha2_224;
326///
327/// let mut hash = sha2_224::default();
328/// hash.update(b"example data");
329/// let digest = hash.digest();
330/// assert_eq!(
331///     digest.to_hex_lowercase(),
332///     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
333/// );
334/// ```
335#[must_use]
336pub fn default() -> SHA2_224 {
337    core::default()
338}
339
340/// Computes the hash of the given input.
341///
342/// # Example
343///
344/// ```rust
345/// use chksum_sha2_224 as sha2_224;
346///
347/// let data = b"example data";
348/// let digest = sha2_224::hash(data);
349/// assert_eq!(
350///     digest.to_hex_lowercase(),
351///     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
352/// );
353/// ```
354pub fn hash(data: impl core::Hashable) -> Digest {
355    core::hash::<SHA2_224>(data)
356}
357
358/// Computes the hash of the given input.
359///
360/// # Example
361///
362/// ```rust
363/// use chksum_sha2_224 as sha2_224;
364///
365/// let data = b"example data";
366/// if let Ok(digest) = sha2_224::chksum(data) {
367///     assert_eq!(
368///         digest.to_hex_lowercase(),
369///         "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
370///     );
371/// }
372/// ```
373pub fn chksum(data: impl core::Chksumable) -> Result<Digest> {
374    core::chksum::<SHA2_224>(data)
375}
376
377/// Computes the hash of the given input.
378///
379/// # Example
380///
381/// ```rust
382/// use chksum_sha2_224 as sha2_224;
383///
384/// # async fn wrapper() {
385/// let data = b"example data";
386/// if let Ok(digest) = sha2_224::async_chksum(data).await {
387///     assert_eq!(
388///         digest.to_hex_lowercase(),
389///         "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
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_224>(data).await
397}
398
399/// The SHA-2 224 hash instance.
400#[derive(Clone, Debug, Default, PartialEq, Eq)]
401pub struct SHA2_224 {
402    inner: hash::Update,
403}
404
405impl SHA2_224 {
406    /// Calculates the hash digest of an input data.
407    ///
408    /// # Example
409    ///
410    /// ```rust
411    /// use chksum_sha2_224::SHA2_224;
412    ///
413    /// let data = b"example data";
414    /// let digest = SHA2_224::hash(data);
415    /// assert_eq!(
416    ///     digest.to_hex_lowercase(),
417    ///     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
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_224::SHA2_224;
436    ///
437    /// let mut hash = SHA2_224::new();
438    /// hash.update(b"example data");
439    /// let digest = hash.digest();
440    /// assert_eq!(
441    ///     digest.to_hex_lowercase(),
442    ///     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
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_224::SHA2_224;
457    ///
458    /// let mut hash = SHA2_224::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    ///     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
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_224::SHA2_224;
481    ///
482    /// let mut hash = SHA2_224::new();
483    /// hash.update(b"example data");
484    /// hash.reset();
485    /// let digest = hash.digest();
486    /// assert_eq!(
487    ///     digest.to_hex_lowercase(),
488    ///     "d14a028c2a3a2bc9476102bb288234c415a2b01f828ea62ac5b3e42f"
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_224::SHA2_224;
501    ///
502    /// let mut hash = SHA2_224::new();
503    /// let digest = hash.digest();
504    /// assert_eq!(
505    ///     digest.to_hex_lowercase(),
506    ///     "d14a028c2a3a2bc9476102bb288234c415a2b01f828ea62ac5b3e42f"
507    /// );
508    /// ```
509    #[must_use]
510    pub fn digest(&self) -> Digest {
511        self.inner.digest().into()
512    }
513}
514
515impl core::Hash for SHA2_224 {
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_224 as sha2_224;
565    ///
566    /// #[rustfmt::skip]
567    /// let digest = [
568    ///     0xD1, 0x4A, 0x02, 0x8C,
569    ///     0x2A, 0x3A, 0x2B, 0xC9,
570    ///     0x47, 0x61, 0x02, 0xBB,
571    ///     0x28, 0x82, 0x34, 0xC4,
572    ///     0x15, 0xA2, 0xB0, 0x1F,
573    ///     0x82, 0x8E, 0xA6, 0x2A,
574    ///     0xC5, 0xB3, 0xE4, 0x2F,
575    /// ];
576    /// let digest = sha2_224::Digest::new(digest);
577    /// assert_eq!(
578    ///     digest.to_hex_lowercase(),
579    ///     "d14a028c2a3a2bc9476102bb288234c415a2b01f828ea62ac5b3e42f"
580    /// );
581    /// ```
582    #[must_use]
583    pub fn to_hex_lowercase(&self) -> String {
584        let Self(inner) = self;
585        inner.to_hex_lowercase()
586    }
587
588    /// Returns a string in the uppercase hexadecimal representation.
589    ///
590    /// # Example
591    ///
592    /// ```rust
593    /// use chksum_sha2_224 as sha2_224;
594    ///
595    /// #[rustfmt::skip]
596    /// let digest = [
597    ///     0xD1, 0x4A, 0x02, 0x8C,
598    ///     0x2A, 0x3A, 0x2B, 0xC9,
599    ///     0x47, 0x61, 0x02, 0xBB,
600    ///     0x28, 0x82, 0x34, 0xC4,
601    ///     0x15, 0xA2, 0xB0, 0x1F,
602    ///     0x82, 0x8E, 0xA6, 0x2A,
603    ///     0xC5, 0xB3, 0xE4, 0x2F,
604    /// ];
605    /// let digest = sha2_224::Digest::new(digest);
606    /// assert_eq!(
607    ///     digest.to_hex_uppercase(),
608    ///     "D14A028C2A3A2BC9476102BB288234C415A2B01F828EA62AC5B3E42F"
609    /// );
610    /// ```
611    #[must_use]
612    pub fn to_hex_uppercase(&self) -> String {
613        let Self(inner) = self;
614        inner.to_hex_uppercase()
615    }
616}
617
618impl core::Digest for Digest {}
619
620impl AsRef<[u8]> for Digest {
621    fn as_ref(&self) -> &[u8] {
622        let Self(inner) = self;
623        inner.as_bytes()
624    }
625}
626
627impl Display for Digest {
628    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
629        let Self(inner) = self;
630        Display::fmt(inner, f)
631    }
632}
633
634impl LowerHex for Digest {
635    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
636        let Self(inner) = self;
637        LowerHex::fmt(inner, f)
638    }
639}
640
641impl UpperHex for Digest {
642    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
643        let Self(inner) = self;
644        UpperHex::fmt(inner, f)
645    }
646}
647
648impl From<[u8; hash::DIGEST_LENGTH_BYTES]> for Digest {
649    fn from(digest: [u8; hash::DIGEST_LENGTH_BYTES]) -> Self {
650        Self::new(digest)
651    }
652}
653
654impl From<hash::Digest> for Digest {
655    fn from(digest: hash::Digest) -> Self {
656        Self(digest)
657    }
658}
chksum_sha2_224/lib.rs

chksum_sha2_224/
lib.rs
