ssdeep/
lib.rs

1// SPDX-License-Identifier: MIT
2// SPDX-FileCopyrightText: Copyright (C) 2023–2025 Tsukasa OI <floss_ssdeep@irq.a4lg.com>.
3
4// Separate from README.md to use rustdoc-specific features in docs/readme.md.
5#![doc = include_str!("_docs/readme.md")]
6// no_std by default (import alloc and std if necessary)
7#![no_std]
8// Regular nightly features
9#![cfg_attr(
10    feature = "unstable",
11    feature(
12        coverage_attribute,
13        doc_cfg,
14        doc_auto_cfg,
15        likely_unlikely,
16        trusted_len
17    )
18)]
19// In the code maintenance mode, disallow all warnings.
20#![cfg_attr(feature = "maint-code", deny(warnings))]
21// unsafe code is *only* allowed on enabling either "unsafe"-like features or
22// the "unchecked" feature, or on the tests.  When full "unsafe" feature is not
23// enabled and not on the tests, unsafe code requires explicit allow.
24#![cfg_attr(
25    not(any(
26        feature = "unsafe",
27        feature = "unsafe-guarantee",
28        feature = "unchecked",
29        test
30    )),
31    forbid(unsafe_code)
32)]
33#![cfg_attr(
34    all(
35        not(any(feature = "unsafe", test)),
36        any(feature = "unchecked", feature = "unsafe-guarantee")
37    ),
38    deny(unsafe_code)
39)]
40// Non-test code requires documents
41#![cfg_attr(not(test), warn(missing_docs, clippy::missing_docs_in_private_items))]
42// Unless in the maintenance mode, allow unknown lints / old lint names.
43#![cfg_attr(
44    not(feature = "maint-lints"),
45    allow(unknown_lints, renamed_and_removed_lints)
46)]
47// On tests, we allow several types of redundant operations.
48#![cfg_attr(
49    test,
50    allow(
51        unused_unsafe,
52        clippy::assertions_on_constants,
53        clippy::int_plus_one,
54        clippy::identity_op,
55        clippy::erasing_op,
56        clippy::overly_complex_bool_expr,
57        clippy::logic_bug, // renamed to clippy::overly_complex_bool_expr
58        clippy::nonminimal_bool
59    )
60)]
61
62// Import alloc and std only when necessary
63#[cfg(any(feature = "alloc", test, doc))]
64extern crate alloc;
65#[cfg(any(feature = "std", test, doc))]
66extern crate std;
67
68mod internals;
69
70#[cfg(doc)]
71#[allow(missing_docs)]
72pub mod _docs;
73
74pub use crate::internals::compare::FuzzyHashCompareTarget;
75#[cfg(feature = "easy-functions")]
76pub use crate::internals::compare_easy::{compare, ParseErrorEither, ParseErrorSide};
77pub use crate::internals::generate::{Generator, GeneratorError};
78#[cfg(feature = "easy-functions")]
79pub use crate::internals::generate_easy::hash_buf;
80#[cfg(all(feature = "easy-functions", feature = "std"))]
81pub use crate::internals::generate_easy_std::{hash_file, hash_stream, GeneratorOrIOError};
82pub use crate::internals::hash::block::{block_hash, block_size, BlockSizeRelation};
83pub use crate::internals::hash::parser_state::{
84    ParseError, ParseErrorInfo, ParseErrorKind, ParseErrorOrigin,
85};
86pub use crate::internals::hash::{
87    FuzzyHash, FuzzyHashData, FuzzyHashOperationError, LongFuzzyHash, LongRawFuzzyHash,
88    RawFuzzyHash,
89};
90pub use crate::internals::hash_dual::{DualFuzzyHash, FuzzyHashDualData, LongDualFuzzyHash};
91
92/// Module containing internal hash functions.
93///
94/// # Compatibility Notice
95///
96/// This module is going to be completely private on the next major release.
97/// If you need to experiment with internal hashing functions, just
98/// vendor the source code for your needs.
99#[deprecated]
100pub mod internal_hashes {
101    pub use crate::internals::generate::{PartialFNVHash, RollingHash};
102}
103
104/// Module containing internal efficient block hash implementation.
105///
106/// # Compatibility Notice
107///
108/// This module is going to be completely private on the next major release.
109/// If you need to experiment with internal hashing functions, just
110/// vendor the source code for your needs.
111#[deprecated]
112pub mod internal_comparison {
113    pub use crate::internals::compare::position_array::{
114        block_hash_position_array_element, BlockHashPositionArray, BlockHashPositionArrayData,
115        BlockHashPositionArrayImpl,
116    };
117
118    #[cfg(feature = "unchecked")]
119    pub use crate::internals::compare::position_array::BlockHashPositionArrayImplUnchecked;
120}
121
122/// Module containing certain constraints about fuzzy hash data.
123pub mod constraints {
124    pub use crate::internals::hash::block::{
125        BlockHashSize, BlockHashSizes, ConstrainedBlockHashSize, ConstrainedBlockHashSizes,
126    };
127}
128
129/// Prelude for convenient uses of this crate.
130///
131/// This module is currently empty but will be heavily used on the next version.
132/// Person who use this crate are recommended to import everything in this prelude.
133///
134/// # Example
135///
136/// ```
137/// use ssdeep::prelude::*;
138/// ```
139pub mod prelude {}
140
141/// The maximum length of the fuzzy hash's string representation
142/// (except optional file name part).
143///
144/// This is the maximum length of the longest valid fuzzy hash (except
145/// optional file name part) when represented in a string.
146///
147/// Note that again, this value does not count
148/// [the file name part of the fuzzy hash](crate::internals::hash::FuzzyHashData#fuzzy-hash-internals)
149/// (not even an optional "comma" character separating the file name part)
150/// because [`LongRawFuzzyHash::len_in_str()`] does not.
151pub const MAX_LEN_IN_STR: usize = LongRawFuzzyHash::MAX_LEN_IN_STR;
152
153/// Constant assertions related to the base requirements.
154#[doc(hidden)]
155mod const_asserts {
156    use static_assertions::const_assert;
157
158    use super::*;
159
160    // Environment: We expect that usize is at least 16 bits in width.
161    // Note that, some tests even require that usize is at least 32 bits.
162    const_assert!(usize::BITS >= 16);
163
164    // MAX_LEN_IN_STR is sufficient to represent every variant of
165    // a fuzzy hash.
166    const_assert!(MAX_LEN_IN_STR >= FuzzyHash::MAX_LEN_IN_STR);
167    const_assert!(MAX_LEN_IN_STR >= RawFuzzyHash::MAX_LEN_IN_STR);
168    const_assert!(MAX_LEN_IN_STR >= LongFuzzyHash::MAX_LEN_IN_STR);
169    const_assert!(MAX_LEN_IN_STR >= LongRawFuzzyHash::MAX_LEN_IN_STR);
170}
171
172mod tests;
ssdeep/lib.rs

ssdeep/
lib.rs
