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 |
Constants | |
---|---|
static Int |
Used by |
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 |
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 |
open Unit |
clear() Removes all items from the SortedList. |
open Unit |
Ends the update transaction and dispatches any remaining event to the callback. |
open T |
Returns the item at the given index. |
open Int |
indexOf(item: T) Returns the position of the provided item. |
open Unit |
recalculatePositionOfItemAt(index: Int) This method can be used to recalculate the position of the item at the given index, without triggering an |
open Boolean |
remove(item: T) Removes the provided item from the list and calls |
open T |
removeItemAt(index: Int) Removes the item at the given index and calls |
open Unit |
replaceAll(@NonNull items: Array<T>, mayModifyInput: Boolean) Replaces the current items with the new items, dispatching |
open Unit |
replaceAll(@NonNull vararg items: T) Replaces the current items with the new items, dispatching |
open Unit |
replaceAll(@NonNull items: MutableCollection<T>) Replaces the current items with the new items, dispatching |
open Int |
size() The number of items in the list. |
open Unit |
updateItemAt(index: Int, item: T) Updates the item at the given index and calls |
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 |
SortedList.Callback<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 |
SortedList.Callback<T>: The callback that controls the behavior of SortedList. |
initialCapacity |
Int: 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 |
Boolean: If true, SortedList is allowed to modify and permanently reference the input array. |
See Also
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.