////////////////////////////////////////////////////////////////////////////
//
// Copyright 2014 Realm Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
////////////////////////////////////////////////////////////////////////////
#import <Foundation/Foundation.h>
#import <Realm/RLMConstants.h>
#import <Realm/RLMThreadSafeReference.h>
NS_ASSUME_NONNULL_BEGIN
@class RLMRealm, RLMResults, RLMSortDescriptor, RLMNotificationToken, RLMCollectionChange;
typedef RLM_CLOSED_ENUM(int32_t, RLMPropertyType);
/**
A homogenous collection of Realm-managed objects. Examples of conforming types
include `RLMArray`, `RLMSet`, `RLMResults`, and `RLMLinkingObjects`.
*/
@protocol RLMCollection <NSFastEnumeration, RLMThreadConfined>
@optional
/**
Returns the first object in the collection.
Returns `nil` if called on an empty collection.
@return An object of the type contained in the collection.
*/
- (nullable id)firstObject;
/**
Returns the last object in the collection.
Returns `nil` if called on an empty collection.
@return An object of the type contained in the collection.
*/
- (nullable id)lastObject;
/// :nodoc:
- (id)objectAtIndexedSubscript:(NSUInteger)index;
/**
Returns an array containing the objects in the collection at the indexes specified by a given index set.
`nil` will be returned if the index set contains an index out of the collections bounds.
@param indexes The indexes in the collection to retrieve objects from.
@return The objects at the specified indexes.
*/
- (nullable NSArray *)objectsAtIndexes:(NSIndexSet *)indexes;
/**
Returns the index of an object in the collection.
Returns `NSNotFound` if the object is not found in the collection.
@param object An object (of the same type as returned from the `objectClassName` selector).
*/
- (NSUInteger)indexOfObject:(id)object;
/**
Returns the index of the first object in the collection matching the predicate.
@param predicateFormat A predicate format string, optionally followed by a variable number of arguments.
@return The index of the object, or `NSNotFound` if the object is not found in the collection.
*/
- (NSUInteger)indexOfObjectWhere:(NSString *)predicateFormat, ...;
/// :nodoc:
- (NSUInteger)indexOfObjectWhere:(NSString *)predicateFormat args:(va_list)args;
/**
Returns the index of the first object in the collection matching the predicate.
@param predicate The predicate with which to filter the objects.
@return The index of the object, or `NSNotFound` if the object is not found in the collection.
*/
- (NSUInteger)indexOfObjectWithPredicate:(NSPredicate *)predicate;
@required
#pragma mark - Properties
/**
The number of objects in the collection.
*/
@property (nonatomic, readonly, assign) NSUInteger count;
/**
The type of the objects in the collection.
*/
@property (nonatomic, readonly, assign) RLMPropertyType type;
/**
Indicates whether the objects in the collection can be `nil`.
*/
@property (nonatomic, readonly, getter = isOptional) BOOL optional;
/**
The class name of the objects contained in the collection.
Will be `nil` if `type` is not RLMPropertyTypeObject.
*/
@property (nonatomic, readonly, copy, nullable) NSString *objectClassName;
/**
The Realm which manages the collection, or `nil` for unmanaged collections.
*/
@property (nonatomic, readonly) RLMRealm *realm;
#pragma mark - Accessing Objects from a Collection
/**
Returns the object at the index specified.
@param index The index to look up.
@return An object of the type contained in the collection.
*/
- (id)objectAtIndex:(NSUInteger)index;
#pragma mark - Querying a Collection
/**
Returns all objects matching the given predicate in the collection.
@param predicateFormat A predicate format string, optionally followed by a variable number of arguments.
@return An `RLMResults` containing objects that match the given predicate.
*/
- (RLMResults *)objectsWhere:(NSString *)predicateFormat, ...;
/// :nodoc:
- (RLMResults *)objectsWhere:(NSString *)predicateFormat args:(va_list)args;
/**
Returns all objects matching the given predicate in the collection.
@param predicate The predicate with which to filter the objects.
@return An `RLMResults` containing objects that match the given predicate.
*/
- (RLMResults *)objectsWithPredicate:(NSPredicate *)predicate;
/**
Returns a sorted `RLMResults` from the collection.
@param keyPath The keyPath to sort by.
@param ascending The direction to sort in.
@return An `RLMResults` sorted by the specified key path.
*/
- (RLMResults *)sortedResultsUsingKeyPath:(NSString *)keyPath ascending:(BOOL)ascending;
/**
Returns a sorted `RLMResults` from the collection.
@param properties An array of `RLMSortDescriptor`s to sort by.
@return An `RLMResults` sorted by the specified properties.
*/
- (RLMResults *)sortedResultsUsingDescriptors:(NSArray<RLMSortDescriptor *> *)properties;
/**
Returns an `NSArray` containing the results of invoking `valueForKey:` using `key` on each of the collection's objects.
@param key The name of the property.
@return An `NSArray` containing results.
*/
- (nullable id)valueForKey:(NSString *)key;
/**
Invokes `setValue:forKey:` on each of the collection's objects using the specified `value` and `key`.
@warning This method may only be called during a write transaction.
@param value The object value.
@param key The name of the property.
*/
- (void)setValue:(nullable id)value forKey:(NSString *)key;
#pragma mark - Notifications
/**
Registers a block to be called each time the collection changes.
The block will be asynchronously called with the initial 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 will be `nil` the first time the block is called.
For each call after that, it will contain information about
which rows in the collection were added, removed or modified. If a write transaction
did not modify any objects in this collection, the block is not called at all.
See the `RLMCollectionChange` documentation for information on how the changes
are reported and an example of updating a `UITableView`.
If an error occurs the block will be called with `nil` for the collection
parameter and a non-`nil` error. Currently the only errors that can occur are
when opening the Realm on the background worker thread.
At the time when the block is called, the collection object 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 `-[RLMRealm 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 collection. 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.
id<RLMCollection> collection = [Dog allObjects];
NSLog(@"dogs.count: %zu", dogs.count); // => 0
self.token = [collection addNotificationBlock:^(id<RLMCollection> 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";
[realm 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.
@param block The block to be called each time the collection changes.
@return A token which must be held for as long as you want collection notifications to be delivered.
*/
- (RLMNotificationToken *)addNotificationBlock:(void (^)(id<RLMCollection> __nullable collection,
RLMCollectionChange *__nullable change,
NSError *__nullable error))block __attribute__((warn_unused_result));
#pragma mark - Aggregating Property Values
/**
Returns the minimum (lowest) value of the given property among all the objects
in the collection.
NSNumber *min = [results minOfProperty:@"age"];
@warning You cannot use this method on `RLMObject`, `RLMArray`, and `NSData` properties.
@param property The property whose minimum value is desired. Only properties of
types `int`, `float`, `double`, and `NSDate` are supported.
@return The minimum value of the property, or `nil` if the Results are empty.
*/
- (nullable id)minOfProperty:(NSString *)property;
/**
Returns the maximum (highest) value of the given property among all the objects
in the collection.
NSNumber *max = [results maxOfProperty:@"age"];
@warning You cannot use this method on `RLMObject`, `RLMArray`, and `NSData` properties.
@param property The property whose maximum value is desired. Only properties of
types `int`, `float`, `double`, and `NSDate` are supported.
@return The maximum value of the property, or `nil` if the Results are empty.
*/
- (nullable id)maxOfProperty:(NSString *)property;
/**
Returns the sum of the values of a given property over all the objects in the collection.
NSNumber *sum = [results sumOfProperty:@"age"];
@warning You cannot use this method on `RLMObject`, `RLMArray`, and `NSData` properties.
@param property The property whose values should be summed. Only properties of
types `int`, `float`, and `double` are supported.
@return The sum of the given property.
*/
- (NSNumber *)sumOfProperty:(NSString *)property;
/**
Returns the average value of a given property over the objects in the collection.
NSNumber *average = [results averageOfProperty:@"age"];
@warning You cannot use this method on `RLMObject`, `RLMArray`, and `NSData` properties.
@param property The property whose average value should be calculated. Only
properties of types `int`, `float`, and `double` are supported.
@return The average value of the given property, or `nil` if the Results are empty.
*/
- (nullable NSNumber *)averageOfProperty:(NSString *)property;
#pragma mark - Freeze
/**
Indicates if the collection is frozen.
Frozen collections are immutable and can be accessed from any thread. The
objects read from a frozen collection will also be frozen.
*/
@property (nonatomic, readonly, getter=isFrozen) BOOL frozen;
/**
Returns a frozen (immutable) snapshot of this collection.
The frozen copy is an immutable collection which contains the same data as
this collection currently contains, but will not update when writes are made
to the containing Realm. Unlike live collections, frozen collections 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 Holding onto a frozen collection for an extended period while
performing write transaction on the Realm may result in the Realm
file growing to large sizes. See
`RLMRealmConfiguration.maximumNumberOfActiveVersions`
for more information.
*/
- (instancetype)freeze;
@end
/**
An `RLMSortDescriptor` stores a property name and a sort order for use with
`sortedResultsUsingDescriptors:`. It is similar to `NSSortDescriptor`, but supports
only the subset of functionality which can be efficiently run by Realm's query
engine.
`RLMSortDescriptor` instances are immutable.
*/
@interface RLMSortDescriptor : NSObject
#pragma mark - Properties
/**
The key path which the sort descriptor orders results by.
*/
@property (nonatomic, readonly) NSString *keyPath;
/**
Whether the descriptor sorts in ascending or descending order.
*/
@property (nonatomic, readonly) BOOL ascending;
#pragma mark - Methods
/**
Returns a new sort descriptor for the given key path and sort direction.
*/
+ (instancetype)sortDescriptorWithKeyPath:(NSString *)keyPath ascending:(BOOL)ascending;
/**
Returns a copy of the receiver with the sort direction reversed.
*/
- (instancetype)reversedSortDescriptor;
@end
/**
A `RLMCollectionChange` object encapsulates information about changes to collections
that are reported by Realm notifications.
`RLMCollectionChange` is passed to the notification blocks registered with
`-addNotificationBlock` on `RLMArray` and `RLMResults`, and reports what rows in the
collection changed since the last time the notification block was called.
The change information is available in two formats: a simple array of row
indices in the collection for each type of change, and an array of index paths
in a requested section suitable for passing directly to `UITableView`'s batch
update methods. A complete example of updating a `UITableView` named `tv`:
[tv beginUpdates];
[tv deleteRowsAtIndexPaths:[changes deletionsInSection:0] withRowAnimation:UITableViewRowAnimationAutomatic];
[tv insertRowsAtIndexPaths:[changes insertionsInSection:0] withRowAnimation:UITableViewRowAnimationAutomatic];
[tv reloadRowsAtIndexPaths:[changes modificationsInSection:0] withRowAnimation:UITableViewRowAnimationAutomatic];
[tv endUpdates];
All of the arrays in an `RLMCollectionChange` are always sorted in ascending order.
*/
@interface RLMCollectionChange : NSObject
/// The indices of objects in the previous version of the collection which have
/// been removed from this one.
@property (nonatomic, readonly) NSArray<NSNumber *> *deletions;
/// The indices in the new version of the collection which were newly inserted.
@property (nonatomic, readonly) NSArray<NSNumber *> *insertions;
/**
The indices in the new version of the collection which were modified.
For `RLMResults`, this means that one or more of the properties of the object at
that index were modified (or an object linked to by that object was
modified).
For `RLMArray`, the array itself being modified to contain a
different object at that index will also be reported as a modification.
*/
@property (nonatomic, readonly) NSArray<NSNumber *> *modifications;
/// Returns the index paths of the deletion indices in the given section.
- (NSArray<NSIndexPath *> *)deletionsInSection:(NSUInteger)section;
/// Returns the index paths of the insertion indices in the given section.
- (NSArray<NSIndexPath *> *)insertionsInSection:(NSUInteger)section;
/// Returns the index paths of the modification indices in the given section.
- (NSArray<NSIndexPath *> *)modificationsInSection:(NSUInteger)section;
@end
NS_ASSUME_NONNULL_END
