defmodule SipHash do
  use Bitwise
  @moduledoc """
  Module for hashing values using the SipHash hash family.

  This module makes use of NIFs for better performance and throughput, but this
  can be disabled by setting the `HASH_IMPL` environment variable to `embedded`.
  This is controlled via the environment rather than a specific function arg as
  the NIFs are automatically loaded during the start of the application. Please
  note that the use of NIFs brings a significant performance improvement, and so
  you should only disable them with good reason.
  """

  # alias both SipHash.State/Util
  alias SipHash.State, as: State
  alias SipHash.Util, as: Util

  # define types
  @type s :: { number, number, number, number }

  @doc """
  Based on the algorithm as described in https://131002.net/siphash/siphash.pdf,
  and therefore requires a key alongside the input to use as a seed. This key
  is required to be 16 bytes, and is measured by `Kernel.byte_size/1`. An error
  will be raised if this is not the case. The default implementation is a 2-4
  hash, but this can be controlled through the options provided.

  Your input *must* be a binary. It's possible to add a catch-all to `SipHash.hash/3`
  which simply wraps the input in `Kernel.inspect/2`, but such usage is not
  encourage. It's better to be more explicit about what is being hashed, and
  `Kernel.inspect/2` does not always perform the fastest available conversion
  (for example, using Poison to encode Maps is far faster, whilst also being more
  reliable). In addition, the output of `Kernel.inspect/2` is specific to Elixir,
  making it annoyingly unportable.

  By default, all values are returned as numbers (i.e. the result of the hash),
  but you can set `:hex` to true as an option to get a hex string output. The
  reason for this is that converting to hex takes an extra couple of µs, and the
  default is intended to be the optimal use case. Please note that any of the
  options related to hex string formatting will be ignored if `:hex` is not set
  to true (e.g. `:case`).

  ## Options

    * `:case` - either of `:upper` or `:lower`, defaults to using `:upper`
    * `:c` and `:d` - the number of compression rounds, default to `2` and `4`
    * `:hex` - when `true` returns the output as a hex string
    * `:padding` - when `true`, pads left with zeroes to 16 chars as necessary

  ## Examples

      iex> SipHash.hash("0123456789ABCDEF", "hello")
      4402678656023170274

      iex> SipHash.hash("0123456789ABCDEF", "hello", hex: true)
      "3D1974E948748CE2"

      iex> SipHash.hash("0123456789ABCDEF", "abcdefgh", hex: true)
      "1AE57886F899E65F"

      iex> SipHash.hash("0123456789ABCDEF", "my long strings", hex: true)
      "1323400B0804036D"

      iex> SipHash.hash("0123456789ABCDEF", "hello", hex: true, case: :lower)
      "3d1974e948748ce2"

      iex> SipHash.hash("0123456789ABCDEF", "zymotechnics", hex: true, padding: :true)
      "09B57037CD3F8F0C"

      iex> SipHash.hash("0123456789ABCDEF", "hello", c: 4, d: 8)
      14986662229302055855

      iex> SipHash.hash("invalid_bytes", "hello")
      ** (RuntimeError) Key must be exactly 16 bytes.

      iex> SipHash.hash("FEDCBA9876543210", %{ "test" => "one" })
      ** (FunctionClauseError) no function clause matching in SipHash.hash/3

  """
  @spec hash(binary, binary, [ { atom, atom } ]) :: binary
  def hash(key, input, opts \\ [])
  when is_binary(key) and is_binary(input) and is_list(opts) do
    if byte_size(key) != 16 do
      raise "Key must be exactly 16 bytes."
    end

    in_len = byte_size(input)
    s_case = :upper
    c_pass = 2
    d_pass = 4
    to_hex = false
    l_pad  = false
    state  = State.initialize(key)

    case opts do
      [] -> ;
      [_h|_t] ->
        s_case = Keyword.get(opts, :case, s_case)
        c_pass = Keyword.get(opts, :c, c_pass)
        d_pass = Keyword.get(opts, :d, d_pass)
        to_hex = Keyword.get(opts, :hex, to_hex)
        l_pad  = Keyword.get(opts, :padding, l_pad)
    end

    input
    |> Util.chunk_string(8)
    |> Enum.reduce(state, fn(chunk, state) ->
        case byte_size(chunk) do
          8 ->
            State.apply_block(state, chunk, c_pass)
          l ->
            { chunk, state, l }
        end
       end)
    |> State.apply_last_block(in_len, c_pass)
    |> State.finalize(d_pass)
    |> Util.to_hex(to_hex)
    |> Util.to_case(s_case, :upper)
    |> Util.pad_left(l_pad)
  end

  @doc """
  Wrapper around `SipHash.hash/3` to rotate the arguments, allowing for more
  convenient usage when creating a pipeline (you can rotate key/input as needed).

  ## Examples

      iex> SipHash.hash_r("hello", "0123456789ABCDEF")
      4402678656023170274

  """
  @spec hash_r(binary, binary | s, [ { atom, atom } ]) :: binary
  def hash_r(input, key_or_state, opts \\ []), do: hash(key_or_state, input, opts)

end