SortedList

const val INVALID_POSITION = -1: Int

Used by indexOf when the item cannot be found in the list.

SortedList(klass: Class<T!>, callback: SortedList.Callback<T!>)

Creates a new SortedList of type T.

SortedList(
    klass: Class<T!>,
    callback: SortedList.Callback<T!>,
    initialCapacity: Int
)

Creates a new SortedList of type T.

fun add(item: T!): Int

Adds the given item to the list. If this is a new item, SortedList calls onInserted.

If the item already exists in the list and its sorting criteria is not changed, it is replaced with the existing Item. SortedList uses areItemsTheSame to check if two items are the same item and uses areContentsTheSame to decide whether it should call onChanged or not. In both cases, it always removes the reference to the old item and puts the new item into the backing array even if areContentsTheSame returns false.

If the sorting criteria of the item is changed, SortedList won't be able to find its duplicate in the list which will result in having a duplicate of the Item in the list. If you need to update sorting criteria of an item that already exists in the list, use updateItemAt. You can find the index of the item using indexOf before you update the object.

fun addAll(items: Array<T!>): Unit

Adds the given items to the list. Does not modify or retain the input.

fun addAll(items: (Mutable)Collection<T!>): Unit

Adds the given items to the list. Does not modify or retain the input.

fun addAll(items: Array<T!>, mayModifyInput: Boolean): Unit

Adds the given items to the list. Equivalent to calling add in a loop, except the callback events may be in a different order/granularity since addAll can batch them for better performance.

If allowed, will reference the input array during, and possibly after, the operation to avoid extra memory allocation, in which case you should not continue to reference or modify the array yourself.

fun beginBatchedUpdates(): Unit

Batches adapter updates that happen after calling this method and before calling endBatchedUpdates. For example, if you add multiple items in a loop and they are placed into consecutive indices, SortedList calls onInserted only once with the proper item count. If an event cannot be merged with the previous event, the previous event is dispatched to the callback instantly.

After running your data updates, you must call endBatchedUpdates which will dispatch any deferred data change event to the current callback.

A sample implementation may look like this:

    mSortedList.beginBatchedUpdates();
    try {
        mSortedList.add(item1)
        mSortedList.add(item2)
        mSortedList.remove(item3)
        ...
    } finally {
        mSortedList.endBatchedUpdates();
    }

Instead of using this method to batch calls, you can use a Callback that extends BatchedCallback. In that case, you must make sure that you are manually calling dispatchLastEvent right after you complete your data changes. Failing to do so may create data inconsistencies with the Callback.

If the current Callback is an instance of BatchedCallback, calling this method has no effect.

fun clear(): Unit

Removes all items from the SortedList.

fun endBatchedUpdates(): Unit

Ends the update transaction and dispatches any remaining event to the callback.

fun get(index: Int): T!

Returns the item at the given index.

fun indexOf(item: T!): Int

Returns the position of the provided item.

fun recalculatePositionOfItemAt(index: Int): Unit

This method can be used to recalculate the position of the item at the given index, without triggering an onChanged callback.

If you are editing objects in the list such that their position in the list may change but you don't want to trigger an onChange animation, you can use this method to re-position it. If the item changes position, SortedList will call onMoved without calling onChanged.

A sample usage may look like:

    final int position = mSortedList.indexOf(item);
    item.incrementPriority(); // assume items are sorted by priority
    mSortedList.recalculatePositionOfItemAt(position);

In the example above, because the sorting criteria of the item has been changed, mSortedList.indexOf(item) will not be able to find the item. This is why the code above first gets the position before editing the item, edits it and informs the SortedList that item should be repositioned.

fun remove(item: T!): Boolean

Removes the provided item from the list and calls onRemoved.

fun removeItemAt(index: Int): T!

Removes the item at the given index and calls onRemoved.

fun replaceAll(items: Array<T!>): Unit

Replaces the current items with the new items, dispatching ListUpdateCallback events for each change detected as appropriate. Does not modify or retain the input.

fun replaceAll(items: (Mutable)Collection<T!>): Unit

Replaces the current items with the new items, dispatching ListUpdateCallback events for each change detected as appropriate. Does not modify or retain the input.

fun replaceAll(items: Array<T!>, mayModifyInput: Boolean): Unit

Replaces the current items with the new items, dispatching ListUpdateCallback events for each change detected as appropriate.

If allowed, will reference the input array during, and possibly after, the operation to avoid extra memory allocation, in which case you should not continue to reference or modify the array yourself.

Note: this method does not detect moves or dispatch onMoved events. It instead treats moves as a remove followed by an add and therefore dispatches onRemoved and onRemoved events. See DiffUtil if you want your implementation to dispatch move events.

fun size(): Int

The number of items in the list.

fun updateItemAt(index: Int, item: T!): Unit

Updates the item at the given index and calls onChanged and/or onMoved if necessary.

You can use this method if you need to change an existing Item such that its position in the list may change.

If the new object is a different object (get(index) != item) and areContentsTheSame returns true, SortedList avoids calling onChanged otherwise it calls onChanged.

If the new position of the item is different than the provided index, SortedList calls onMoved.