# erlang-xorf <!-- omit in toc -->

[![ci](https://github.com/helium/erlang-xorf/actions/workflows/erlang.yml/badge.svg)](https://github.com/helium/erlang-xorf/actions/workflows/erlang.yml)
[![codecov](https://codecov.io/gh/helium/erlang-xorf/branch/main/graph/badge.svg?token=PHV5HEFNRT)](https://codecov.io/gh/helium/erlang-xorf)
[![hex.pm](https://img.shields.io/hexpm/v/erlang-xorf)](https://hex.pm/packages/erlang-xorf)

This library is a NIF wrapper for the [xorf](https://crates.io/crates/xorf)
family of xor filters.

Both binary fuses and xor filters are suported in 8 16, and 32 bits per entry.

**NOTE**: The initialization list to a filter must be a unique list of 64 bit
integers. Use a good hashing function over your data and make sure to dedupe it
before passing it into the `xorf:new/2` functions. Lists with duplicates may
cause undefined behavior.

## Table of Contents

- [Table of Contents](#table-of-contents)
- [Installation](#installation)
- [Example Usage](#example-usage)
- [Serialization](#serialization)

## Installation

Install from [hex.pm](https://hex.pm/packages/xorf).

For rebar3:

```erlang
%% rebar.config

{deps, [
  {xorf, "1.0.0"}
]}.
```

For Mix:

```elixir
## mix.exs

defp deps do
  [
    {:xorf, "~> 1.0.0"}
  ]
end
```

## Example Usage

**NOTE** The list of integers given to `xorf:new/2` must be deduped to avoid
undefined behavior.

For an xor filter:

```erlang
{ok, Filter} = xorf:new({exor, 8}, [1, 2, 3]),
true   = xorf:contains(Filter, 1),
false  = xorf:contains(Filter, 5),
```

Note that the number of bits per entry implies the likelihood of false positives
in the resulting filter.

For a binary fuse:

```erlang
{ok, Filter} = xorf:new({binary_fuse, 8}, [1, 2, 3]),
true   = xorf:contains(Filter, 1),
false  = xorf:contains(Filter, 5),
```

## Serialization

Binary serialization and deserialization is achieved using the [bincode](https://github.com/bincode-org/bincode).

For example, given a binary for an 8 bit binary fuse:

```erlang
{ok, Bin} = xorf:to_bin(Filter),
{ok, DFilter} = xorf:from_bin({binary_fuse, 8}, Bin),
true   = xorf:contains(DFilter, 1),
false  = xorf:contains(DFilter, 5),
```