Struct ssdeep::FuzzyHashDualData

#[repr(align(8))]
pub struct FuzzyHashDualData<const S1: usize, const S2: usize, const C1: usize, const C2: usize>
where
    BlockHashSize<S1>: ConstrainedBlockHashSize,
    BlockHashSize<S2>: ConstrainedBlockHashSize,
    BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes,
    ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize,
    ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,
{ /* private fields */ }

An efficient compressed fuzzy hash representation, containing both normalized and raw block hash contents.

This struct contains a normalized fuzzy hash object and opaque data to perform “reverse normalization” afterwards.

On the current design, it allows compression ratio of about 5 / 8 (compared to two fuzzy hash objects, one normalized and another raw).

With this, you can compare many fuzzy hashes efficiently while preserving the original string representation without requesting too much memory.

Some methods accept AsRef to the normalized FuzzyHashData. On such cases, it is possible to pass this object directly (e.g. FuzzyHashCompareTarget::compare()).

Ordering

Sorting objects of this type will result in the following order.

• Two equivalent FuzzyHashDualData objects are considered equal (and the underlying sorting algorithm decides ordering of equivalent objects).
• Two different FuzzyHashDualData objects with different normalized FuzzyHashData objects (inside) will be ordered as the same order as the underlying FuzzyHashData.
• Two different FuzzyHashDualData objects with the same normalized FuzzyHashData objects (inside) will be ordered in an implementation-defined manner.

The implementation-defined order is not currently guaranteed to be stable. For instance, different versions of this crate may order them differently. However, it is guaranteed deterministic so that you can expect the same order in the same version (and the same configuration) of this crate.

Safety

Generic parameters of this type should not be considered stable because some generic parameters are just there because of the current restrictions of Rust’s constant generics (that will be resolved after the feature generic_const_exprs is stabilized).

Do not use FuzzyHashDualData directly.

Instead, use instantiations of this generic type:

• DualFuzzyHash (will be sufficient on most cases)
• LongDualFuzzyHash

Examples

// Requires the "alloc" feature to use `to_string()` method (default enabled).
use ssdeep::{DualFuzzyHash, FuzzyHash, RawFuzzyHash};

let hash_str_raw  = "12288:+ySwl5P+C5IxJ845HYV5sxOH/cccccccei:+Klhav84a5sxJ";
let hash_str_norm = "12288:+ySwl5P+C5IxJ845HYV5sxOH/cccei:+Klhav84a5sxJ";

let dual_hash: DualFuzzyHash = str::parse(hash_str_raw).unwrap();

// This object can effectively contain both
// normalized and raw fuzzy hash representations.
assert_eq!(dual_hash.to_raw_form().to_string(),   hash_str_raw);
assert_eq!(dual_hash.to_normalized().to_string(), hash_str_norm);

let another_hash: FuzzyHash = str::parse(
    "12288:+yUwldx+C5IxJ845HYV5sxOH/cccccccex:+glvav84a5sxK"
).unwrap();

// You can directly compare a DualFuzzyHash against a FuzzyHash.
//
// This is almost as fast as comparison between two FuzzyHash objects
// because the native representation inside DualFuzzyHash
// is a FuzzyHash object.
assert_eq!(another_hash.compare(dual_hash), 88);

// But DualFuzzyHash is not a drop-in replacement of FuzzyHash.
// You need to use `as_normalized()` to compare a FuzzyHash against
// a DualFuzzyHash (direct comparison may be provided on the later version).
assert_eq!(dual_hash.as_normalized().compare(&another_hash), 88);

Implementations

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

pub const MAX_BLOCK_HASH_SIZE_1: usize = FuzzyHashData<S1, S2, true>::MAX_BLOCK_HASH_SIZE_1

The maximum size of the block hash 1.

This value is the same as the underlying fuzzy hash type.

pub const MAX_BLOCK_HASH_SIZE_2: usize = FuzzyHashData<S1, S2, true>::MAX_BLOCK_HASH_SIZE_2

The maximum size of the block hash 2.

This value is the same as the underlying fuzzy hash type.

pub const IS_NORMALIZED_FORM: bool = false

