chksum_sha2_384/
lib.rs

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

chksum_sha2_384/
lib.rs
