Specs

add(set :: t(), item :: Discord.SortedSet.Types.supported_term()) ::
  t() | Discord.SortedSet.Types.common_errors()

Adds an item to the set.

To retrieve the index of where the item was added, see index_add/2 There is no performance penalty for requesting the index while adding an item.

Performance

Unlike a hash based set that has O(1) inserts, the SortedSet is O(log(N/B)) + O(log(B)) where N is the number of items in the SortedSet and B is the Bucket Size.

Specs

at(set :: t(), index :: non_neg_integer(), default :: any()) ::
  (item_or_default :: Discord.SortedSet.Types.supported_term() | any())
  | Discord.SortedSet.Types.common_errors()

Retrieve an item at the given index.

If the index is out of bounds then the optional default value is returned instead, this defaults to nil if not provided.

Specs

debug(set :: t()) :: String.t()

Returns a string representation of the underlying Rust data structure.

This function is mostly provided as a convenience, since the actual data structure is stored in the NIF memory space it can be difficult to introspect the data structure as it changes. This function allows the caller to get the view of the data structure as Rust sees it.

Specs

default_bucket_size() :: pos_integer()

Helper function to access the default_bucket_size module attribute

Specs

default_capacity() :: pos_integer()

Helper function to access the default_capacity module attribute

Specs

find_index(set :: t(), item :: Discord.SortedSet.Types.supported_term()) ::
  non_neg_integer() | nil | Discord.SortedSet.Types.common_errors()

Finds the index of the specified term.

Since SortedSet does enforce uniqueness of terms there is no need to worry about which index gets returned, the term either exists in the set or does not exist in the set. If the term exists the index of the term is returned, if not then nil is returned.

Specs

from_enumerable(
  terms :: [Discord.SortedSet.Types.supported_term()],
  bucket_size :: pos_integer()
) ::
  t() | Discord.SortedSet.Types.common_errors()

Construct a new SortedSet from an enumerable.

The enumerable does not have to be proper to use this constructor, if the enumerable is proper then the from_proper_enumerable/2 function should be used as it is slightly faster.

See from_proper_enumerable/2 for a definition of proper.

Specs

from_proper_enumerable(
  terms :: [Discord.SortedSet.Types.supported_term()],
  bucket_size :: pos_integer()
) :: t() | Discord.SortedSet.Types.common_errors()

Construct a new SortedSet from a proper enumerable

An enumerable is considered proper if it satisfies the following:

• Enumerable is sorted
• Enumerable contains no duplicates
• Enumerable is made up entirely of supported terms

This method of construction is much faster than iterative construction.

See from_enumerable/2 for enumerables that are not proper.

Specs

index_add(set :: t(), item :: any()) ::
  {index :: non_neg_integer() | nil, t()}
  | Discord.SortedSet.Types.common_errors()

Adds an item to the set, returning the index.

If the index is not needed the add/2 function can be used instead, there is no performance difference between these two functions.

Performance

Unlike a hash based set that has O(1) inserts, the SortedSet is O(log(N/B)) + O(log(B)) where N is the number of items in the SortedSet and B is the Bucket Size.

Specs

index_remove(set :: t(), item :: any()) ::
  {index :: non_neg_integer(), t()} | Discord.SortedSet.Types.common_errors()

Removes an item from the set, returning the index of the item before removal.

If the item is not present in the set, the index nil is returned along with the set. If the index is not needed the remove/2 function can be used instead, there is no performance difference between these two functions.

Performance

Unlike a hash based set that has O(1) removes, the SortedSet is O(log(N/B)) + O(log(B)) where N is the number of items in the SortedSet and B is the Bucket Size.

Returns information about this NIF's memory allocations, as reported by jemalloc.

Specs

new(capacity :: pos_integer(), bucket_size :: pos_integer()) ::
  t() | Discord.SortedSet.Types.common_errors()

Construct a new SortedSet with a given capacity and bucket size

See the README for more information about how SortedSet works.

Capacity

The caller can pre-allocate capacity for the data structure, this can be helpful when the initial set's size can be reasonably estimated. The pre-allocation will be for the buckets but not the contents of the buckets, so setting a high capacity and not using it is still memory efficient.

Bucket Size

Internally the SortedSet is a collection of sorted Buckets, this allows the SortedSet to out perform a simpler array of items. The default bucket size was chosen based off of benchmarking to select a size that performs well for most uses.

Returned Resource

Unlike a native Elixir data structure, the data in the SortedSet is held in the NIF's memory space, there are some important caveats to be aware of when using the SortedSet.

First, new/2 returns a reference/0 instead of a struct/0. This reference/0 can be used to access the SortedSet in subsequent calls.

Second, because the data is stored in the NIF's memory space, the data structure acts more like a mutable data structure than a standard immutable data structure. It's best to treat the reference/0 like one would treat an ETS tid.

Specs

remove(set :: t(), item :: any()) ::
  t() | Discord.SortedSet.Types.common_errors()

Removes an item from the set.

If the item is not present in the set, the set is simply returned. To retrieve the index of where the item was removed from, see index_remove/2. There is no performance penalty for requesting the index while removing an item.

Performance

Unlike a hash based set that has O(1) removes, the SortedSet is O(log(N/B)) + O(log(B)) where N is the number of items in the SortedSet and B is the Bucket Size.

Specs

size(set :: t()) :: non_neg_integer() | Discord.SortedSet.Types.common_errors()

Get the size of a SortedSet

This function follows the standard Elixir naming convention, size/1 take O(1) time as the size is tracked with every addition and removal.

Specs

slice(set :: t(), start :: non_neg_integer(), amount :: non_neg_integer()) ::
  [Discord.SortedSet.Types.supported_term()]
  | Discord.SortedSet.Types.common_errors()

Retrieves a slice of the SortedSet starting at the specified index and including up to the specified amount.

slice/3 will return an empty list if the start index is out of bounds. If the amount exceeds the number of items from the start index to the end of the set then all terms up to the end of the set will be returned. This means that the length of the list returned by slice will fall into the range of [0, amount]

Specs

to_list(set :: t()) ::
  [Discord.SortedSet.Types.supported_term()]
  | Discord.SortedSet.Types.common_errors()

Converts a SortedSet into a List

This operation requires copying the entire SortedSet out of NIF space and back into Elixir space it can be very expensive.