Denotes whether the fuzzy type only contains a normalized form.

In this type, it is always false.

pub const IS_LONG_FORM: bool = FuzzyHashData<S1, S2, true>::IS_LONG_FORM

Denotes whether the fuzzy type can contain a non-truncated fuzzy hash.

This value is the same as the underlying fuzzy hash type.

pub const MAX_LEN_IN_STR: usize = FuzzyHashData<S1, S2, true>::MAX_LEN_IN_STR

The maximum length in the string representation.

This value is the same as the underlying fuzzy hash type.

pub fn new() -> Self

Creates a new fuzzy hash object with empty contents.

This is equivalent to the fuzzy hash string 3::.

pub fn init_from_raw_form(&mut self, hash: &FuzzyHashData<S1, S2, false>)

Initialize the object from a raw fuzzy hash.

pub unsafe fn init_from_raw_form_internals_raw_unchecked( &mut self, log_block_size: u8, block_hash_1: &[u8; S1], block_hash_2: &[u8; S2], block_hash_1_len: u8, block_hash_2_len: u8 )

Available on crate feature unchecked only.

Initialize the fuzzy hash object with internal contents (raw). The input is of the raw form.

Safety

• Valid range of block_hash_1 and block_hash_2 must consist of valid Base64 indices.
• Invalid range of block_hash_1 and block_hash_2 must be filled with zeroes.
• block_hash_1_len and block_hash_2_len must be valid.
• log_block_size must hold a valid base-2 logarithm form of a block size.

If they are not satisfied, the resulting object will be corrupted.

pub fn init_from_raw_form_internals_raw( &mut self, log_block_size: u8, block_hash_1: &[u8; S1], block_hash_2: &[u8; S2], block_hash_1_len: u8, block_hash_2_len: u8 )

Initialize the fuzzy hash object with internal contents (raw). The input is of the raw form.

Usage Constraints

• Valid range of block_hash_1 and block_hash_2 must consist of valid Base64 indices.
• Invalid range of block_hash_1 and block_hash_2 must be filled with zeroes.
• block_hash_1_len and block_hash_2_len must be valid.
• log_block_size must hold a valid base-2 logarithm form of a block size.

pub unsafe fn new_from_raw_form_internals_raw_unchecked( log_block_size: u8, block_hash_1: &[u8; S1], block_hash_2: &[u8; S2], block_hash_1_len: u8, block_hash_2_len: u8 ) -> Self

Available on crate feature unchecked only.

Creates a new fuzzy hash object with internal contents (raw). The input is of the raw form.

Safety

• Valid range of block_hash_1 and block_hash_2 must consist of valid Base64 indices.
• Invalid range of block_hash_1 and block_hash_2 must be filled with zeroes.
• block_hash_1_len and block_hash_2_len must be valid.
• log_block_size must hold a valid base-2 logarithm form of a block size.

If they are not satisfied, the resulting object will be corrupted.

pub fn new_from_raw_form_internals_raw( log_block_size: u8, block_hash_1: &[u8; S1], block_hash_2: &[u8; S2], block_hash_1_len: u8, block_hash_2_len: u8 ) -> Self

Creates a new fuzzy hash object with internal contents (raw). The input is of the raw form.

Usage Constraints

• Valid range of block_hash_1 and block_hash_2 must consist of valid Base64 indices.
• Invalid range of block_hash_1 and block_hash_2 must be filled with zeroes.
• block_hash_1_len and block_hash_2_len must be valid.
• log_block_size must hold a valid base-2 logarithm form of a block size.

pub fn log_block_size(&self) -> u8

The base-2 logarithm form of the block size.

See also: “Block Size” section of FuzzyHashData

pub fn block_size(&self) -> u32

The block size of the fuzzy hash.

pub fn as_normalized(&self) -> &FuzzyHashData<S1, S2, true>

A reference to the normalized fuzzy hash.

To note, this operation should be fast enough because this type contains this object directly.

pub fn as_ref_normalized(&self) -> &FuzzyHashData<S1, S2, true>

👎Deprecated

A reference to the normalized fuzzy hash.

This method is superseded by as_normalized().

