Adds a single entry to an existing leaderboard. Invalid entries will return an error. If the id already exists, will return an error.

See Entry section of the module doc for information about entries.

Examples

iex> {:ok, board} = Leaderboard.create(name: :foo)
iex> {:ok, board} = Leaderboard.add(board, {-1, :id1})
iex> Leaderboard.count(board)
1
iex> Leaderboard.add(board, :invalid_entry)
{:error, :bad_entry}
iex> Leaderboard.add(board, {-1, :id1})
{:error, :entry_already_exists}

Same as add/2 but returns the leaderboard or raises.

Updates an entry in an existing leaderboard, or adds it if the id doesn’t exist. Invalid entries will return an error.

See Entry section of the module doc for information about entries.

Examples

iex> {:ok, board} = Leaderboard.create(name: :foo)
iex> {:ok, board} = Leaderboard.add_or_update(board, {1, :id1})
iex> Leaderboard.get(board, :id1)
{{1, :id1}, :id1, {0, {1, 99.0}}}
iex> {:ok, board} = Leaderboard.add_or_update(board, {2, :id1})
iex> Leaderboard.get(board, :id1)
{{2, :id1}, :id1, {0, {1, 99.0}}}

Same as add_or_update/2 but returns the leaderboard or raises.

Populates a leaderboard with entries asynchronously. Only works with CxLeaderboard.EtsStore. Invalid entries are silently skipped.

See Entry section of the module doc for information about entries.

Examples

iex> {:ok, board} = Leaderboard.create(name: :foo)
iex> {:ok, board} = Leaderboard.async_populate(board, [
...>   {-2, :id1},
...>   {-3, :id2}
...> ])
iex> Leaderboard.count(board)
0
iex> :timer.sleep(100)
iex> Leaderboard.count(board)
2

Same as async_populate/2 but returns the leaderboard or raises.

Returns a stream of bottom leaderboard records.

Examples

iex> {:ok, board} = Leaderboard.create(name: :foo)
iex> {:ok, board} = Leaderboard.populate(board, [{-2, :id1}, {-3, :id2}])
iex> Leaderboard.bottom(board) |> Enum.take(1)
[{{-2, :id1}, :id1, {1, {2, 50.0}}}]

Clears the data from a leaderboard.

Examples

iex> {:ok, board} = Leaderboard.create(name: :foo)
iex> {:ok, board} = Leaderboard.populate(board, [{-2, :id1}, {-3, :id2}])
iex> Leaderboard.count(board)
2
iex> {:ok, board} = Leaderboard.clear(board)
iex> Leaderboard.count(board)
0

Same as clear/1 but returns the leaderboard or raises.

When your leaderboard is started as a server elsewhere, use this function to get a reference to be able to interact with it. See docs for start_link/2 for more information on client/server mode of operation.

Returns the number of records in a leaderboard. This number is stored in the leaderboard, so this is an O(1) operation.

Examples

iex> {:ok, board} = Leaderboard.create(name: :foo)
iex> {:ok, board} = Leaderboard.populate(board, [{-2, :id1}, {-3, :id2}])
iex> Leaderboard.count(board)
2

Creates a new leaderboard.

Options

• :store - storage engine to use for the leaderboard. Supports CxLeaderboard.EtsStore and CxLeaderboard.TermStore. Default: CxLeaderboard.EtsStore.

• :indexer - indexer to use for stats calculation. The default indexer calculates rank with offsets (e.g. 1,1,3) and percentile based on same-or- lower scores, within 1-99 range. Learn more about making custom indexers in CxLeaderboard.Indexer module doc.

• :name - sets the name identifying the leaderboard. Only needed when using CxLeaderboard.EtsStore.

Examples

iex> Leaderboard.create(name: :global)
{:ok,
  %Leaderboard{
    state: :global,
    store: CxLeaderboard.EtsStore,
    indexer: %CxLeaderboard.Indexer{},
    data: []
  }
}

Same as create/1 but returns the leaderboard or raises an error.

Retrieves a single record from a leaderboard by id. Returns nil if record is not found.

Examples

iex> {:ok, board} = Leaderboard.create(name: :foo)
iex> {:ok, board} = Leaderboard.populate(board, [{-2, :id1}, {-3, :id2}])
iex> Leaderboard.get(board, :id1)
{{-2, :id1}, :id1, {1, {2, 50.0}}}
iex> Leaderboard.get(board, :missing_id)
nil

