RLMSet

Objective-C

@interface RLMSet<RLMObjectType> : NSObject <RLMCollection>

Swift

@_nonSendable(_assumed) class RLMSet<RLMObjectType> : NSObject, RLMCollection where RLMObjectType : AnyObject

A collection datatype used for storing distinct objects.

Note

RLMSet supports storing primitive and RLMObject types. RLMSet does not support storing Embedded Realm Objects.

Properties

  • The number of objects in the set.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSUInteger count;

    Swift

    var count: UInt { get }
  • The type of the objects in the set.

    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 objects in the RLMSet as an NSArray value.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSArray<RLMObjectType> *_Nonnull allObjects;

    Swift

    var allObjects: [RLMObjectType] { get }
  • The class name of the objects contained in the set.

    Will be nil if type is not RLMPropertyTypeObject.

    Declaration

    Objective-C

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

    Swift

    var objectClassName: String? { get }
  • The Realm which manages the set. Returns nil for unmanaged set.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) RLMRealm *realm;

    Swift

    var realm: RLMRealm? { get }
  • Indicates if the set can no longer be accessed.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isInvalidated) BOOL invalidated;

    Swift

    var isInvalidated: Bool { get }
  • Indicates if the set is frozen.

    Frozen sets are immutable and can be accessed from any thread. Frozen sets are created by calling -freeze on a managed live set. Unmanaged sets are never frozen.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isFrozen) BOOL frozen;

    Swift

    var isFrozen: Bool { get }

Adding, Removing, and Replacing Objects in a Set

  • Adds an object to the set if it is not already present.

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

  • Adds an array of distinct objects to the set.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Objective-C

    - (void)addObjects:(nonnull id<NSFastEnumeration>)objects;

    Swift

    func addObjects(_ objects: NSFastEnumeration)

    Parameters

    objects

    An enumerable object such as NSArray, NSSet or RLMResults which contains objects of the same class as the set.

  • Removes a given object from the set.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Objective-C

    - (void)removeObject:(nonnull RLMObjectType)object;

    Swift

    func remove(_ object: RLMObjectType)

    Parameters

    object

    The object in the set that you want to remove.

  • Removes all objects from the set.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Objective-C

    - (void)removeAllObjects;

    Swift

    func removeAllObjects()
  • Empties the receiving set, then adds each object contained in another given set.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Objective-C

    - (void)setSet:(nonnull RLMSet<RLMObjectType> *)set;

    Swift

    func setSet(_ set: RLMSet<RLMObjectType>)

    Parameters

    set

    The RLMSet whose members replace the receiving set’s content.

  • Removes from the receiving set each object that isn’t a member of another given set.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Objective-C

    - (void)intersectSet:(nonnull RLMSet<RLMObjectType> *)set;

    Swift

    func intersect(_ set: RLMSet<RLMObjectType>)

    Parameters

    set

    The RLMSet with which to perform the intersection.

  • Removes each object in another given set from the receiving set, if present.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Objective-C

    - (void)minusSet:(nonnull RLMSet<RLMObjectType> *)set;

    Swift

    func minus(_ set: RLMSet<RLMObjectType>)

    Parameters

    set

    The set of objects to remove from the receiving set.

  • Adds each object in another given set to the receiving set, if not present.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Objective-C

    - (void)unionSet:(nonnull RLMSet<RLMObjectType> *)set;

    Swift

    func union(_ set: RLMSet<RLMObjectType>)

    Parameters

    set

    The set of objects to add to the receiving set.

Querying a Set

  • Returns a Boolean value that indicates whether at least one object in the receiving set is also present in another given set.

    Declaration

    Objective-C

    - (BOOL)intersectsSet:(nonnull RLMSet<RLMObjectType> *)set;

    Swift

    func intersects(_ set: RLMSet<RLMObjectType>) -> Bool

    Parameters

    set

    The RLMSet to compare the receiving set to.

    Return Value

    YES if at least one object in the receiving set is also present in otherSet, otherwise NO.

  • Returns a Boolean value that indicates whether every object in the receiving set is also present in another given set.

    Declaration

    Objective-C

    - (BOOL)isSubsetOfSet:(nonnull RLMSet<RLMObjectType> *)set;

    Swift

    func isSubset(of set: RLMSet<RLMObjectType>) -> Bool

    Parameters

    set

    The RLMSet to compare the receiving set to.

    Return Value

    YES if every object in the receiving set is also present in otherSet, otherwise NO.

  • Returns a Boolean value that indicates whether a given object is present in the set.

    Declaration

    Objective-C

    - (BOOL)containsObject:(nonnull RLMObjectType)anObject;

    Swift

    func contains(_ anObject: RLMObjectType) -> Bool

    Parameters

    anObject

    An object to look for in the set.

    Return Value

    YES if anObject is present in the set, otherwise NO.

  • Compares the receiving set to another set.

    Declaration

    Objective-C

    - (BOOL)isEqualToSet:(nonnull RLMSet<RLMObjectType> *)otherSet;

    Swift

    func isEqual(to otherSet: RLMSet<RLMObjectType>) -> Bool

    Parameters

    otherSet

    The set with which to compare the receiving set.

    Return Value

    YES if the contents of otherSet are equal to the contents of the receiving set, otherwise NO.