This method will be removed on the next major release.

pub fn from_raw_form(hash: &FuzzyHashData<S1, S2, false>) -> Self

Constructs an object from a raw fuzzy hash.

pub fn from_normalized(hash: &FuzzyHashData<S1, S2, true>) -> Self

Constructs an object from a normalized fuzzy hash.

pub fn into_mut_raw_form(&self, hash: &mut FuzzyHashData<S1, S2, false>)

Decompresses a raw variant of the fuzzy hash and stores into an existing object.

pub fn to_raw_form(&self) -> FuzzyHashData<S1, S2, false>

Decompresses and generates a raw variant of the fuzzy hash.

Based on the normalized fuzzy hash representation and the “reverse normalization” data, this method generates the original, a raw variant of the fuzzy hash.

pub fn to_normalized(&self) -> FuzzyHashData<S1, S2, true>

Returns the clone of the normalized fuzzy hash.

Where possible, as_normalized() or AsRef::as_ref() should be used instead.

pub fn to_normalized_string(&self) -> String

Available on crate feature alloc only.

Converts the fuzzy hash to the string (normalized form).

This method returns the string corresponding the normalized form.

pub fn to_raw_form_string(&self) -> String

Available on crate feature alloc only.

Converts the fuzzy hash to the string (raw form).

This method returns the string corresponding the raw (non-normalized) form.

pub fn from_bytes(str: &[u8]) -> Result<Self, ParseError>

Parse a fuzzy hash from given bytes (a slice of u8).

pub fn normalize_in_place(&mut self)

Normalize the fuzzy hash in place.

After calling this method, self will be normalized.

In this implementation, it clears all “reverse normalization” data.

See also: “Normalization” section of FuzzyHashData

pub fn is_normalized(&self) -> bool

Returns whether the dual fuzzy hash is normalized.

pub fn is_valid(&self) -> bool

Performs full validity checking of the internal structure.

The primary purpose of this is debugging and it should always return true unless…

• There is a bug in this crate, corrupting this structure or
• A memory corruption is occurred somewhere else.

Because of its purpose, this method is not designed to be fast.

Note that, despite that it is only relevant to users when the unchecked feature is enabled but made public without any features because this method is not unsafe or unchecked in any way.

Trait Implementations

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> AsRef<FuzzyHashData<S1, S2, true>> for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

fn as_ref(&self) -> &FuzzyHashData<S1, S2, true>

Converts this type into a shared reference of the (usually inferred) input type.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> Clone for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

fn clone(&self) -> FuzzyHashDualData<S1, S2, C1, C2>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> Debug for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> Default for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

fn default() -> Self

Returns the “default value” for a type.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> Display for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> From<&FuzzyHashDualData<S1, S2, C1, C2>> for FuzzyHashCompareTarget

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

fn from(value: &FuzzyHashDualData<S1, S2, C1, C2>) -> Self

Converts to this type from the input type.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> From<FuzzyHashData<S1, S2, false>> for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

fn from(value: FuzzyHashData<S1, S2, false>) -> Self

Converts to this type from the input type.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> From<FuzzyHashData<S1, S2, true>> for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

fn from(value: FuzzyHashData<S1, S2, true>) -> Self

Converts to this type from the input type.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> From<FuzzyHashDualData<S1, S2, C1, C2>> for FuzzyHashCompareTarget

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

fn from(value: FuzzyHashDualData<S1, S2, C1, C2>) -> Self

Converts to this type from the input type.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> FromStr for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> Hash for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> Ord for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> PartialEq for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> PartialOrd for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> Copy for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,

impl<const S1: usize, const S2: usize, const C1: usize, const C2: usize> Eq for FuzzyHashDualData<S1, S2, C1, C2>

where BlockHashSize<S1>: ConstrainedBlockHashSize, BlockHashSize<S2>: ConstrainedBlockHashSize, BlockHashSizes<S1, S2>: ConstrainedBlockHashSizes, ReconstructionBlockSize<S1, C1>: ConstrainedReconstructionBlockSize, ReconstructionBlockSize<S2, C2>: ConstrainedReconstructionBlockSize,