public interface OrderedRealmCollection<E extends RealmModel> extends List<E>, RealmCollection<E>
OrderedRealmCollection is a collection which maintains an ordering for its elements. Every
element in the OrderedRealmCollection has an index. Each element can thus be accessed by its
index, with the first index being zero. Normally, OrderedRealmCollections allow duplicate
elements, as compared to Sets, where elements have to be unique.
There are three types of OrderedRealmCollection. RealmResults and RealmList are live
collections. They are up-to-date all the time and they will never contain an invalid RealmObject.
OrderedRealmCollectionSnapshot is different. An OrderedRealmCollectionSnapshot can be created from
another OrderedRealmCollection. Its size and elements order stay the same as the original collection's when
it was created. OrderedRealmCollectionSnapshot may contain invalid RealmObjects if the objects get
deleted.
Using iterators to iterate on
OrderedRealmCollection will always work. You can delete or modify the elements
without impacting the iterator. See below example:
RealmResults<Dog> dogs = realm.where(Dog.class).findAll();
int s = dogs.size(); // 10
realm.beginTransaction();
for (Dog dog : dogs) {
dog.deleteFromRealm();
s = dogs.size(); // This will be decreased by 1 every time after a dog is removed.
}
realm.commitTransaction();
s = dogs.size(); // 0
An iterator created from a live collection will create a stable view when the iterator is created, allowing you to
delete and modify elements while iterating without impacting the iterator. However, the RealmResults backing
the iterator will still be live updated meaning that size and order of elements can change when iterating.
RealmList has the same behaviour as RealmResults since they are both live collections.
A simple for-loop is different. See below example:
RealmResults<Dog> dogs = realm.where(Dog.class).findAll();
realm.beginTransaction();
for (int i = 0; i < dogs.size(); i++) {
dogs.get(i).deleteFromRealm();
}
realm.commitTransaction();
s = dogs.size(); // 5
The above example only deletes half of elements in the RealmResults. This is because of dogs.size()
decreased by 1 for every loop. The deletion happens in the loop will immediately impact the size of
RealmResults. To solve this problem, you can create a OrderedRealmCollectionSnapshot from the
RealmResults or RealmList and do simple for-loop on that instead:
RealmResults<Dog> dogs = realm.where(Dog.class).findAll();
OrderedRealmCollectionSnapshot snapshot = dogs.createSnapshot();
// dogs.size() == 10 && snapshot.size() == 10
realm.beginTransaction();
for (int i = 0; i < snapshot.size(); i++) {
snapshot.get(0).deleteFromRealm();
// snapshot.get(0).isValid() == false
}
realm.commitTransaction();
// dogs.size() == 0 && snapshot.size() == 10
As you can see, after deletion, the size and elements order of snapshot stay the same as before. But the element at
the position becomes invalid.| Modifier and Type | Method and Description |
|---|---|
OrderedRealmCollectionSnapshot<E> |
createSnapshot()
Creates a snapshot from this
OrderedRealmCollection. |
boolean |
deleteFirstFromRealm()
Deletes the first object from the Realm.
|
void |
deleteFromRealm(int location)
Deletes the object at the given index from the Realm.
|
boolean |
deleteLastFromRealm()
Deletes the last object from the Realm.
|
E |
first()
Gets the first object from the collection.
|
E |
first(E defaultValue)
Gets the first object from the collection.
|
E |
last()
Gets the last object from the collection.
|
E |
last(E defaultValue)
Gets the last object from the collection.
|
RealmResults<E> |
sort(String fieldName)
Sorts a collection based on the provided field in ascending order.
|
RealmResults<E> |
sort(String[] fieldNames,
Sort[] sortOrders)
Sorts a collection based on the provided fields and sort orders.
|
RealmResults<E> |
sort(String fieldName,
Sort sortOrder)
Sorts a collection based on the provided field and sort order.
|
RealmResults<E> |
sort(String fieldName1,
Sort sortOrder1,
String fieldName2,
Sort sortOrder2)
Sorts a collection based on the provided fields and sort orders.
|
add, add, addAll, addAll, clear, contains, containsAll, equals, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, replaceAll, retainAll, set, size, sort, spliterator, subList, toArray, toArrayaverage, contains, deleteAllFromRealm, isLoaded, isManaged, isValid, load, max, maxDate, min, minDate, sum, whereparallelStream, removeIf, streamE first()
IndexOutOfBoundsException - if the collection is empty.E first(E defaultValue)
E last()
IndexOutOfBoundsException - if the collection is empty.E last(E defaultValue)
RealmResults<E> sort(String fieldName)
fieldName - the field name to sort by. Only fields of type boolean, short, int, long, float, double, Date,
and String are supported.RealmResults will be created and returned. The original collection stays unchanged.IllegalArgumentException - if field name does not exist or it has an invalid type.IllegalStateException - if the Realm is closed, called on the wrong thread or the collection is
an unmanaged collection.RealmResults<E> sort(String fieldName, Sort sortOrder)
fieldName - the field name to sort by. Only fields of type boolean, short, int, long, float, double, Date,
and String are supported.sortOrder - the direction to sort by.RealmResults will be created and returned. The original collection stays unchanged.IllegalArgumentException - if field name does not exist or has an invalid type.IllegalStateException - if the Realm is closed, called on the wrong thread or the collection is
an unmanaged collection.RealmResults<E> sort(String fieldName1, Sort sortOrder1, String fieldName2, Sort sortOrder2)
fieldName1 - first field name. Only fields of type boolean, short, int, long, float,
double, Date, and String are supported.sortOrder1 - sort order for first field.fieldName2 - second field name. Only fields of type boolean, short, int, long, float,
double, Date, and String are supported.sortOrder2 - sort order for second field.RealmResults will be created and returned. The original collection stays unchanged.IllegalArgumentException - if a field name does not exist or has an invalid type.IllegalStateException - if the Realm is closed, called on the wrong thread or the collection is
an unmanaged collection.RealmResults<E> sort(String[] fieldNames, Sort[] sortOrders)
fieldNames - an array of field names to sort by. Only fields of type boolean, short, int, long, float,
double, Date, and String are supported.sortOrders - the directions to sort by.RealmResults will be created and returned. The original collection stays unchanged.IllegalArgumentException - if a field name does not exist or has an invalid type.IllegalStateException - if the Realm is closed, called on the wrong thread or the collection is
an unmanaged collection.void deleteFromRealm(int location)
location - the array index identifying the object to be removed.IndexOutOfBoundsException - if location < 0 || location >= size().IllegalStateException - if the Realm is closed or the method is called from the wrong thread.UnsupportedOperationException - if the collection is unmanaged.boolean deleteFirstFromRealm()
true if an object was deleted, false otherwise.IllegalStateException - if the Realm is closed or the method is called on the wrong thread.UnsupportedOperationException - if the collection is unmanaged.boolean deleteLastFromRealm()
true if an object was deleted, false otherwise.IllegalStateException - if the Realm is closed or the method is called from the wrong thread.UnsupportedOperationException - if the collection is unmanaged.OrderedRealmCollectionSnapshot<E> createSnapshot()
OrderedRealmCollection.IllegalStateException - if the Realm is closed or the method is called from the wrong thread.UnsupportedOperationException - if the collection is unmanaged.OrderedRealmCollectionSnapshot