Module fuse8

Description
Data Types
Function Index
Function Details

Interface for the fuse8 filter.

Authors: Matthew Pope.

Description

Interface for the fuse8 filter.

For a full set of examples, see the GitHub README at https://github.com/mpope9/efuse_filter/blob/main/README.md

Example usage:

  Filter = fuse8:new(["cat", "dog", "mouse"]),
  true   = fuse8:contain(Filter, "cat"),
  false  = fuse8:contain(Filter, "goose").

Data Types

fuse8()

fuse8() = #fuse8{reference = reference() | undefined, hashing_method = default | none, elements = set:set() | undefined}

Function Index

add/2	Adds elements to filter, and applys the default hashing mechanism if `none` wasn't specified in the `fuse8:new_empty/1` function.
contain/2	Tests to see if the passed argument is in the filter.
contain/3	Tests to see if the passed argument is in the filter.
contain/4	This function exists for testing if an element exists in a serialized filter with custom hashing.
finalize/1	Initializes filter internally.
from_bin/1	Deserialize the filter from a previous `fuse8_to_bin` call.
from_bin/2	Deserialize the filter from a previous `fuse8_to_bin` call.
new/1	Initializes the fuse filter.
new/2
new_empty/0	Initializes an empty filter.
new_empty/1	Initializes an empty filter.
to_bin/1	Serialize the filter to a binary.

Function Details

add/2

add(Filter::fuse8:fuse8(), Element::term()) -> fuse8:fuse8() | {error, atom()}

Adds elements to filter, and applys the default hashing mechanism if none wasn't specified in the fuse8:new_empty/1 function. This function attempts to catch issues early, before they reach the NIF code. So if any elements that are passed when custom hashing was specified this function will return {error, pre_hashed_values_should_be_ints}.

This function accepts both a list of elements and a single element.

contain/2

contain(Filter::fuse8:fuse8() | binary(), Key::term()) -> term()

Tests to see if the passed argument is in the filter. The first argument must be the pre-initialized filter. Returns false if the argument is not found.

A filter previously serialized by to_bin is allowed

contain/3

contain(Filter::fuse8:fuse8() | binary(), Key::term(), Default::term()) -> true | term()

Tests to see if the passed argument is in the filter. The first argument must be the pre-initialized filter. If the value is not found, the third arguement is returned instead of false.

A filter previously serialized by to_bin is allowed

If an invalid filter is passed or if the key is not an integer and the hashing method is set to none then false will be returned.

contain/4

contain(Filter::binary(), Key::integer(), Default::term(), HashingMethod::none) -> term()

This function exists for testing if an element exists in a serialized filter with custom hashing. The first argument should be the pre-initialized and seralized filter. The second argument is the key that will be tested. The third arguement is returned instead of false. The fourth argument should be none.

If an invalid filter is passed or if the key is not an integer and the hashing method is set to none then false will be returned.

finalize/1

finalize(Fuse8) -> any()

Initializes filter internally. Equivalent to calling fuse8:new. Elements are deduplicated at this point, so this function should only fail if an already intiialized filter is passed to it.

If more than 100K elements have been added, then the dirty version of the NIF is called. This is based around some simple benchmarking, and 100K elements initialized in under 1ms.

from_bin/1

from_bin(X1) -> any()

Deserialize the filter from a previous fuse8_to_bin call. This will defines the filter to use the default hashing method.

Returns fuse8:fuse8.

from_bin/2

from_bin(Binary, X2) -> any()

Deserialize the filter from a previous fuse8_to_bin call. This will defines the filter to use custom hashing.

Returns fuse8:fuse8.

new/1

new(List::[term()]) -> fuse8:fuse8() | {error, atom()}

Initializes the fuse filter

Initializes a fuse8 filter frim the passed values. Each value is hashed using the erlang:phash2/1 function.

Returns a fuse8 type, which is a filter to be used in contain If a predefined set of hashes is desired, pass none as the second argument.

Otherwise, an {error, reason} tuple will be returned.

Do not modify the return value of this function.

new/2

new(List::[term()], Method::atom()) -> fuse8:fuse8() | {error, atom()}

new_empty/0

new_empty() -> fuse8:fuse8()

Initializes an empty filter. This should be filled incrementally. Do not modify the reutrn value of this function.

new_empty/1

new_empty(X1::atom()) -> fuse8:fuse8() | {error, atom()}

Initializes an empty filter. This should be filled incrementally. If a value other than none is passed, then {error, invalid_hash_method} will be returned. Values passed to fuse8:add/2 need to be pre-hashed as integers before adding to a filter returned by this function. Do not modify the return value of this function.

to_bin/1

to_bin(Fuse8) -> any()

Serialize the filter to a binary

Returns binary().

Generated by EDoc