tlsh/
lib.rs

1// SPDX-License-Identifier: Apache-2.0 OR MIT
2// SPDX-FileCopyrightText: Copyright (C) 2024, 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
7#![cfg_attr(not(any(test, doc, feature = "std")), no_std)]
8// Allow using internal features when use of Nightly Rust features are allowed.
9#![cfg_attr(feature = "unstable", allow(internal_features))]
10// Regular nightly features
11#![cfg_attr(feature = "unstable", feature(core_intrinsics))]
12#![cfg_attr(feature = "unstable", feature(coverage_attribute))]
13#![cfg_attr(feature = "unstable", feature(doc_cfg))]
14#![cfg_attr(feature = "unstable", feature(likely_unlikely))]
15#![cfg_attr(feature = "unstable", feature(portable_simd))]
16#![cfg_attr(
17    all(feature = "unstable", target_arch = "arm"),
18    feature(arm_target_feature)
19)]
20#![cfg_attr(
21    all(feature = "unstable", target_arch = "arm"),
22    feature(stdarch_arm_feature_detection)
23)]
24#![cfg_attr(
25    all(feature = "unstable", target_arch = "arm"),
26    feature(stdarch_arm_neon_intrinsics)
27)]
28// In the code maintenance mode, disallow all warnings.
29#![cfg_attr(feature = "maint-code", deny(warnings))]
30// Unsafe code is *only* allowed on enabling either arch-specific SIMD
31// ("simd-per-arch") or "unsafe" features ("simd-per-arch" and "simd-portable"
32// features only indicate those "implemented using SIMD inside this crate").
33// If only arch-specific SIMD features are enabled,
34// such code requires explicit allow.
35#![cfg_attr(
36    not(any(feature = "simd-per-arch", feature = "unsafe")),
37    forbid(unsafe_code)
38)]
39#![cfg_attr(
40    all(feature = "simd-per-arch", not(feature = "unsafe")),
41    deny(unsafe_code)
42)]
43// Non-test code requires documents (including private items)
44#![cfg_attr(not(test), warn(missing_docs))]
45#![cfg_attr(not(test), warn(clippy::missing_docs_in_private_items))]
46// Unless in the maintenance mode, allow unknown lints.
47#![cfg_attr(not(feature = "maint-lints"), allow(unknown_lints))]
48// Unless in the maintenance mode, allow old lint names.
49#![cfg_attr(not(feature = "maint-lints"), allow(renamed_and_removed_lints))]
50// Tests: allow unused unsafe blocks (invariant! does will not need unsafe
51// on tests but others may need this macro).
52#![cfg_attr(test, allow(unused_unsafe))]
53// Tests: non-simplified boolean expressions should be allowed.
54#![cfg_attr(test, allow(clippy::nonminimal_bool))]
55// Tests: assertion on constants should be allowed.
56#![cfg_attr(test, allow(clippy::assertions_on_constants))]
57// Tests: redundant clones should be allowed.
58#![cfg_attr(test, allow(clippy::redundant_clone))]
59
60// alloc is required when the "alloc" feature is enabled or testing (including doctests).
61#[cfg(any(feature = "alloc", test, doc))]
62extern crate alloc;
63
64pub mod _docs;
65pub mod buckets;
66pub mod compare;
67mod compare_easy;
68pub mod errors;
69pub mod generate;
70mod generate_easy;
71mod generate_easy_std;
72pub mod hash;
73pub mod hashes;
74mod intrinsics;
75pub mod length;
76mod macros;
77mod params;
78mod parse;
79#[cfg(not(any(doc, feature = "experiment-pearson")))]
80mod pearson;
81#[cfg(any(doc, feature = "experiment-pearson"))]
82#[cfg_attr(feature = "unstable", doc(cfg(feature = "experiment-pearson")))]
83#[cfg_attr(doc, deprecated)]
84pub mod pearson;
85
86// Easy function re-exports
87#[cfg(feature = "easy-functions")]
88pub use compare_easy::{compare, compare_with};
89#[cfg(feature = "easy-functions")]
90pub use generate_easy::{hash_buf, hash_buf_for};
91#[cfg(all(feature = "easy-functions", feature = "std"))]
92pub use generate_easy_std::{hash_file, hash_file_for, hash_stream, hash_stream_for};
93
94// Trait re-exports
95pub use generate::public::GeneratorType;
96pub use hash::public::FuzzyHashType;
97
98/// The default fuzzy hash type.
99pub type Tlsh = hashes::Normal;
100
101/// The fuzzy hash generator with the default parameter.
102pub type TlshGenerator = generate::Generator<Tlsh>;
103
104/// The fuzzy hash generator with specified parameter
105/// (or output fuzzy hash type).
106///
107/// The type parameter `T` must be either:
108///
109/// *   [`Tlsh`], the default (in this case, you'd better to use
110///     [`TlshGenerator`]),
111/// *   One of the types in [`hashes`] (each represents a fuzzy hash type
112///     and its parameter at the same time) or
113/// *   [`hash::FuzzyHash`] with valid parameters.
114///
115/// unless you have something pointing to these types above somewhere else.
116///
117/// # Example
118///
119/// ```
120/// use tlsh::prelude::*;
121///
122/// // Initialize a generator for long fuzzy hash (with 256 buckets)
123/// // with long (3-byte) checksum.
124/// let mut generator = TlshGeneratorFor::<tlsh::hashes::LongWithLongChecksum>::new();
125/// ```
126pub type TlshGeneratorFor<T> = generate::Generator<T>;
127
128/// The recommended set (prelude) to import.
129///
130/// It contains all crate-root types, traits and type aliases
131/// suitable for using this crate.  Because some methods require importing
132/// certain traits, just importing this can be convenient (not to confuse
133/// beginners, those traits are imported as `_`).
134///
135/// It (intentionally) excludes crate-root easy functions because
136/// it's not a big cost to type `tlsh::`.
137///
138/// It also excludes [`tlsh::hashes`](crate::hashes) to avoid confusion.
139pub mod prelude {
140    pub use super::FuzzyHashType as _;
141    pub use super::GeneratorType as _;
142
143    pub use super::Tlsh;
144    pub use super::{TlshGenerator, TlshGeneratorFor};
145}
146
147mod tests;
tlsh/lib.rs

tlsh/
lib.rs
