RLMArray Class Reference
| Declared in | RLMArray.h |
Overview
RLMArray is the container type in Realm used to define to-many relationships.
Unlike an NSArray, RLMArrays 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_ARRAY_TYPE macro). RLMArray properties can also use Objective‑C generics
if available. For example:
RLM_ARRAY_TYPE(ObjectType)
@property RLMArray<ObjectType *><ObjectType> *arrayOfObjectTypes;
RLMArrays can be queried with the same predicates as RLMObject and RLMResults.
RLMArrays cannot be created directly. RLMArray properties on RLMObjects 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 persisted
RLMObject (RLMArrays on standalone RLMObjects will never become invalidated).
Because RLMArrays 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.
Tasks
RLMArray Properties
-
countproperty -
objectClassNameproperty -
realmproperty -
invalidatedproperty
Accessing Objects from an Array
Adding, Removing, and Replacing Objects in an Array
-
– addObject: -
– addObjects: -
– insertObject:atIndex: -
– removeObjectAtIndex: -
– removeLastObject -
– removeAllObjects -
– replaceObjectAtIndex:withObject: -
– moveObjectAtIndex:toIndex: -
– exchangeObjectAtIndex:withObjectAtIndex:
Querying an Array
-
– indexOfObject: -
– indexOfObjectWhere: -
– indexOfObjectWithPredicate: -
– objectsWhere: -
– objectsWithPredicate: -
– sortedResultsUsingProperty:ascending: -
– sortedResultsUsingDescriptors:
Unavailable Methods
Properties
count
Number of objects in the array.
@property (nonatomic, readonly, assign) NSUInteger countDeclared In
RLMArray.hinvalidated
Indicates if an array can no longer be accessed.
@property (nonatomic, readonly, getter=isInvalidated) BOOL invalidatedDeclared In
RLMArray.hClass Methods
new
[RLMArray new] is not available because RLMArrays cannot be created directly. RLMArray properties on RLMObjects are lazily created when accessed, or can be obtained by querying a Realm.
+ (instancetype)newDeclared In
RLMArray.hInstance Methods
addObject:
Adds an object to the end of the array.
- (void)addObject:(RLMObjectArgument)objectParameters
- object
An RLMObject of the class contained by this RLMArray.
Discussion
Warning: This method can only be called during a write transaction.
Declared In
RLMArray.haddObjects:
Adds an array of objects at the end of the array.
- (void)addObjects:(id<NSFastEnumeration>)objectsParameters
- objects
An enumerable object such as NSArray or RLMResults which contains objects of the same class as this RLMArray.
Discussion
Warning: This method can only be called during a write transaction.
Declared In
RLMArray.hexchangeObjectAtIndex:withObjectAtIndex:
Exchanges the objects in the array at given indexes.
- (void)exchangeObjectAtIndex:(NSUInteger)index1 withObjectAtIndex:(NSUInteger)index2Parameters
- index1
The index of the object with which to replace the object at index
index2.
- index2
The index of the object with which to replace the object at index
index1.
Discussion
Throws an exception when either index exceeds the bounds of this RLMArray.
Warning: This method can only be called during a write transaction.
Declared In
RLMArray.hfirstObject
Returns the first object in the array.
- (nullable RLMObjectType)firstObjectReturn Value
An RLMObject of the class contained by this RLMArray.
Discussion
Returns nil if called on an empty RLMArray.
Declared In
RLMArray.hindexOfObject:
Gets the index of an object.
- (NSUInteger)indexOfObject:(RLMObjectArgument)objectParameters
- object
An object (of the same type as returned from the objectClassName selector).
Discussion
Returns NSNotFound if the object is not found in this RLMArray.
Declared In
RLMArray.hindexOfObjectWhere:
Gets the index of the first object matching the predicate.
- (NSUInteger)indexOfObjectWhere:(NSString *)predicateFormat, ...Parameters
- predicateFormat
The predicate format string which can accept variable arguments.
Return Value
Index of object or NSNotFound if the object is not found in this RLMArray.
Declared In
RLMArray.hindexOfObjectWithPredicate:
Gets the index of the first object matching the predicate.
- (NSUInteger)indexOfObjectWithPredicate:(NSPredicate *)predicateParameters
- predicate
The predicate to filter the objects.
Return Value
Index of object or NSNotFound if the object is not found in this RLMArray.
Declared In
RLMArray.hinit
[RLMArray init] is not available because RLMArrays cannot be created directly. RLMArray properties on RLMObjects are lazily created when accessed, or can be obtained by querying a Realm.
- (instancetype)initDeclared In
RLMArray.hinsertObject:atIndex:
Inserts an object at the given index.
- (void)insertObject:(RLMObjectArgument)anObject atIndex:(NSUInteger)indexParameters
- anObject
An object (of the same type as returned from the objectClassName selector).
- index
The array index at which the object is inserted.
Discussion
Throws an exception when called with an index greater than the number of objects in this RLMArray.
Warning: This method can only be called during a write transaction.
Declared In
RLMArray.hlastObject
Returns the last object in the array.
- (nullable RLMObjectType)lastObjectReturn Value
An RLMObject of the class contained by this RLMArray.
Discussion
Returns nil if called on an empty RLMArray.
Declared In
RLMArray.hmoveObjectAtIndex:toIndex:
Moves the object at the given source index to the given destination index.
- (void)moveObjectAtIndex:(NSUInteger)sourceIndex toIndex:(NSUInteger)destinationIndexParameters
- sourceIndex
The index of the object to be moved.
- destinationIndex
The index to which the object at
sourceIndexshould be moved.
Discussion
Throws an exception when called with an index greater than or equal to the number of objects in this RLMArray.
Warning: This method can only be called during a write transaction.
Declared In
RLMArray.hobjectAtIndex:
Returns the object at the index specified.
- (RLMObjectType)objectAtIndex:(NSUInteger)indexParameters
- index
The index to look up.
Return Value
An RLMObject of the class contained by this RLMArray.
Declared In
RLMArray.hobjectsWhere:
Get objects matching the given predicate in the RLMArray.
- (RLMResults RLM_GENERIC_RETURN *)objectsWhere:(NSString *)predicateFormat, ...Parameters
- predicateFormat
The predicate format string which can accept variable arguments.
Return Value
An RLMResults of objects that match the given predicate
Declared In
RLMArray.hobjectsWithPredicate:
Get objects matching the given predicate in the RLMArray.
- (RLMResults RLM_GENERIC_RETURN *)objectsWithPredicate:(NSPredicate *)predicateParameters
- predicate
The predicate to filter the objects.
Return Value
An RLMResults of objects that match the given predicate
Declared In
RLMArray.hremoveAllObjects
Removes all objects from an RLMArray.
- (void)removeAllObjectsDiscussion
Warning: This method can only be called during a write transaction.
Declared In
RLMArray.hremoveLastObject
Removes the last object in an RLMArray.
- (void)removeLastObjectDiscussion
Warning: This method can only be called during a write transaction.
Declared In
RLMArray.hremoveObjectAtIndex:
Removes an object at a given index.
- (void)removeObjectAtIndex:(NSUInteger)indexParameters
- index
The array index identifying the object to be removed.
Discussion
Throws an exception when called with an index greater than the number of objects in this RLMArray.
Warning: This method can only be called during a write transaction.
Declared In
RLMArray.hreplaceObjectAtIndex:withObject:
Replaces an object at the given index with a new object.
- (void)replaceObjectAtIndex:(NSUInteger)index withObject:(RLMObjectArgument)anObjectParameters
- index
The array index of the object to be replaced.
- anObject
An object (of the same type as returned from the objectClassName selector).
Discussion
Throws an exception when called with an index greater than the number of objects in this RLMArray.
Warning: This method can only be called during a write transaction.
Declared In
RLMArray.hsortedResultsUsingDescriptors:
Get a sorted RLMResults from an RLMArray
- (RLMResults RLM_GENERIC_RETURN *)sortedResultsUsingDescriptors:(NSArray *)propertiesParameters
- properties
An array of
RLMSortDescriptors to sort by.
Return Value
An RLMResults sorted by the specified properties.
Declared In
RLMArray.hsortedResultsUsingProperty:ascending:
Get a sorted RLMResults from an RLMArray
- (RLMResults RLM_GENERIC_RETURN *)sortedResultsUsingProperty:(NSString *)property ascending:(BOOL)ascendingParameters
- property
The property name to sort by.
- ascending
The direction to sort by.
Return Value
An RLMResults sorted by the specified property.
Declared In
RLMArray.h