Inherits from NSObject
Conforms to NSFastEnumeration
Declared in RLMArray.h
RLMArray.mm

Overview

RLMArray is the primary container type in Realm. 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.

RLMArrays can be queried with the same predicates as RLMObject and RLMRealm, so you can easily chain queries to further filter query results.

RLMArrays fulfill 2 primary purposes:

  • Hold the results of a query. Using one of the query methods on RLMRealm or RLMObject will return a typed RLMArray of results.
  • Allow the declaration of one-to-many relationships. See RLMObject class documentation for details.

RLMArrays cannot be created directly. RLMArray properties on RLMObjects are lazily created when accessed, or can be obtained by querying a Realm.

Tasks

RLMArray Properties

Accessing Objects from an Array

Adding, Removing, and Replacing Objects in an Array

Querying an Array

Aggregating Property Values

Serializing an Array to JSON

Unavailable Methods

Properties

count

Number of objects in the array.

@property (nonatomic, readonly, assign) NSUInteger count

Declared In

RLMArray.h

objectClassName

The class name (i.e. type) of the RLMObjects contained in this RLMArray.

@property (nonatomic, readonly, copy) NSString *objectClassName

Declared In

RLMArray.h

readOnly

Indicates if the RLMArray is readOnly. YES for RLMArray instances returned from predicate queries and object enumeration.

@property (nonatomic, readonly, getter=isReadOnly) BOOL readOnly

Declared In

RLMArray.h

realm

The Realm in which this array is persisted. Returns nil for standalone arrays.

@property (nonatomic, readonly) RLMRealm *realm

Declared In

RLMArray.h

Class 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)new

Declared In

RLMArray.h

Instance Methods

JSONString

Returns the RLMArray and the RLMObjects it contains as a JSON string.

- (NSString *)JSONString

Return Value

JSON string representation of this RLMArray.

Declared In

RLMArray.h

addObject:

Adds an object to the end of the array.

- (void)addObject:(RLMObject *)object

Parameters

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.h

addObjectsFromArray:

Adds an array of objects at the end of the array.

- (void)addObjectsFromArray:(id)objects

Parameters

objects

An NSArray or RLMArray of objects of the class contained by this RLMArray.

Discussion

Warning: This method can only be called during a write transaction.

Declared In

RLMArray.h

arraySortedByProperty:ascending:

Get a sorted RLMArray from an existing RLMArray

- (RLMArray *)arraySortedByProperty:(NSString *)property ascending:(BOOL)ascending

Parameters

property

The property name to sort by.

ascending

The direction to sort by.

Return Value

An RLMArray sorted by the specified property.

Declared In

RLMArray.h

averageOfProperty:

Returns the average of a given property for objects in an RLMArray.

- (NSNumber *)averageOfProperty:(NSString *)property

Parameters

property

The property to calculate average on. Only properties of type int, float and double are supported.

Return Value

The average for the given property amongst objects in an RLMArray. This will be of type double for both float and double properties.

Discussion

NSNumber *average = [table averageOfProperty:@“age”];

Warning: You cannot use this method on RLMObject, RLMArray, and NSData properties.

Declared In

RLMArray.h

firstObject

Returns the first object in the array.

- (id)firstObject

Return Value

An RLMObject of the class contained by this RLMArray.

Discussion

Returns nil if called on an empty RLMArray.

Declared In

RLMArray.h

indexOfObject:

Gets the index of an object.

- (NSUInteger)indexOfObject:(RLMObject *)object

Parameters

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.h

indexOfObjectWhere:

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.h

indexOfObjectWithPredicate:

Gets the index of the first object matching the predicate.

- (NSUInteger)indexOfObjectWithPredicate:(NSPredicate *)predicate

Parameters

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.h

init

[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)init

Declared In

RLMArray.h

insertObject:atIndex:

Inserts an object at the given index.

- (void)insertObject:(RLMObject *)anObject atIndex:(NSUInteger)index

Parameters

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.h

lastObject

Returns the last object in the array.

- (id)lastObject

Return Value

An RLMObject of the class contained by this RLMArray.

Discussion

Returns nil if called on an empty RLMArray.

Declared In

RLMArray.h

maxOfProperty:

Returns the maximum (highest) value of the given property of objects in an RLMArray

- (id)maxOfProperty:(NSString *)property

Parameters

property

The property to look for a maximum on. Only properties of type int, float, double and NSDate are supported.

Return Value

The maximum value for the property amongst objects in an RLMArray

Discussion

NSNumber *max = [array maxOfProperty:@“age”];

Warning: You cannot use this method on RLMObject, RLMArray, and NSData properties.

Declared In

RLMArray.h

minOfProperty:

Returns the minimum (lowest) value of the given property

- (id)minOfProperty:(NSString *)property

Parameters

property

The property to look for a minimum on. Only properties of type int, float, double and NSDate are supported.

Return Value

The minimum value for the property amongst objects in an RLMArray.

Discussion

NSNumber *min = [array minOfProperty:@“age”];

Warning: You cannot use this method on RLMObject, RLMArray, and NSData properties.

Declared In

RLMArray.h

objectAtIndex:

Returns the object at the index specified.

- (id)objectAtIndex:(NSUInteger)index

Parameters

index

The index to look up.

Return Value

An RLMObject of the class contained by this RLMArray.

Declared In

RLMArray.h

objectsWhere:

Get objects matching the given predicate in the RLMArray.

- (RLMArray *)objectsWhere:(NSString *)predicateFormat, ...

Parameters

predicateFormat

The predicate format string which can accept variable arguments.

Return Value

An RLMArray of objects that match the given predicate

Declared In

RLMArray.h

objectsWithPredicate:

Get objects matching the given predicate in the RLMArray.

- (RLMArray *)objectsWithPredicate:(NSPredicate *)predicate

Parameters

predicate

The predicate to filter the objects.

Return Value

An RLMArray of objects that match the given predicate

Declared In

RLMArray.h

removeAllObjects

Removes all objects from an RLMArray.

- (void)removeAllObjects

Discussion

Warning: This method can only be called during a write transaction.

Declared In

RLMArray.h

removeLastObject

Removes the last object in an RLMArray.

- (void)removeLastObject

Discussion

Warning: This method can only be called during a write transaction.

Declared In

RLMArray.h

removeObjectAtIndex:

Removes an object at a given index.

- (void)removeObjectAtIndex:(NSUInteger)index

Parameters

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.h

replaceObjectAtIndex:withObject:

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

- (void)replaceObjectAtIndex:(NSUInteger)index withObject:(RLMObject *)anObject

Parameters

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.h

sumOfProperty:

Returns the sum of the given property for objects in an RLMArray.

- (NSNumber *)sumOfProperty:(NSString *)property

Parameters

property

The property to calculate sum on. Only properties of type int, float and double are supported.

Return Value

The sum of the given property over all objects in an RLMArray.

Discussion

NSNumber *sum = [array sumOfProperty:@“age”];

Warning: You cannot use this method on RLMObject, RLMArray, and NSData properties.

Declared In

RLMArray.h