Retrieves a range of records from a leaderboard around the given id. Returns an empty list if the requested record is not found. If the range goes out of leaderboard bounds will stop at the top/bottom without error. If the given range is in reverse direction, returns entries in reverse direction as well.

Examples

iex> {:ok, board} = Leaderboard.create(name: :foo)
iex> {:ok, board} = Leaderboard.populate(board, [
...>   {-4, :id1},
...>   {-3, :id2},
...>   {-2, :id3},
...>   {-1, :id4}
...> ])
iex> Leaderboard.get(board, :id3, -1..0)
[
  {{-3, :id2}, :id2, {1, {2, 74.5}}},
  {{-2, :id3}, :id3, {2, {3, 50.0}}}
]
iex> Leaderboard.get(board, :id3, 0..-1)
[
  {{-2, :id3}, :id3, {2, {3, 50.0}}},
  {{-3, :id2}, :id2, {1, {2, 74.5}}}
]

Populates a leaderboard with entries replacing any existing content. Invalid entries are silently skipped.

See Entry section of the module doc for information about entries.

Examples

iex> {:ok, board} = Leaderboard.create(name: :foo)
iex> {:ok, board} = Leaderboard.populate(board, [{-2, :id1}, {-3, :id2}])
iex> Leaderboard.count(board)
2

Same as populate/2 but returns the leaderboard or raises.

Removes an entry from a leaderboard by id. If the id is not in the leaderboard, will return an error.

Examples

iex> {:ok, board} = Leaderboard.create(name: :foo)
iex> {:ok, board} = Leaderboard.populate(board, [{-2, :id1}, {-3, :id2}])
iex> {:ok, board} = Leaderboard.remove(board, :id1)
iex> Leaderboard.count(board)
1
iex> Leaderboard.remove(board, :id1)
{:error, :entry_not_found}

Same as remove/2 but returns the leaderboard or raises.

If your chosen storage engine supports server/client operation (CxLeaderboard.EtsStore does), then you could set Leaderboard as a worker in your application’s children list. For each leaderboard you would just add a worker, passing it a name. Then in your applicaiton you can use client_for/2 to get the reference to it that you can use to call all the functions in this module.

Examples

defmodule Foo.Application do
  use Application

  def start(_type, _args) do
    import Supervisor.Spec

    # Make sure your data is available as a stream
    data_stream = Foo.LeaderboardData.stream()

    children = [
      worker(CxLeaderboard.Leaderboard, [
        name: :global,
        data: data_stream
      ])
    ]

    opts = [strategy: :one_for_one, name: Foo.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

# Elsewhere in your application
alias CxLeaderboard.Leaderboard

global_lb = Leaderboard.client_for(:global)
global_lb
|> Leaderboard.top()
|> Enum.take(10)

Indexer is configured at the client level (it’s passed to server with each function), therefore if you want the leaderboard to use a custom indexer, all you need to do is:

lb = Leaderboard.client_for(:global, indexer: my_custom_indexer)

See the Stats section of this module’s doc to learn more about indexers.

Returns a stream of top leaderboard records.

Examples

iex> {:ok, board} = Leaderboard.create(name: :foo)
iex> {:ok, board} = Leaderboard.populate(board, [{-2, :id1}, {-3, :id2}])
iex> Leaderboard.top(board) |> Enum.take(1)
[{{-3, :id2}, :id2, {0, {1, 99.0}}}]

Updates a single entry in an existing leaderboard. Invalid entries will return an error. If the id is not in the leaderboard, will return an error.

See Entry section of the module doc for information about entries.

Examples

iex> {:ok, board} = Leaderboard.create(name: :foo)
iex> {:ok, board} = Leaderboard.populate(board, [{-2, :id1}, {-3, :id2}])
iex> {:ok, board} = Leaderboard.update(board, {-5, :id1})
iex> Leaderboard.get(board, :id1)
{{-5, :id1}, :id1, {0, {1, 99.0}}}
iex> Leaderboard.update(board, {-2, :missing_id})
{:error, :entry_not_found}

Same as update/2 but returns the leaderboard or raises.