LinkingObjects
public final class LinkingObjects<T: Object>: LinkingObjectsBase
LinkingObjects
is an auto-updating container type. It represents a collection of objects that
link to its parent object.
LinkingObjects
can be queried with the same predicates as List<T>
and Results<T>
.
LinkingObjects
always reflects the current state of the Realm on the current thread,
including during write transactions on the current thread. The one exception to
this is when using for...in
enumeration, which will always enumerate over the
linking objects that were present when the enumeration is begun, even if some of them
are deleted or modified to no longer link to the target object during the enumeration.
LinkingObjects
can only be used as a property on Object
models. Properties of this type must
be declared as let
and cannot be dynamic
.
-
Returns the object at the given
index
.Declaration
Swift
public subscript(index: Int) -> T
Parameters
index
The index.
Return Value
The object at the given
index
. -
The element type contained in this collection.
Declaration
Swift
public typealias Element = T
-
The Realm which manages this linking objects collection, or
nil
if the collection is unmanaged.Declaration
Swift
public var realm: Realm?
-
Indicates if the linking objects collection is no longer valid.
The linking objects collection becomes invalid if
invalidate
is called on the containingrealm
.An invalidated linking objects can be accessed, but will always be empty.
Declaration
Swift
public var invalidated: Bool
-
The number of objects in the linking objects.
Declaration
Swift
public var count: Int
-
Creates an instance of a
LinkingObjects
. This initializer should only be called when declaring a property on a Realm model.Declaration
Swift
public init(fromType type: T.Type, property propertyName: String)
Parameters
type
The type of the object owning the property this
LinkingObjects
should refer to.propertyName
The property name of the property this
LinkingObjects
should refer to. -
Returns a description of the objects contained within the linking objects.
Declaration
Swift
public override var description: String
-
Returns the index of an object in the linking objects collection, or
nil
if the object is not present.Declaration
Swift
public func indexOf(object: T) -> Int?
Parameters
object
The object whose index is being queried.
-
Returns the index of the first object matching the given predicate, or
nil
if no objects match.Declaration
Swift
public func indexOf(predicate: NSPredicate) -> Int?
Parameters
predicate
The predicate with which to filter the objects.
-
Returns the index of the first object matching the given predicate, or
nil
if no objects match.Declaration
Swift
public func indexOf(predicateFormat: String, _ args: AnyObject...) -> Int?
Parameters
predicateFormat
A predicate format string, optionally followed by a variable number of arguments.
-
Returns the first object in the linking objects collection, or
nil
if the collection is empty.Declaration
Swift
public var first: T?
-
Returns the last object in the linking objects collection, or
nil
if collection is empty.Declaration
Swift
public var last: T?
-
Returns an
Array
containing the results of invokingvalueForKey(_:)
withkey
on each of the linking objects collection’s objects.Declaration
Swift
public override func valueForKey(key: String) -> AnyObject?
Parameters
key
The name of the property whose values are desired.
-
Returns an
Array
containing the results of invokingvalueForKeyPath(_:)
withkeyPath
on each of the linking objects collection’s objects.Declaration
Swift
public override func valueForKeyPath(keyPath: String) -> AnyObject?
Parameters
keyPath
The key path to the property whose values are desired.
-
Invokes
setValue(_:forKey:)
on each of the linking objects collection’s objects using the specifiedvalue
andkey
.Warning
This method may only be called during a write transaction.
Declaration
Swift
public override func setValue(value: AnyObject?, forKey key: String)
Parameters
value
The value to set the property to.
key
The name of the property whose value should be set on each object.
-
Returns a
Results
containing all objects matching the given predicate in the linking objects collection.Declaration
Swift
public func filter(predicateFormat: String, _ args: AnyObject...) -> Results<T>
Parameters
predicateFormat
A predicate format string, optionally followed by a variable number of arguments.
-
Returns a
Results
containing the objects in the linking objects collection, but sorted.Objects are sorted based on the values of the given property. For example, to sort a collection of
Student
s from youngest to oldest based on theirage
property, you might callstudents.sorted("age", ascending: true)
.Warning
Collections may only be sorted by properties of boolean,
NSDate
, single and double-precision floating point, integer, and string types.Declaration
Swift
public func sorted(property: String, ascending: Bool = true) -> Results<T>
Parameters
property
The name of the property to sort by.
ascending
The direction to sort in.
-
Returns a
Results
containing the objects in the linking objects collection, but sorted.Warning
Collections may only be sorted by properties of boolean,
NSDate
, single and double-precision floating point, integer, and string types.Declaration
Swift
public func sorted<S: SequenceType where S.Generator.Element == SortDescriptor>(sortDescriptors: S) -> Results<T>
Parameters
sortDescriptors
A sequence of
SortDescriptor
s to sort by.
-
Returns the minimum (lowest) value of the given property among all the objects represented by the linking objects collection.
Warning
Only a property whose type conforms to the
MinMaxType
protocol can be specified.Declaration
Swift
public func min<U: MinMaxType>(property: String) -> U?
Parameters
property
The name of a property whose minimum value is desired.
Return Value
The minimum value of the property, or
nil
if the collection is empty. -
Returns the maximum (highest) value of the given property among all the objects represented by the linking objects collection.
Warning
Only a property whose type conforms to the
MinMaxType
protocol can be specified.Declaration
Swift
public func max<U: MinMaxType>(property: String) -> U?
Parameters
property
The name of a property whose minimum value is desired.
Return Value
The maximum value of the property, or
nil
if the collection is empty. -
Returns the sum of the values of a given property over all the objects represented by the linking objects collection.
Warning
Only a property whose type conforms to the
AddableType
protocol can be specified.Declaration
Swift
public func sum<U: AddableType>(property: String) -> U
Parameters
property
The name of a property whose values should be summed.
Return Value
The sum of the given property.
-
Returns the average value of a given property over all the objects represented by the linking objects collection.
Warning
Only the name of a property whose type conforms to the
AddableType
protocol can be specified.Declaration
Swift
public func average<U: AddableType>(property: String) -> U?
Parameters
property
The name of a property whose average value should be calculated.
Return Value
The average value of the given property, or
nil
if the collection is empty.
-
Registers a block to be called each time the linking objects collection changes.
The block will be asynchronously called with the initial linking objects collection, and then called again after each write transaction which changes either any of the objects in the collection, or which objects are in the collection.
The
change
parameter that is passed to the block reports, in the form of indices within the collection, which of the objects were added, removed, or modified during each write transaction. See theRealmCollectionChange
documentation for more information on the change information supplied and an example of how to use it to update aUITableView
.At the time when the block is called, the linking objects collection will be fully evaluated and up-to-date, and as long as you do not perform a write transaction on the same thread or explicitly call
realm.refresh()
, accessing it will never perform blocking work.Notifications are delivered via the standard run loop, and so can’t be delivered while the run loop is blocked by other activity. When notifications can’t be delivered instantly, multiple notifications may be coalesced into a single notification. This can include the notification with the initial set of objects. For example, the following code performs a write transaction immediately after adding the notification block, so there is no opportunity for the initial notification to be delivered first. As a result, the initial notification will reflect the state of the Realm after the write transaction.
let dog = realm.objects(Dog.self).first! let owners = dog.owners print("owners.count: \(owners.count)") // => 0 let token = owners.addNotificationBlock { changes in switch changes { case .Initial(let owners): // Will print "owners.count: 1" print("owners.count: \(owners.count)") break case .Update: // Will not be hit in this example break case .Error: break } } try! realm.write { realm.add(Person.self, value: ["name": "Mark", dogs: [dog]]) } // end of runloop execution context
You must retain the returned token for as long as you want updates to be sent to the block. To stop receiving updates, call
stop()
on the token.Warning
This method cannot be called during a write transaction, or when the containing Realm is read-only.
Declaration
Swift
public func addNotificationBlock(block: (RealmCollectionChange<LinkingObjects> -> Void)) -> NotificationToken
Parameters
block
The block to be called whenever a change occurs.
Return Value
A token which must be retained for as long as you want updates to be delivered.
-
Returns an
RLMGenerator
that yields successive elements in the results.Declaration
Swift
public func generate() -> RLMGenerator<T>
-
The position of the first element in a non-empty collection. Identical to
endIndex
in an empty collection.Declaration
Swift
public var startIndex: Int
-
The collection’s
past the end
position.endIndex
is not a valid argument to subscript, and is always reachable fromstartIndex
by zero or more applications ofsuccessor()
.Declaration
Swift
public var endIndex: Int