defmodule Explorer.Backend.Series do
  @moduledoc """
  The behaviour for series backends.
  """

  @type t :: struct()

  @type s :: Explorer.Series.t()
  @type lazy_s :: Explorer.Series.lazy_t()
  @type df :: Explorer.DataFrame.t()
  @type dtype :: Explorer.Series.dtype()

  @type valid_types ::
          number()
          | boolean()
          | String.t()
          | Date.t()
          | Time.t()
          | NaiveDateTime.t()
          | Explorer.Duration.t()

  @type non_finite :: Explorer.Series.non_finite()
  @type option(type) :: type | nil

  # Conversion

  @callback from_list(list(), dtype()) :: s
  @callback from_binary(binary(), dtype()) :: s
  @callback to_list(s) :: list()
  @callback to_iovec(s) :: [binary()]
  @callback cast(s, dtype) :: s
  @callback categorise(s, s) :: s
  @callback strptime(s, String.t()) :: s
  @callback strftime(s, String.t()) :: s

  # Introspection

  @callback dtype(s) :: dtype()
  @callback size(s) :: non_neg_integer() | lazy_s()
  @callback inspect(s, opts :: Inspect.Opts.t()) :: Inspect.Algebra.t()
  @callback categories(s) :: s

  # Slice and dice

  @callback head(s, n :: integer()) :: s
  @callback tail(s, n :: integer()) :: s
  @callback sample(
              s,
              n_or_frac :: number(),
              replacement :: boolean(),
              shuffle :: boolean(),
              seed :: option(integer())
            ) :: s
  @callback at(s, idx :: integer()) :: s
  @callback at_every(s, integer()) :: s
  @callback mask(s, mask :: s) :: s
  @callback slice(s, indices :: list() | s()) :: s
  @callback slice(s, offset :: integer(), length :: integer()) :: s
  @callback format(list(s)) :: s
  @callback concat(list(s)) :: s
  @callback coalesce(s, s) :: s
  @callback first(s) :: valid_types() | lazy_s()
  @callback last(s) :: valid_types() | lazy_s()
  @callback select(predicate :: s, s, s) :: s
  @callback shift(s, offset :: integer, default :: nil) :: s
  @callback rank(
              s,
              method :: atom(),
              descending :: boolean(),
              seed :: option(integer())
            ) :: s | lazy_s()
  # Aggregation

  @callback count(s) :: number() | lazy_s()
  @callback sum(s) :: number() | non_finite() | lazy_s() | nil
  @callback min(s) :: number() | non_finite() | Date.t() | NaiveDateTime.t() | lazy_s() | nil
  @callback max(s) :: number() | non_finite() | Date.t() | NaiveDateTime.t() | lazy_s() | nil
  @callback argmin(s) :: number() | non_finite() | lazy_s() | nil
  @callback argmax(s) :: number() | non_finite() | lazy_s() | nil
  @callback mean(s) :: float() | non_finite() | lazy_s() | nil
  @callback median(s) :: float() | non_finite() | lazy_s() | nil
  @callback mode(s) :: s | lazy_s()
  @callback variance(s, ddof :: non_neg_integer()) :: float() | non_finite() | lazy_s() | nil
  @callback standard_deviation(s, ddof :: non_neg_integer()) ::
              float() | non_finite() | lazy_s() | nil
  @callback quantile(s, float()) ::
              number() | non_finite() | Date.t() | NaiveDateTime.t() | lazy_s() | nil
  @callback nil_count(s) :: number() | lazy_s()
  @callback product(s) :: float() | non_finite() | lazy_s() | nil
  @callback skew(s, bias? :: boolean()) :: float() | non_finite() | lazy_s() | nil
  @callback correlation(s, s, ddof :: non_neg_integer(), method :: atom()) ::
              float() | non_finite() | lazy_s() | nil
  @callback covariance(s, s, ddof :: non_neg_integer()) :: float() | non_finite() | lazy_s() | nil
  @callback all?(s) :: boolean() | lazy_s()
  @callback any?(s) :: boolean() | lazy_s()
  @callback row_index(s) :: s | lazy_s()

  # Cumulative

  @callback cumulative_max(s, reverse? :: boolean()) :: s
  @callback cumulative_min(s, reverse? :: boolean()) :: s
  @callback cumulative_sum(s, reverse? :: boolean()) :: s
  @callback cumulative_product(s, reverse? :: boolean()) :: s

  # Local minima/maxima

  @callback peaks(s, :max | :min) :: s

  # Arithmetic

  @callback add(out_dtype :: dtype(), s, s) :: s
  @callback subtract(out_dtype :: dtype(), s, s) :: s
  @callback multiply(out_dtype :: dtype(), s, s) :: s
  @callback divide(out_dtype :: dtype(), s, s) :: s
  @callback quotient(s, s) :: s
  @callback remainder(s, s) :: s
  @callback pow(out_dtype :: dtype(), s, s) :: s
  @callback log(argument :: s) :: s
  @callback log(argument :: s, base :: float()) :: s
  @callback exp(s) :: s
  @callback abs(s) :: s
  @callback clip(s, number(), number()) :: s

  # Trigonometry

  @callback acos(s) :: s
  @callback asin(s) :: s
  @callback atan(s) :: s
  @callback cos(s) :: s
  @callback sin(s) :: s
  @callback tan(s) :: s

  # Comparisons

  @callback equal(s, s) :: s
  @callback not_equal(s, s) :: s
  @callback greater(s, s) :: s
  @callback greater_equal(s, s) :: s
  @callback less(s, s) :: s
  @callback less_equal(s, s) :: s
  @callback all_equal(s, s) :: boolean() | lazy_s()

  @callback binary_and(s, s) :: s
  @callback binary_or(s, s) :: s
  @callback binary_in(s, s) :: s

  # Float predicates
  @callback is_finite(s) :: s
  @callback is_infinite(s) :: s
  @callback is_nan(s) :: s

  # Float round
  @callback round(s, decimals :: non_neg_integer()) :: s
  @callback floor(s) :: s
  @callback ceil(s) :: s

  # Coercion

  # Sort

  @callback sort(
              s,
              descending? :: boolean(),
              maintain_order? :: boolean(),
              multithreaded? :: boolean(),
              nulls_last? :: boolean()
            ) :: s
  @callback argsort(
              s,
              descending? :: boolean(),
              maintain_order? :: boolean(),
              multithreaded? :: boolean(),
              nulls_last? :: boolean()
            ) :: s
  @callback reverse(s) :: s

  # Distinct

  @callback distinct(s) :: s
  @callback unordered_distinct(s) :: s
  @callback n_distinct(s) :: integer() | lazy_s()
  @callback frequencies(s) :: df

  # Categorisation

  @callback cut(s, [float()], [String.t()] | nil, String.t() | nil, String.t() | nil) ::
              df
  @callback qcut(s, [float()], [String.t()] | nil, String.t() | nil, String.t() | nil) ::
              df

  # Rolling

  @callback window_sum(
              s,
              window_size :: integer(),
              weights :: [float()] | nil,
              min_periods :: integer() | nil,
              center :: boolean()
            ) :: s
  @callback window_min(
              s,
              window_size :: integer(),
              weights :: [float()] | nil,
              min_periods :: integer() | nil,
              center :: boolean()
            ) :: s
  @callback window_max(
              s,
              window_size :: integer(),
              weights :: [float()] | nil,
              min_periods :: integer() | nil,
              center :: boolean()
            ) :: s
  @callback window_mean(
              s,
              window_size :: integer(),
              weights :: [float()] | nil,
              min_periods :: integer() | nil,
              center :: boolean()
            ) :: s
  @callback window_median(
              s,
              window_size :: integer(),
              weights :: [float()] | nil,
              min_periods :: integer() | nil,
              center :: boolean()
            ) :: s
  @callback window_standard_deviation(
              s,
              window_size :: integer(),
              weights :: [float()] | nil,
              min_periods :: integer() | nil,
              center :: boolean()
            ) :: s

  # Exponentially weighted windows

  @callback ewm_mean(
              s,
              alpha :: float(),
              adjust :: boolean(),
              min_periods :: integer(),
              ignore_nils :: boolean()
            ) :: s

  @callback ewm_standard_deviation(
              s,
              alpha :: float(),
              adjust :: boolean(),
              bias :: boolean(),
              min_periods :: integer(),
              ignore_nils :: boolean()
            ) :: s

  @callback ewm_variance(
              s,
              alpha :: float(),
              adjust :: boolean(),
              bias :: boolean(),
              min_periods :: integer(),
              ignore_nils :: boolean()
            ) :: s

  # Nulls

  @callback fill_missing_with_strategy(s, :backward | :forward | :min | :max | :mean) :: s
  @callback fill_missing_with_value(s, :nan | valid_types()) :: s
  @callback is_nil(s) :: s
  @callback is_not_nil(s) :: s

  # Escape hatch

  @callback transform(s, fun) :: s

  # Inversions

  @callback unary_not(s) :: s

  # Strings

  @callback contains(s, String.t()) :: s
  @callback upcase(s) :: s
  @callback downcase(s) :: s
  @callback replace(s, String.t(), String.t()) :: s
  @callback strip(s, String.t() | nil) :: s
  @callback lstrip(s, String.t() | nil) :: s
  @callback rstrip(s, String.t() | nil) :: s
  @callback substring(s, integer(), non_neg_integer() | nil) :: s
  @callback split(s, String.t()) :: s
  @callback split_into(s, String.t(), list(String.t() | atom())) :: s
  @callback json_decode(s, dtype()) :: s
  @callback json_path_match(s, String.t()) :: s
  @callback count_matches(s, String.t()) :: s

  ## String - Regular expression versions
  @callback re_contains(s, String.t()) :: s
  @callback re_replace(s, String.t(), String.t()) :: s
  @callback re_count_matches(s, String.t()) :: s
  @callback re_scan(s, String.t()) :: s
  @callback re_named_captures(s, String.t()) :: s

  # Date / DateTime

  @callback day_of_week(s) :: s
  @callback day_of_year(s) :: s
  @callback week_of_year(s) :: s
  @callback month(s) :: s
  @callback year(s) :: s
  @callback hour(s) :: s
  @callback minute(s) :: s
  @callback second(s) :: s

  # List
  @callback join(s, String.t()) :: s
  @callback lengths(s) :: s
  @callback member?(s, valid_types()) :: s

  # Struct
  @callback field(s, String.t()) :: s

  # Functions

  @doc """
  Create a new `Series`.
  """
  def new(data, dtype) do
    dtype = Explorer.Shared.normalise_dtype!(dtype)

    %Explorer.Series{data: data, dtype: dtype}
  end

  alias Inspect.Algebra, as: A
  alias Explorer.Series

  @doc """
  Default inspect implementation for backends.
  """
  def inspect(series, backend, n_rows, inspect_opts, opts \\ [])
      when is_binary(backend) and (is_integer(n_rows) or is_nil(n_rows) or is_binary(n_rows)) and
             is_list(opts) do
    elide_columns? = Keyword.get(opts, :elide_columns, false)
    open = A.color("[", :list, inspect_opts)
    close = A.color("]", :list, inspect_opts)

    type =
      series
      |> Series.dtype()
      |> Explorer.Shared.dtype_to_string()

    dtype = A.color("#{type} ", :atom, inspect_opts)

    data = build_series_data(series, inspect_opts, elide_columns?)

    A.concat([
      A.color(backend, :atom, inspect_opts),
      open,
      "#{n_rows || "???"}",
      close,
      A.line(),
      dtype,
      data
    ])
  end

  defp build_series_data(_series, _inspect_opts, true) do
    "???"
  end

  defp build_series_data(series, inspect_opts, _elide_columns?) do
    series =
      case inspect_opts.limit do
        :infinity -> series
        limit when is_integer(limit) -> Series.slice(series, 0, limit + 1)
      end

    series
    |> Series.to_list()
    |> Explorer.Shared.to_doc(inspect_opts)
  end
end