Realm.List

Instances of this class will be returned when accessing object properties whose type is "list" (see ObjectSchemaProperty). The objects contained in a list are accessible through its index properties and may only be modified inside a write transaction.

Extends

Members

length
readonly

The number of objects in the collection.

Type:
number

Methods

pop()Realm.Object or undefined

Remove the last object from the list and return it.

Throws:
  • Error

    • If not inside a write transaction.

Returns: Realm.Object or undefined if the list is empty.
push(object)number

Add one or more objects to the end of the list.

Parameters:
Throws:
  • TypeError

    • If an object is of the wrong type.

  • Error

    • If not inside a write transaction.

Returns: number equal to the new length of the list after adding objects.
shift()Realm.Object or undefined

Remove the first object from the list and return it.

Throws:
  • Error

    • If not inside a write transaction.

Returns: Realm.Object or undefined if the list is empty.
splice(index, count, object)[Realm.Object, ...]

Changes the contents of the list by removing objects and/or inserting new objects.

See: Array.prototype.splice
Parameters:
  • index
    • Type: number

    • The start index. If greater than the length of the list, the start index will be set to the length instead. If negative, then the start index will be counted from the end of the list (e.g. list.length - index).

  • count optional
    • Type: number

    • The number of objects to remove from the list. If not provided, then all objects from the start index through the end of the list will be removed.

  • object optional repeatable
    • Type: Realm.Object

    • Objects to insert into the list starting at index.

Returns: [Realm.Object, ...] containing the objects that were removed from the list. The array is empty if no objects were removed.
unshift(object)number

Add one or more objects to the beginning of the list.

Parameters:
Throws:
  • TypeError

    • If an object is of the wrong type.

  • Error

    • If not inside a write transaction.

Returns: number equal to the new length of the list after adding objects.

Inherited Methods

entries()Iterator
See: Array.prototype.entries
Returns: Iterator of each [index, object] pair in the collection
Since: 0.11.0
every(callback, thisArg)boolean
See: Array.prototype.every
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the collection. If this function returns true for every object, then this method will return true. This function takes three arguments:

      • object – The current object being processed in the collection.
      • index – The index of the object being processed in the collection.
      • collection – The collection itself.
  • thisArg optional
    • Type: object

    • The value of this when callback is called.

Returns: boolean representing if callback returned true for every object in the collection.
Since: 0.11.0
filtered(query, arg)Realm.Results

Returns new Results that represent this collection being filtered by the provided query.

Parameters:
  • query
    • Type: string

    • Query used to filter objects from the collection.

  • arg optional repeatable
    • Type: any

    • Each subsequent argument is used by the placeholders (e.g. $0, $1, $2, …) in the query.

Throws:
  • Error

    • If the query or any other argument passed into this method is invalid.

Returns: Realm.Results filtered according to the provided query.
Example:
let merlots = wines.filtered('variety == "Merlot" && vintage <= $0', maxYear);
find(callback, thisArg)Realm.Object or undefined
See: Array.prototype.find
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the collection. If this function returns true, then that object will be returned by this method. This function takes three arguments:

      • object – The current object being processed in the collection.
      • index – The index of the object being processed in the collection.
      • collection – The collection itself.
  • thisArg optional
    • Type: object

    • The value of this when callback is called.

Returns: Realm.Object or undefined if the callback did not return true for any object in the collection.
Since: 0.11.0
findIndex(callback, thisArg)number
See: Array.prototype.findIndex
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the collection. If this function returns true, then the index of that object will be returned by this method. This function takes three arguments:

      • object – The current object being processed in the collection.
      • index – The index of the object being processed in the collection.
      • collection – The collection itself.
  • thisArg optional
    • Type: object

    • The value of this when callback is called.

Returns: number representing the index where the callback returned true, or -1 if true was never returned.
Since: 0.11.0
forEach(callback, thisArg)
See: Array.prototype.forEach
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the collection. This function takes three arguments:

      • object – The current object being processed in the collection.
      • index – The index of the object being processed in the collection.
      • collection – The collection itself.
  • thisArg optional
    • Type: object

    • The value of this when callback is called.

Since: 0.11.0
isValid()boolean

Checks if this collection has not been deleted and is part of a valid Realm.

Returns: boolean indicating if the collection can be safely accessed.
Since: 0.14.0
join(separator)string

Joins all objects in the collection into a string.

See: Array.prototype.join
Parameters:
  • separator optional
    • Type: string
    • Default: ","

    • A string to separate the return values of the toString() method being called on each object in the collection.