Sectioning a Set

Notifications

  • Registers a block to be called each time the set changes.

    The block will be asynchronously called with the initial set, and then called again after each write transaction which changes any of the objects in the set, which objects are in the results, or the order of the objects in the set.

    The changes 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 set were added, removed or modified. If a write transaction did not modify any objects in the set, 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.

    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(RLMSet<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 set.

    Declaration

    Objective-C

    - (nonnull RLMNotificationToken *)addNotificationBlock:
        (nonnull void (^)(RLMSet<RLMObjectType> *_Nullable,
                          RLMCollectionChange *_Nullable, NSError *_Nullable))block;

    Swift

    func addNotificationBlock(_ block: @escaping (RLMSet<RLMObjectType>?, RLMCollectionChange?, Error?) -> Void) -> RLMNotificationToken

    Parameters

    block

    The block to be called each time the set 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 set changes.

    The block will be asynchronously called with the initial set, and then called again after each write transaction which changes any of the objects in the set, which objects are in the results, or the order of the objects in the set.

    The changes 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 set were added, removed or modified. If a write transaction did not modify any objects in the set, 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.

    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 (^)(RLMSet<RLMObjectType> *_Nullable,
                                               RLMCollectionChange *_Nullable,
                                               NSError *_Nullable))block
                       queue:(nullable dispatch_queue_t)queue;

    Swift

    func addNotificationBlock(_ block: @escaping (RLMSet<RLMObjectType>?, RLMCollectionChange?, 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 set changes.

    The block will be asynchronously called with the initial set, and then called again after each write transaction which changes any of the objects in the set, which objects are in the results, or the order of the objects in the set.

    The changes 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 set were added, removed or modified. If a write transaction did not modify any objects in the set, 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.

    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 (^)(RLMSet<RLMObjectType> *_Nullable,
                                               RLMCollectionChange *_Nullable,
                                               NSError *_Nullable))block
                    keyPaths:(nullable NSArray<NSString *> *)keyPaths
                       queue:(nullable dispatch_queue_t)queue;

    Swift

    func addNotificationBlock(_ block: @escaping (RLMSet<RLMObjectType>?, RLMCollectionChange?, 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 set changes.

    The block will be asynchronously called with the initial set, and then called again after each write transaction which changes any of the objects in the set, which objects are in the results, or the order of the objects in the set.

    The changes 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 set were added, removed or modified. If a write transaction did not modify any objects in the set, 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.

    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 (^)(RLMSet<RLMObjectType> *_Nullable,
                                               RLMCollectionChange *_Nullable,
                                               NSError *_Nullable))block
                    keyPaths:(nullable NSArray<NSString *> *)keyPaths;

    Swift

    func addNotificationBlock(_ block: @escaping (RLMSet<RLMObjectType>?, RLMCollectionChange?, 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.

Aggregating Property Values

  • Returns the minimum (lowest) value of the given property among all the objects in the set.

    NSNumber *min = [object.setProperty minOfProperty:@"age"];
    

    Warning

    You cannot use this method on RLMObject, RLMArray, RLMSet, and NSData 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, and NSDate are supported.

    Return Value

    The minimum value of the property, or nil if the set is empty.

  • Returns the maximum (highest) value of the given property among all the objects in the set.

    NSNumber *max = [object.setProperty maxOfProperty:@"age"];
    

    Warning

    You cannot use this method on RLMObject, RLMArray, RLMSet, and NSData 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, and NSDate are supported.

    Return Value

    The maximum value of the property, or nil if the set is empty.

  • Returns the sum of distinct values of a given property over all the objects in the set.

    NSNumber *sum = [object.setProperty sumOfProperty:@"age"];
    

    Warning

    You cannot use this method on RLMObject, RLMArray, RLMSet 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, and double are supported.

    Return Value

    The sum of the given property.

  • Returns the average value of a given property over the objects in the set.

    NSNumber *average = [object.setProperty averageOfProperty:@"age"];
    

    Warning

    You cannot use this method on RLMObject, RLMSet, RLMArray, and NSData 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, and double are supported.

    Return Value

    The average value of the given property, or nil if the set is empty.

Freeze

  • Returns a frozen (immutable) snapshot of this set.

    The frozen copy is an immutable set which contains the same data as this et currently contains, but will not update when writes are made to the containing Realm. Unlike live sets, frozen sets 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 set.

    Warning

    Holding onto a frozen set 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.

    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 Methods

  • Unavailable

    RLMSets cannot be created directly

    -[RLMSet init] is not available because RLMSets cannot be created directly. `RLMSet properties on RLMObjects are lazily created when accessed.

    Declaration

    Objective-C

    - (nonnull instancetype)init;
  • Unavailable

    RLMSet cannot be created directly

    +[RLMSet new] is not available because RLMSets cannot be created directly. RLMSet properties on RLMObjects are lazily created when accessed.

    Declaration

    Objective-C

    + (nonnull instancetype)new;