The Android Developer Challenge is back! Submit your idea before December 2.

SortedList

open class SortedList<T : Any!>
kotlin.Any
   ↳ androidx.recyclerview.widget.SortedList

A Sorted list implementation that can keep items in order and also notify for changes in the list such that it can be bound to a RecyclerView.Adapter.

It keeps items ordered using the Callback#compare(Object, Object) method and uses binary search to retrieve items. If the sorting criteria of your items may change, make sure you call appropriate methods while editing them to avoid data inconsistencies.

You can control the order of items and change notifications via the Callback parameter.

Summary

Nested classes

open

A callback implementation that can batch notify events dispatched by the SortedList.

abstract

The class that controls the behavior of the SortedList.

Constants

static Int

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

Public constructors

<init>(@NonNull klass: Class<T>, @NonNull callback: SortedList.Callback<T>)

Creates a new SortedList of type T.

<init>(@NonNull klass: Class<T>, @NonNull callback: SortedList.Callback<T>, initialCapacity: Int)

Creates a new SortedList of type T.

Public methods

open Int
add(item: T)

Adds the given item to the list.

open Unit
addAll(@NonNull items: Array<T>, mayModifyInput: Boolean)

Adds the given items to the list.

open Unit
addAll(@NonNull vararg items: T)

Adds the given items to the list.

open Unit
addAll(@NonNull items: MutableCollection<T>)

Adds the given items to the list.

open Unit

Batches adapter updates that happen after calling this method and before calling endBatchedUpdates().

open Unit

Removes all items from the SortedList.

open Unit

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

open T
get(index: Int)

Returns the item at the given index.

open Int
indexOf(item: T)

Returns the position of the provided item.

open Unit

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

open Boolean
remove(item: T)

Removes the provided item from the list and calls Callback#onRemoved(int, int).

open T
removeItemAt(index: Int)

Removes the item at the given index and calls Callback#onRemoved(int, int).

open Unit
replaceAll(@NonNull items: Array<T>, mayModifyInput: Boolean)

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

open Unit
replaceAll(@NonNull vararg items: T)

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

open Unit
replaceAll(@NonNull items: MutableCollection<T>)

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

open Int

The number of items in the list.

open Unit
updateItemAt(index: Int, item: T)

Updates the item at the given index and calls Callback#onChanged(int, int) and/or Callback#onMoved(int, int) if necessary.

Constants

INVALID_POSITION

static val INVALID_POSITION: Int

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

Value: -1

Public constructors

<init>

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

Creates a new SortedList of type T.

Parameters
klass Class<T>: The class of the contents of the SortedList.
callback Class<T>: The callback that controls the behavior of SortedList.

<init>

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

Creates a new SortedList of type T.

Parameters
klass Class<T>: The class of the contents of the SortedList.
callback Class<T>: The callback that controls the behavior of SortedList.
initialCapacity Class<T>: The initial capacity to hold items.

Public methods

add

open fun add(item: T): Int

Adds the given item to the list. If this is a new item, SortedList calls Callback#onInserted(int, int).

If the item already exists in the list and its sorting criteria is not changed, it is replaced with the existing Item. SortedList uses Callback#areItemsTheSame(Object, Object) to check if two items are the same item and uses Callback#areContentsTheSame(Object, Object) to decide whether it should call Callback#onChanged(int, int) 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 Callback#areContentsTheSame(Object, Object) 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(int, Object). You can find the index of the item using indexOf(Object) before you update the object.

Parameters
item T: The item to be added into the list.
Return
Int: The index of the newly added item.

addAll

open fun addAll(@NonNull items: Array<T>, mayModifyInput: Boolean): Unit

Adds the given items to the list. Equivalent to calling SortedList#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.

Parameters
items Array<T>: Array of items to be added into the list.
mayModifyInput Array<T>: If true, SortedList is allowed to modify and permanently reference the input array.

addAll

open fun addAll(@NonNull vararg items: T): Unit

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

Parameters
items T: Array of items to be added into the list.

addAll

open fun addAll(@NonNull items: MutableCollection<T>): Unit

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

Parameters
items MutableCollection<T>: Collection of items to be added into the list.

beginBatchedUpdates

open 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 Callback#onInserted(int, int) 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 BatchedCallback#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.

clear

open fun clear(): Unit

Removes all items from the SortedList.

endBatchedUpdates

open fun endBatchedUpdates(): Unit

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

get

open fun get(index: Int): T

Returns the item at the given index.

Parameters
index Int: The index of the item to retrieve.
Return
T: The item at the given index.
Exceptions
java.lang.IndexOutOfBoundsException if provided index is negative or larger than the size of the list.

indexOf

open fun indexOf(item: T): Int

Returns the position of the provided item.

Parameters
item T: The item to query for position.
Return
Int: The position of the provided item or INVALID_POSITION if item is not in the list.

recalculatePositionOfItemAt

open fun recalculatePositionOfItemAt(index: Int): Unit

This method can be used to recalculate the position of the item at the given index, without triggering an Callback#onChanged(int, int) 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 Callback#onMoved(int, int) without calling Callback#onChanged(int, int).

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.
Parameters
index Int: The current index of the Item whose position should be re-calculated.

remove

open fun remove(item: T): Boolean

Removes the provided item from the list and calls Callback#onRemoved(int, int).

Parameters
item T: The item to be removed from the list.
Return
Boolean: True if item is removed, false if item cannot be found in the list.

removeItemAt

open fun removeItemAt(index: Int): T

Removes the item at the given index and calls Callback#onRemoved(int, int).

Parameters
index Int: The index of the item to be removed.
Return
T: The removed item.

replaceAll

open fun replaceAll(@NonNull 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 ListUpdateCallback#onMoved(int, int) events. It instead treats moves as a remove followed by an add and therefore dispatches ListUpdateCallback#onRemoved(int, int) and ListUpdateCallback#onRemoved(int, int) events. See DiffUtil if you want your implementation to dispatch move events.

Parameters
items Array<T>: Array of items to replace current items.
mayModifyInput Array<T>: If true, SortedList is allowed to modify and permanently reference the input array.

See Also

replaceAll

open fun replaceAll(@NonNull vararg items: 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.

Parameters
items T: Array of items to replace current items.

replaceAll

open fun replaceAll(@NonNull items: MutableCollection<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.

Parameters
items MutableCollection<T>: Array of items to replace current items.

size

open fun size(): Int

The number of items in the list.

Return
Int: The number of items in the list.

updateItemAt

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

Updates the item at the given index and calls Callback#onChanged(int, int) and/or Callback#onMoved(int, int) 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 Callback#areContentsTheSame(Object, Object) returns true, SortedList avoids calling Callback#onChanged(int, int) otherwise it calls Callback#onChanged(int, int).

If the new position of the item is different than the provided index, SortedList calls Callback#onMoved(int, int).

Parameters
index Int: The index of the item to replace
item Int: The item to replace the item at the given Index.

See Also