defmodule Wasmex.Memory do
  @moduledoc ~S"""
  Memory is a linear array of bytes to store Wasm values. The `Memory` module provides functions to read and write to this array.

  `Memory` is accessible through `Wasmex.Instance.memory/2`,
  `Wasmex.Memory.from_instance/2`, or as the caller context
  of an imported function (see `Wasmex.Instance.call_exported_function/5`).

      iex> %{store: store, module: module} = TestHelper.wasm_module()
      iex> {:ok, instance} = Wasmex.Instance.new(store, module, %{})
      iex> {:ok, memory} = Wasmex.Instance.memory(store, instance)
      iex> Wasmex.Memory.set_byte(store, memory, 0, 42)
      iex> Wasmex.Memory.get_byte(store, memory, 0)
      42

  Wasm memory is organized in pages of 64kb and may be grown by additional pages.
  """

  @type t :: %__MODULE__{
          resource: binary(),
          reference: reference()
        }

  defstruct resource: nil,
            # The actual NIF memory resource.
            # Normally the compiler will happily do stuff like inlining the
            # resource in attributes. This will convert the resource into an
            # empty binary with no warning. This will make that harder to
            # accidentally do.
            reference: nil

  def __wrap_resource__(resource) do
    %__MODULE__{
      resource: resource,
      reference: make_ref()
    }
  end

  @doc ~S"""
  Returns the exported memory resource of the given `Wasmex.Instance`.

  ## Example

      iex> %{store: store, module: module} = TestHelper.wasm_module()
      iex> {:ok, instance} = Wasmex.Instance.new(store, module, %{})
      iex> {:ok, %Wasmex.Memory{}} = Wasmex.Memory.from_instance(store, instance)
  """
  @spec from_instance(Wasmex.StoreOrCaller.t(), Wasmex.Instance.t()) ::
          {:ok, t} | {:error, binary()}
  def from_instance(store_or_caller, instance) do
    %{resource: store_or_caller_resource} = store_or_caller
    %Wasmex.Instance{resource: instance_resource} = instance

    case Wasmex.Native.memory_from_instance(store_or_caller_resource, instance_resource) do
      {:error, err} -> {:error, err}
      resource -> {:ok, __wrap_resource__(resource)}
    end
  end

  @doc ~S"""
  Returns the size in bytes of the given memory.

  Note that the size of the memory is always a multiple of 64kb (one page).

  ## Example

      iex> %{store: store, module: module} = TestHelper.wasm_module()
      iex> {:ok, instance} = Wasmex.Instance.new(store, module, %{})
      iex> {:ok, memory} = Wasmex.Memory.from_instance(store, instance)
      iex> Wasmex.Memory.size(store, memory)
      1114112 # in bytes (17 pages of 64 kB)
  """
  @spec size(Wasmex.StoreOrCaller.t(), t()) :: pos_integer()
  def size(store_or_caller, memory) do
    %Wasmex.StoreOrCaller{resource: store_or_caller_resource} = store_or_caller
    %__MODULE__{resource: memory_resource} = memory
    Wasmex.Native.memory_size(store_or_caller_resource, memory_resource)
  end

  @doc ~S"""
  Grows the amount of available memory by the given number of pages.

  Returns the number of previously available pages.
  A page has a size of 64 kB or 65,536 bytes.

  Returns an error if memory could not be grown.

  ## Example

      iex> %{store: store, module: module} = TestHelper.wasm_module()
      iex> {:ok, instance} = Wasmex.Instance.new(store, module, %{})
      iex> {:ok, memory} = Wasmex.Memory.from_instance(store, instance)
      iex> Wasmex.Memory.grow(store, memory, 1)
      17
  """
  @spec grow(Wasmex.StoreOrCaller.t(), t(), pos_integer()) :: pos_integer() | {:error, binary()}
  def grow(store_or_caller, memory, pages) do
    %Wasmex.StoreOrCaller{resource: store_or_caller_resource} = store_or_caller
    %__MODULE__{resource: memory_resource} = memory
    Wasmex.Native.memory_grow(store_or_caller_resource, memory_resource, pages)
  end

  @doc ~S"""
  Returns the byte at the given `index`.

  ## Example

  Set a value at memory position `0` and read it back:

      iex> %{store: store, module: module} = TestHelper.wasm_module()
      iex> {:ok, instance} = Wasmex.Instance.new(store, module, %{})
      iex> {:ok, memory} = Wasmex.Memory.from_instance(store, instance)
      iex> Wasmex.Memory.set_byte(store, memory, 0, 42)
      iex> Wasmex.Memory.get_byte(store, memory, 0)
      42
  """
  @spec get_byte(Wasmex.StoreOrCaller.t(), t(), non_neg_integer()) ::
          number()
  def get_byte(store_or_caller, memory, index) do
    %{resource: store_or_caller_resource} = store_or_caller
    %__MODULE__{resource: memory_resource} = memory

    Wasmex.Native.memory_get_byte(store_or_caller_resource, memory_resource, index)
  end

  @doc ~S"""
  Sets the byte at the given `index` to the given `value`.

  ## Example

  Set a value at memory position `0` and read it back:

      iex> %{store: store, module: module} = TestHelper.wasm_module()
      iex> {:ok, instance} = Wasmex.Instance.new(store, module, %{})
      iex> {:ok, memory} = Wasmex.Memory.from_instance(store, instance)
      iex> Wasmex.Memory.set_byte(store, memory, 0, 42)
      iex> Wasmex.Memory.get_byte(store, memory, 0)
      42
  """
  @spec set_byte(Wasmex.StoreOrCaller.t(), t(), non_neg_integer(), number()) ::
          :ok | {:error, binary()}
  def set_byte(store_or_caller, memory, index, value) do
    %{resource: store_or_caller_resource} = store_or_caller
    %__MODULE__{resource: memory_resource} = memory

    Wasmex.Native.memory_set_byte(store_or_caller_resource, memory_resource, index, value)
  end

  @doc ~S"""
  Writes the given `binary` into the memory at the given `index`.

  ## Example

  Writes 5 bytes representing the ASCII characters for "hello"
  at memory position `0`.

      iex> %{store: store, module: module} = TestHelper.wasm_module()
      iex> {:ok, instance} = Wasmex.Instance.new(store, module, %{})
      iex> {:ok, memory} = Wasmex.Memory.from_instance(store, instance)
      iex> Wasmex.Memory.write_binary(store, memory, 0, "hello")
      :ok
  """
  @spec write_binary(
          Wasmex.StoreOrCaller.t(),
          t(),
          non_neg_integer(),
          binary()
        ) ::
          :ok
  def write_binary(store_or_caller, memory, index, binary) when is_binary(binary) do
    %Wasmex.StoreOrCaller{resource: store_or_caller_resource} = store_or_caller
    %__MODULE__{resource: memory_resource} = memory

    Wasmex.Native.memory_write_binary(
      store_or_caller_resource,
      memory_resource,
      index,
      binary
    )
  end

  @doc ~S"""
  Reads the given number of bytes from the given memory at the given index.

  Returns the read bytes as a binary.

  ## Example

  Reads 5 bytes from memory position `0`, given it contains the 5 ASCII
  characters forming "hello".

      iex> %{store: store, module: module} = TestHelper.wasm_module()
      iex> {:ok, instance} = Wasmex.Instance.new(store, module, %{})
      iex> {:ok, memory} = Wasmex.Memory.from_instance(store, instance)
      iex> Wasmex.Memory.write_binary(store, memory, 0, "hello")
      iex> Wasmex.Memory.read_binary(store, memory, 0, 5)
      "hello"
      iex> Wasmex.Memory.read_binary(store, memory, 3, 2)
      "lo"
  """
  @spec read_binary(
          Wasmex.StoreOrCaller.t(),
          t(),
          non_neg_integer(),
          non_neg_integer()
        ) ::
          binary()
  def read_binary(store_or_caller, memory, index, length) do
    %Wasmex.StoreOrCaller{resource: store_or_caller_resource} = store_or_caller
    %__MODULE__{resource: memory_resource} = memory

    Wasmex.Native.memory_read_binary(
      store_or_caller_resource,
      memory_resource,
      index,
      length
    )
  end

  @doc ~S"""
  Reads the given number of bytes from the given memory at the given index.

  Returns the read bytes as a string.

  ## Example

  Reads 5 bytes from memory position `0`, given it contains the 5 ASCII
  characters forming "hello".

      iex> %{store: store, module: module} = TestHelper.wasm_module()
      iex> {:ok, instance} = Wasmex.Instance.new(store, module, %{})
      iex> {:ok, memory} = Wasmex.Memory.from_instance(store, instance)
      iex> Wasmex.Memory.write_binary(store, memory, 0, "hello")
      iex> Wasmex.Memory.read_string(store, memory, 0, 5)
      "hello"
      iex> Wasmex.Memory.read_string(store, memory, 3, 2)
      "lo"
  """
  @spec read_string(
          Wasmex.StoreOrCaller.t(),
          t(),
          non_neg_integer(),
          non_neg_integer()
        ) ::
          String.t()
  def read_string(store, memory, index, length) do
    read_binary(store, memory, index, length)
    |> to_string()
  end
end

defimpl Inspect, for: Wasmex.Memory do
  import Inspect.Algebra

  def inspect(dict, opts) do
    concat(["#Wasmex.Memory<", to_doc(dict.reference, opts), ">"])
  end
end
