List

public final class List<Element> : RLMSwiftCollectionBase, RealmCollectionImpl where Element : RealmCollectionValue
extension List: ObservableObject, RealmSubscribable
extension List: _ObjcBridgeable
extension List: MutableCollection
extension List: _RealmSchemaDiscoverable, SchemaDiscoverable where Element: _RealmSchemaDiscoverable
extension List: _HasPersistedType, _Persistable, _DefaultConstructible where Element: _Persistable
extension List: Decodable where Element: Decodable
extension List: Encodable where Element: Encodable

List is the container type in Realm used to define to-many relationships.

Like Swift’s Array, List is a generic type that is parameterized on the type it stores. This can be either an Object subclass or one of the following types: Bool, Int, Int8, Int16, Int32, Int64, Float, Double, String, Data, Date, Decimal128, and ObjectId (and their optional versions)

Unlike Swift’s native collections, Lists are reference types, and are only immutable if the Realm that manages them is opened as read-only.

Lists can be filtered and sorted with the same predicates as Results<Element>.

Properties of List type defined on Object subclasses must be declared as let and cannot be dynamic.

Show on GitHub

Initializers

  • Creates a List that holds Realm model objects of type Element.

    Declaration

    Swift

    public override init()
    Show on GitHub

Object Retrieval

  • Returns the object at the given index (get), or replaces the object at the given index (set).

    Warning

    You can only set an object during a write transaction.

    Declaration

    Swift

    public subscript(position: Int) -> Element { get set }

    Parameters

    index

    The index of the object to retrieve or replace.
    Show on GitHub

KVC

  • Returns an Array containing the results of invoking valueForKey(_:) using key on each of the collection’s objects.

    Declaration

    Swift

    @nonobjc
public func value(forKey key: String) -> [AnyObject]
    Show on GitHub

  • Returns an Array containing the results of invoking valueForKeyPath(_:) using keyPath on each of the collection’s objects.

    Declaration

    Swift

    @nonobjc
public func value(forKeyPath keyPath: String) -> [AnyObject]

    Parameters

    keyPath

    The key path to the property whose values are desired.
    Show on GitHub

Mutation

  • Appends the given object to the end of the list.

    If the object is managed by a different Realm than the receiver, a copy is made and added to the Realm managing the receiver.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Swift

    public func append(_ object: Element)

    Parameters

    object

    An object.
    Show on GitHub

  • Appends the objects in the given sequence to the end of the list.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Swift

    public func append<S>(objectsIn objects: S) where Element == S.Element, S : Sequence
    Show on GitHub

  • Inserts an object at the given index.

    Warning

    This method may only be called during a write transaction.

    Warning

    This method will throw an exception if called with an invalid index.

    Declaration

    Swift

    public func insert(_ object: Element, at index: Int)

    Parameters

    object

    An object.
    index

    The index at which to insert the object.
    Show on GitHub

  • Removes an object at the given index. The object is not removed from the Realm that manages it.

    Warning

    This method may only be called during a write transaction.

    Warning

    This method will throw an exception if called with an invalid index.

    Declaration

    Swift

    public func remove(at index: Int)

    Parameters

    index

    The index at which to remove the object.
    Show on GitHub

  • Removes all objects from the list. The objects are not removed from the Realm that manages them.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Swift

    public func removeAll()
    Show on GitHub

  • Replaces an object at the given index with a new object.

    Warning

    This method may only be called during a write transaction.

    Warning

    This method will throw an exception if called with an invalid index.

    Declaration

    Swift

    public func replace(index: Int, object: Element)

    Parameters

    index

    The index of the object to be replaced.
    object

    An object.
    Show on GitHub

  • Moves the object at the given source index to the given destination index.

    Warning

    This method may only be called during a write transaction.

    Warning

    This method will throw an exception if called with invalid indices.

    Declaration

    Swift

    public func move(from: Int, to: Int)

    Parameters

    from

    The index of the object to be moved.
    to

    index to which the object at from should be moved.
    Show on GitHub

  • Exchanges the objects in the list at given indices.

    Warning

    This method may only be called during a write transaction.

    Warning

    This method will throw an exception if called with invalid indices.

    Declaration

    Swift

    public func swapAt(_ index1: Int, _ index2: Int)

    Parameters

    index1

    The index of the object which should replace the object at index index2.
    index2

    The index of the object which should replace the object at index index1.
    Show on GitHub

  • Returns a human-readable description of the objects contained in the List.

    Declaration

    Swift

    public override var description: String { get }
    Show on GitHub

List

  • A publisher that emits Void each time the collection changes.

    Despite the name, this actually emits after the collection has changed.

    Declaration

    Swift

    public var objectWillChange: RealmPublishers.WillChange<List> { get }
    Show on GitHub

  • Replace the given subRange of elements with newElements.

    Declaration

    Swift

    public func replaceSubrange<C: Collection, R>(_ subrange: R, with newElements: C)
    where C.Iterator.Element == Element, R: RangeExpression, List<Element>.Index == R.Bound

    Parameters

    subrange

    The range of elements to be replaced.
    newElements

    The new elements to be inserted into the List.
    Show on GitHub

MutableCollection conformance, range replaceable collection emulation

  • Declaration

    Swift

    public typealias SubSequence = Slice<List>
    Show on GitHub

  • Returns the objects at the given range (get), or replaces the objects at the given range with new objects (set).

    Warning

    Objects may only be set during a write transaction.

    Declaration

    Swift

    public subscript(bounds: Range<Int>) -> SubSequence { get set }

    Parameters

    index

    The index of the object to retrieve or replace.
    Show on GitHub

  • Removes the specified number of objects from the beginning of the list. The objects are not removed from the Realm that manages them.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Swift

    public func removeFirst(_ number: Int = 1)
    Show on GitHub

  • Removes the specified number of objects from the end of the list. The objects are not removed from the Realm that manages them.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Swift

    public func removeLast(_ number: Int = 1)
    Show on GitHub

  • Inserts the items in the given collection into the list at the given position.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Swift

    public func insert<C>(contentsOf newElements: C, at i: Int) where Element == C.Element, C : Collection
    Show on GitHub

  • Removes objects from the list at the given range.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Swift

    public func removeSubrange<R>(_ boundsExpression: R) where R : RangeExpression, R.Bound == Int
    Show on GitHub

Available where Element: _RealmSchemaDiscoverable

Available where Element: _Persistable

Available where Element: Decodable

Available where Element: ObjectBase & RealmCollectionValue

  • projectTo will map the original List of Objects or List of EmbeddedObjects in to ProjectedCollection.

    For example:

     class Person: Object {
     @Persisted var dogs: List<Dog>
 }
 class PersonProjection: Projection<Person> {
     @Projected(\Person.dogs.projectTo.name) var dogNames: ProjectedCollection<String>
 }

    In this code the Person‘s dogs list will be prijected to the list of dogs names via projectTo

    Declaration

    Swift

    public var projectTo: CollectionElementMapper<Element> { get }
    Show on GitHub