RLMArray
Objective-C
@interface RLMArray<RLMObjectType> : NSObject <RLMCollection>
Swift
@_nonSendable(_assumed) class RLMArray<RLMObjectType> : NSObject, RLMCollection where RLMObjectType : AnyObject
RLMArray
is the container type in Realm used to define to-many relationships.
Unlike an NSArray
, RLMArray
s hold a single type, specified by the objectClassName
property.
This is referred to in these docs as the “type” of the array.
When declaring an RLMArray
property, the type must be marked as conforming to a
protocol by the same name as the objects it should contain (see the
RLM_COLLECTION_TYPE
macro). In addition, the property can be declared using Objective-C
generics for better compile-time type safety.
RLM_COLLECTION_TYPE(ObjectType)
...
@property RLMArray<ObjectType *><ObjectType> *arrayOfObjectTypes;
RLMArray
s can be queried with the same predicates as RLMObject
and RLMResult
s.
RLMArray
s cannot be created directly. RLMArray
properties on RLMObject
s are
lazily created when accessed, or can be obtained by querying a Realm.
Key-Value Observing
RLMArray
supports array key-value observing on RLMArray
properties on RLMObject
subclasses, and the invalidated
property on RLMArray
instances themselves is
key-value observing compliant when the RLMArray
is attached to a managed
RLMObject
(RLMArray
s on unmanaged RLMObject
s will never become invalidated).
Because RLMArray
s are attached to the object which they are a property of, they
do not require using the mutable collection proxy objects from
-mutableArrayValueForKey:
or KVC-compatible mutation methods on the containing
object. Instead, you can call the mutation methods on the RLMArray
directly.
-
The number of objects in the array.
Declaration
Objective-C
@property (nonatomic, readonly) NSUInteger count;
Swift
var count: UInt { get }
-
The type of the objects in the array.
Declaration
Objective-C
@property (nonatomic, readonly) RLMPropertyType type;
Swift
var type: RLMPropertyType { get }
-
Indicates whether the objects in the collection can be
nil
.Declaration
Objective-C
@property (nonatomic, readonly, getter=isOptional) BOOL optional;
Swift
var isOptional: Bool { get }
-
The class name of the objects contained in the array.
Will be
nil
iftype
is not RLMPropertyTypeObject.Declaration
Objective-C
@property (nonatomic, copy, readonly, nullable) NSString *objectClassName;
Swift
var objectClassName: String? { get }
-
Indicates if the array can no longer be accessed.
Declaration
Objective-C
@property (nonatomic, readonly, getter=isInvalidated) BOOL invalidated;
Swift
var isInvalidated: Bool { get }
-
Indicates if the array is frozen.
Frozen arrays are immutable and can be accessed from any thread. Frozen arrays are created by calling
-freeze
on a managed live array. Unmanaged arrays are never frozen.Declaration
Objective-C
@property (nonatomic, readonly, getter=isFrozen) BOOL frozen;
Swift
var isFrozen: Bool { get }
-
Returns the object at the index specified.
Declaration
Objective-C
- (nonnull RLMObjectType)objectAtIndex:(NSUInteger)index;
Swift
func object(at index: UInt) -> RLMObjectType
Parameters
index
The index to look up.
Return Value
An object of the type contained in the array.
-
Returns an array containing the objects in the array at the indexes specified by a given index set.
nil
will be returned if the index set contains an index out of the arrays bounds.Declaration
Objective-C
- (nullable NSArray<RLMObjectType> *)objectsAtIndexes: (nonnull NSIndexSet *)indexes;
Swift
func objects(at indexes: IndexSet) -> [RLMObjectType]?
Parameters
indexes
The indexes in the array to retrieve objects from.
Return Value
The objects at the specified indexes.
-
Returns the first object in the array.
Returns
nil
if called on an empty array.Declaration
Objective-C
- (nullable RLMObjectType)firstObject;
Swift
func firstObject() -> RLMObjectType?
Return Value
An object of the type contained in the array.
-
Returns the last object in the array.
Returns
nil
if called on an empty array.Declaration
Objective-C
- (nullable RLMObjectType)lastObject;
Swift
func lastObject() -> RLMObjectType?
Return Value
An object of the type contained in the array.
-
Adds an object to the end of the array.
Warning
This method may only be called during a write transaction.
Declaration
Objective-C
- (void)addObject:(nonnull RLMObjectType)object;
Swift
func add(_ object: RLMObjectType)
Parameters
object
An object of the type contained in the array.
-
Adds an array of objects to the end of the array.
Warning
This method may only be called during a write transaction.
Declaration
Objective-C
- (void)addObjects:(nonnull id<NSFastEnumeration>)objects;
Swift
func addObjects(_ objects: any NSFastEnumeration)
Parameters
objects
An enumerable object such as
NSArray
orRLMResults
which contains objects of the same class as the array. -
Inserts an object at the given index.
Throws an exception if the index exceeds the bounds of the array.
Warning
This method may only be called during a write transaction.
Declaration
Objective-C
- (void)insertObject:(nonnull RLMObjectType)anObject atIndex:(NSUInteger)index;
Swift
func insert(_ anObject: RLMObjectType, at index: UInt)
Parameters
anObject
An object of the type contained in the array.
index
The index at which to insert the object.
-
Removes an object at the given index.
Throws an exception if the index exceeds the bounds of the array.
Warning
This method may only be called during a write transaction.
Declaration
Objective-C
- (void)removeObjectAtIndex:(NSUInteger)index;
Swift
func removeObject(at index: UInt)
Parameters
index
The array index identifying the object to be removed.
-
Removes the last object in the array.
This is a no-op if the array is already empty.
Warning
This method may only be called during a write transaction.Declaration
Objective-C
- (void)removeLastObject;
Swift
func removeLastObject()
-
Removes all objects from the array.
Warning
This method may only be called during a write transaction.Declaration
Objective-C
- (void)removeAllObjects;
Swift
func removeAllObjects()
-
Replaces an object at the given index with a new object.
Throws an exception if the index exceeds the bounds of the array.
Warning
This method may only be called during a write transaction.
Declaration
Objective-C
- (void)replaceObjectAtIndex:(NSUInteger)index withObject:(nonnull RLMObjectType)anObject;
Swift
func replaceObject(at index: UInt, with anObject: RLMObjectType)
Parameters
index
The index of the object to be replaced.
anObject
An object (of the same type as returned from the
objectClassName
selector). -
Moves the object at the given source index to the given destination index.
Throws an exception if the index exceeds the bounds of the array.
Warning
This method may only be called during a write transaction.
Declaration
Objective-C
- (void)moveObjectAtIndex:(NSUInteger)sourceIndex toIndex:(NSUInteger)destinationIndex;
Swift
func moveObject(at sourceIndex: UInt, to destinationIndex: UInt)
Parameters
sourceIndex
The index of the object to be moved.
destinationIndex
The index to which the object at
sourceIndex
should be moved. -
Exchanges the objects in the array at given indices.
Throws an exception if either index exceeds the bounds of the array.
Warning
This method may only be called during a write transaction.
Declaration
Objective-C
- (void)exchangeObjectAtIndex:(NSUInteger)index1 withObjectAtIndex:(NSUInteger)index2;
Swift
func exchangeObject(at index1: UInt, withObjectAt index2: UInt)
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
.
-
Returns the index of an object in the array.
Returns
NSNotFound
if the object is not found in the array.Declaration
Objective-C
- (NSUInteger)indexOfObject:(nonnull RLMObjectType)object;
Swift
func index(of object: RLMObjectType) -> UInt
Parameters
object
An object (of the same type as returned from the
objectClassName
selector). -
Returns the index of the first object in the array matching the predicate.
Declaration
Objective-C
- (NSUInteger)indexOfObjectWhere:(nonnull NSString *)predicateFormat, ...;
Parameters
predicateFormat
A predicate format string, optionally followed by a variable number of arguments.
Return Value
The index of the object, or
NSNotFound
if the object is not found in the array. -
Returns the index of the first object in the array matching the predicate.
Declaration
Objective-C
- (NSUInteger)indexOfObjectWithPredicate:(nonnull NSPredicate *)predicate;
Swift
func indexOfObject(with predicate: NSPredicate) -> UInt
Parameters
predicate
The predicate with which to filter the objects.
Return Value
The index of the object, or
NSNotFound
if the object is not found in the array. -
Returns all the objects matching the given predicate in the array.
Declaration
Objective-C
- (nonnull RLMResults<RLMObjectType> *)objectsWhere: (nonnull NSString *)predicateFormat, ...;
Parameters
predicateFormat
A predicate format string, optionally followed by a variable number of arguments.
Return Value
An
RLMResults
of objects that match the given predicate. -
Returns all the objects matching the given predicate in the array.
Declaration
Objective-C
- (nonnull RLMResults<RLMObjectType> *)objectsWithPredicate: (nonnull NSPredicate *)predicate;
Swift
func objects(with predicate: NSPredicate) -> RLMResults
Parameters
predicate
The predicate with which to filter the objects.
Return Value
An
RLMResults
of objects that match the given predicate -
Returns a sorted
RLMResults
from the array.Declaration
Objective-C
- (nonnull RLMResults<RLMObjectType> *) sortedResultsUsingKeyPath:(nonnull NSString *)keyPath ascending:(BOOL)ascending;
Swift
func sortedResults(usingKeyPath keyPath: String, ascending: Bool) -> RLMResults
Parameters
keyPath
The key path to sort by.
ascending
The direction to sort in.
Return Value
An
RLMResults
sorted by the specified key path. -
Returns a sorted
RLMResults
from the array.Declaration
Objective-C
- (nonnull RLMResults<RLMObjectType> *)sortedResultsUsingDescriptors: (nonnull NSArray<RLMSortDescriptor *> *)properties;
Swift
func sortedResults(using properties: [RLMSortDescriptor]) -> RLMResults
Parameters
properties
An array of
RLMSortDescriptor
s to sort by.Return Value
An
RLMResults
sorted by the specified properties. -
Returns a distinct
RLMResults
from the array.Declaration
Objective-C
- (nonnull RLMResults<RLMObjectType> *)distinctResultsUsingKeyPaths: (nonnull NSArray<NSString *> *)keyPaths;
Swift
func distinctResults(usingKeyPaths keyPaths: [String]) -> RLMResults
Parameters
keyPaths
The key paths to distinct on.
Return Value
An
RLMResults
with the distinct values of the keypath(s).
-
Sorts and sections this collection from a given property key path, returning the result as an instance of
RLMSectionedResults
.Declaration
Objective-C
- (nonnull RLMSectionedResults *) sectionedResultsSortedUsingKeyPath:(nonnull NSString *)keyPath ascending:(BOOL)ascending keyBlock: (nonnull RLMSectionedResultsKeyBlock)keyBlock;
Swift
func sectionedResultsSorted(usingKeyPath keyPath: String, ascending: Bool, keyBlock: @escaping RLMSectionedResultsKeyBlock) -> RLMSectionedResults
Parameters
keyPath
The property key path to sort on.
ascending
The direction to sort in.
keyBlock
A callback which is invoked on each element in the Results collection. This callback is to return the section key for the element in the collection.
Return Value
An instance of RLMSectionedResults.
-
Sorts and sections this collection from a given array of sort descriptors, returning the result as an instance of
RLMSectionedResults
.Note
The primary sort descriptor must be responsible for determining the section key.
Declaration
Objective-C
- (nonnull RLMSectionedResults *) sectionedResultsUsingSortDescriptors: (nonnull NSArray<RLMSortDescriptor *> *)sortDescriptors keyBlock:(nonnull RLMSectionedResultsKeyBlock) keyBlock;
Swift
func sectionedResults(using sortDescriptors: [RLMSortDescriptor], keyBlock: @escaping RLMSectionedResultsKeyBlock) -> RLMSectionedResults
Parameters
sortDescriptors
An array of
RLMSortDescriptor
s to sort by.keyBlock
A callback which is invoked on each element in the Results collection. This callback is to return the section key for the element in the collection.
Return Value
An instance of RLMSectionedResults.
-
Registers a block to be called each time the array changes.
The block will be asynchronously called with the initial array, and then called again after each write transaction which changes any of the objects in the array, which objects are in the results, or the order of the objects in the array.
The
changes
parameter will benil
the first time the block is called. For each call after that, it will contain information about which rows in the array were added, removed or modified. If a write transaction did not modify any objects in the array, the block is not called at all. See theRLMCollectionChange
documentation for information on how the changes are reported and an example of updating aUITableView
.The error parameter is present only for backwards compatibility and will always be
nil
.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 results. 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.
Person *person = [[Person allObjectsInRealm:realm] firstObject]; NSLog(@"person.dogs.count: %zu", person.dogs.count); // => 0 self.token = [person.dogs addNotificationBlock(RLMArray<Dog *> *dogs, RLMCollectionChange *changes, NSError *error) { // Only fired once for the example NSLog(@"dogs.count: %zu", dogs.count) // => 1 }]; [realm transactionWithBlock:^{ Dog *dog = [[Dog alloc] init]; dog.name = @"Rex"; [person.dogs addObject:dog]; }]; // end of run loop execution context
You must retain the returned token for as long as you want updates to continue to be sent to the block. To stop receiving updates, call
-invalidate
on the token.Warning
This method cannot be called during a write transaction, or when the containing Realm is read-only.Warning
This method may only be called on a non-frozen managed array.
Declaration
Objective-C
- (nonnull RLMNotificationToken *)addNotificationBlock: (nonnull void (^)(RLMArray<RLMObjectType> *_Nullable, RLMCollectionChange *_Nullable, NSError *_Nullable))block;
Swift
func addNotificationBlock(_ block: @escaping (RLMArray<RLMObjectType>?, RLMCollectionChange?, (any Error)?) -> Void) -> RLMNotificationToken
Parameters
block
The block to be called each time the array changes.
Return Value
A token which must be held for as long as you want updates to be delivered.
-
Registers a block to be called each time the array changes.
The block will be asynchronously called with the initial array, and then called again after each write transaction which changes any of the objects in the array, which objects are in the results, or the order of the objects in the array.
The
changes
parameter will benil
the first time the block is called. For each call after that, it will contain information about which rows in the array were added, removed or modified. If a write transaction did not modify any objects in the array, the block is not called at all. See theRLMCollectionChange
documentation for information on how the changes are reported and an example of updating aUITableView
.The error parameter is present only for backwards compatibility and will always be
nil
.Notifications are delivered on the given queue. If the queue is blocked and notifications can’t be delivered instantly, multiple notifications may be coalesced into a single notification.
You must retain the returned token for as long as you want updates to continue to be sent to the block. To stop receiving updates, call
-invalidate
on the token.Warning
This method cannot be called when the containing Realm is read-only or frozen.Warning
The queue must be a serial queue.
Declaration
Objective-C
- (nonnull RLMNotificationToken *) addNotificationBlock:(nonnull void (^)(RLMArray<RLMObjectType> *_Nullable, RLMCollectionChange *_Nullable, NSError *_Nullable))block queue:(nullable dispatch_queue_t)queue;
Swift
func addNotificationBlock(_ block: @escaping (RLMArray<RLMObjectType>?, RLMCollectionChange?, (any Error)?) -> Void, queue: dispatch_queue_t?) -> RLMNotificationToken
Parameters
block
The block to be called whenever a change occurs.
queue
The serial queue to deliver notifications to.
Return Value
A token which must be held for as long as you want updates to be delivered.
-
Registers a block to be called each time the array changes.
The block will be asynchronously called with the initial array, and then called again after each write transaction which changes any of the objects in the array, which objects are in the results, or the order of the objects in the array.
The
changes
parameter will benil
the first time the block is called. For each call after that, it will contain information about which rows in the array were added, removed or modified. If a write transaction did not modify any objects in the array, the block is not called at all. See theRLMCollectionChange
documentation for information on how the changes are reported and an example of updating aUITableView
.The error parameter is present only for backwards compatibility and will always be
nil
.Notifications are delivered on the given queue. If the queue is blocked and notifications can’t be delivered instantly, multiple notifications may be coalesced into a single notification.
You must retain the returned token for as long as you want updates to continue to be sent to the block. To stop receiving updates, call
-invalidate
on the token.Warning
This method cannot be called when the containing Realm is read-only or frozen.Warning
The queue must be a serial queue.
Declaration
Objective-C
- (nonnull RLMNotificationToken *) addNotificationBlock:(nonnull void (^)(RLMArray<RLMObjectType> *_Nullable, RLMCollectionChange *_Nullable, NSError *_Nullable))block keyPaths:(nullable NSArray<NSString *> *)keyPaths queue:(nullable dispatch_queue_t)queue;
Swift
func addNotificationBlock(_ block: @escaping (RLMArray<RLMObjectType>?, RLMCollectionChange?, (any Error)?) -> Void, keyPaths: [String]?, queue: dispatch_queue_t?) -> RLMNotificationToken
Parameters
block
The block to be called whenever a change occurs.
keyPaths
The block will be called for changes occurring on these keypaths. If no key paths are given, notifications are delivered for every property key path.
queue
The serial queue to deliver notifications to.
Return Value
A token which must be held for as long as you want updates to be delivered.
-
Registers a block to be called each time the array changes.
The block will be asynchronously called with the initial array, and then called again after each write transaction which changes any of the objects in the array, which objects are in the results, or the order of the objects in the array.
The
changes
parameter will benil
the first time the block is called. For each call after that, it will contain information about which rows in the array were added, removed or modified. If a write transaction did not modify any objects in the array, the block is not called at all. See theRLMCollectionChange
documentation for information on how the changes are reported and an example of updating aUITableView
.The error parameter is present only for backwards compatibility and will always be
nil
.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 results. 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.
You must retain the returned token for as long as you want updates to continue to be sent to the block. To stop receiving updates, call
-invalidate
on the token.Warning
This method cannot be called when the containing Realm is read-only or frozen.Warning
The queue must be a serial queue.
Declaration
Objective-C
- (nonnull RLMNotificationToken *) addNotificationBlock:(nonnull void (^)(RLMArray<RLMObjectType> *_Nullable, RLMCollectionChange *_Nullable, NSError *_Nullable))block keyPaths:(nullable NSArray<NSString *> *)keyPaths;
Swift
func addNotificationBlock(_ block: @escaping (RLMArray<RLMObjectType>?, RLMCollectionChange?, (any Error)?) -> Void, keyPaths: [String]?) -> RLMNotificationToken
Parameters
block
The block to be called whenever a change occurs.
keyPaths
The block will be called for changes occurring on these keypaths. If no key paths are given, notifications are delivered for every property key path.
Return Value
A token which must be held for as long as you want updates to be delivered.
-
Returns the minimum (lowest) value of the given property among all the objects in the array.
NSNumber *min = [object.arrayProperty minOfProperty:@"age"];
Warning
You cannot use this method on
RLMObject
,RLMArray
, andNSData
properties.Declaration
Objective-C
- (nullable id)minOfProperty:(nonnull NSString *)property;
Swift
func min(ofProperty property: String) -> Any?
Parameters
property
The property whose minimum value is desired. Only properties of types
int
,float
,double
, andNSDate
are supported.Return Value
The minimum value of the property, or
nil
if the array is empty. -
Returns the maximum (highest) value of the given property among all the objects in the array.
NSNumber *max = [object.arrayProperty maxOfProperty:@"age"];
Warning
You cannot use this method on
RLMObject
,RLMArray
, andNSData
properties.Declaration
Objective-C
- (nullable id)maxOfProperty:(nonnull NSString *)property;
Swift
func max(ofProperty property: String) -> Any?
Parameters
property
The property whose maximum value is desired. Only properties of types
int
,float
,double
, andNSDate
are supported.Return Value
The maximum value of the property, or
nil
if the array is empty. -
Returns the sum of the values of a given property over all the objects in the array.
NSNumber *sum = [object.arrayProperty sumOfProperty:@"age"];
Warning
You cannot use this method on
RLMObject
,RLMArray
, andNSData
properties.Declaration
Objective-C
- (nonnull NSNumber *)sumOfProperty:(nonnull NSString *)property;
Swift
func sum(ofProperty property: String) -> NSNumber
Parameters
property
The property whose values should be summed. Only properties of types
int
,float
, anddouble
are supported.Return Value
The sum of the given property.
-
Returns the average value of a given property over the objects in the array.
NSNumber *average = [object.arrayProperty averageOfProperty:@"age"];
Warning
You cannot use this method on
RLMObject
,RLMArray
, andNSData
properties.Declaration
Objective-C
- (nullable NSNumber *)averageOfProperty:(nonnull NSString *)property;
Swift
func average(ofProperty property: String) -> NSNumber?
Parameters
property
The property whose average value should be calculated. Only properties of types
int
,float
, anddouble
are supported.Return Value
The average value of the given property, or
nil
if the array is empty.
-
Returns a frozen (immutable) snapshot of this array.
The frozen copy is an immutable array which contains the same data as this array currently contains, but will not update when writes are made to the containing Realm. Unlike live arrays, frozen arrays can be accessed from any thread.
Warning
This method cannot be called during a write transaction, or when the containing Realm is read-only.Warning
This method may only be called on a managed array.Warning
Holding onto a frozen array for an extended period while performing write transaction on the Realm may result in the Realm file growing to large sizes. SeeRLMRealmConfiguration.maximumNumberOfActiveVersions
for more information.Declaration
Objective-C
- (nonnull instancetype)freeze;
Swift
func freeze() -> Self
-
Returns a live version of this frozen collection.
This method resolves a reference to a live copy of the same frozen collection. If called on a live collection, will return itself.
Declaration
Objective-C
- (nonnull instancetype)thaw;
Swift
func thaw() -> Self
-
Unavailable
RLMArrays cannot be created directly
-[RLMArray init]
is not available becauseRLMArray
s cannot be created directly.RLMArray
properties onRLMObject
s are lazily created when accessed.Declaration
Objective-C
- (nonnull instancetype)init;
-
Unavailable
RLMArrays cannot be created directly
+[RLMArray new]
is not available becauseRLMArray
s cannot be created directly.RLMArray
properties onRLMObject
s are lazily created when accessed.Declaration
Objective-C
+ (nonnull instancetype)new;