Returns: string
Since: 0.11.0
keys()Iterator
See: Array.prototype.keys
Returns: Iterator of each index in the collection
Since: 0.11.0
map(callback, thisArg)[any, ...]
See: Array.prototype.map
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the collection. This function takes three arguments:

      • object – The current object being processed in the collection.
      • index – The index of the object being processed in the collection.
      • collection – The collection itself.
  • thisArg optional
    • Type: object

    • The value of this when callback is called.

Returns: [any, ...] – the return values of callback after being called on every object in the collection.
Since: 0.11.0
reduce(callback, initialValue)any
See: Array.prototype.reduce
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the collection. This function takes four arguments:

      • previousValue – The value previously returned in the last invocation of the callback, or initialValue, if supplied.
      • object – The current object being processed in the collection.
      • index – The index of the object being processed in the collection.
      • collection – The collection itself.
  • initialValue optional
    • Type: object

    • The value to use as the first argument to the first call of the callback.

Throws:
  • TypeError

    • If the collection is empty and no initialValue was supplied.

Returns: any – the value returned by the final invocation of callback, except for the following special cases:
  • If collection consists of a single object, and no initalValue was supplied, then that object will be returned.
  • If the collection is empty, then initialValue must be supplied and will be returned.
Since: 0.11.0
reduceRight(callback, initialValue)any
See: Array.prototype.reduceRight
Parameters:
  • callback
    • Type: function

    • Function to execute on each object, from right to left, in the collection. This function takes four arguments:

      • previousValue – The value previously returned in the last invocation of the callback, or initialValue, if supplied.
      • object – The current object being processed in the collection.
      • index – The index of the object being processed in the collection.
      • collection – The collection itself.
  • initialValue optional
    • Type: object

    • The value to use as the first argument to the first call of the callback.

Throws:
  • TypeError

    • If the collection is empty and no initialValue was supplied.

Returns: any – the value returned by the final invocation of callback, except for the following special cases:
  • If collection consists of a single object, and no initalValue was supplied, then that object will be returned.
  • If the collection is empty, then initialValue must be supplied and will be returned.
Since: 0.11.0
slice(start, end)[Realm.Object, ...]
See: Array.prototype.slice
Parameters:
  • start optional
    • Type: number
    • Default: 0

    • The start index. If negative, then the start index will be counted from the end of the collection.

  • end optional
    • Type: number

    • The end index. The objects up to, but not including, the end index will be include in the return value. If negative, then the end index will be counted from the end of the collection. If omitted, then all objects from the start index will be included in the return value.

Returns: [Realm.Object, ...] containing the objects from the start index up to, but not including, the end index.
Since: 0.11.0
snapshot()Realm.Results

Create a frozen snapshot of the collection. This means objects added to and removed from the original collection will not be reflected in the Results returned by this method. However, objects deleted from the Realm will become null at their respective indices. This is not a deep snapshot, meaning the objects contained in this snapshot will continue to update as changes are made to them.

Returns: Realm.Results which will not live update.
some(callback, thisArg)boolean
See: Array.prototype.some
Parameters:
  • callback
    • Type: function

    • Function to execute on each object in the collection. If this function ever returns true, then this method will return true. This function takes three arguments:

      • object – The current object being processed in the collection.
      • index – The index of the object being processed in the collection.
      • collection – The collection itself.
  • thisArg optional
    • Type: object

    • The value of this when callback is called.

Returns: boolean – true when callback returns true for an object in the collection, otherwise false.
Since: 0.11.0
sorted(descriptor, reverse)Realm.Results

Returns new Results that represent this collection being sorted by the provided property (or properties) of each object.

Parameters:
  • descriptor
    • Type: string or [SortDescriptor, ...]

    • The property name(s) to sort the objects in the collection.

  • reverse optional
    • Type: boolean
    • Default: false

    • May only be provided if descriptor is a string.

Throws:
  • Error

    • If a specified property does not exist.

Returns: Realm.Results sorted according to the arguments passed in
Symbol.iterator()Iterator

This is the same method as the values() method. Its presence makes collections iterable, thus able to be used with ES6 for-of loops, ... spread operators, and more.

See: Symbol.iterator and the iterable protocol
Returns: Iterator of each Realm object in the collection
Example:
for (let object of collection) {
  // do something with each object
}
Since: 0.11.0
values()Iterator
See: Array.prototype.values
Returns: Iterator of each Realm object in the collection
Since: 0.11.0