RLMSet

Objective-C

@interface RLMSet<RLMObjectType> : NSObject <RLMCollection>

Swift

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.

Show on GitHub

Properties


                    
                    
                    count

The number of objects in the set.

Declaration

Objective-C

@property (nonatomic, readonly) NSUInteger count;

Swift

var count: UInt { get }

Show on GitHub


                    
                    
                    type

The type of the objects in the set.

Declaration

Objective-C

@property (nonatomic, readonly) RLMPropertyType type;

Swift

var type: RLMPropertyType { get }

Show on GitHub

optional
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 }
Show on GitHub


                    
                    
                    allObjects

The objects in the RLMSet as an NSArray value.

Declaration

Objective-C

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

Swift

var allObjects: [RLMObjectType] { get }

Show on GitHub

objectClassName
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 }
Show on GitHub
realm
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 }
Show on GitHub


                    
                    
                    invalidated

Indicates if the set can no longer be accessed.

Declaration

Objective-C

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

Swift

var isInvalidated: Bool { get }

Show on GitHub

frozen
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 }
Show on GitHub

Adding, Removing, and Replacing Objects in a Set


                    
                    
                    -addObject:

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.

Show on GitHub


                    
                    
                    -addObjects:

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.

Show on GitHub


                    
                    
                    -removeObject:

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.

Show on GitHub

-removeAllObjects
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()
Show on GitHub


                    
                    
                    -setSet:

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.

Show on GitHub


                    
                    
                    -intersectSet:

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.

Show on GitHub


                    
                    
                    -minusSet:

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.

Show on GitHub


                    
                    
                    -unionSet:

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.

Show on GitHub

Querying a Set


                    
                    
                    -intersectsSet:

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.

Show on GitHub


                    
                    
                    -isSubsetOfSet:

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.

Show on GitHub


                    
                    
                    -containsObject:

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.

Show on GitHub


                    
                    
                    -isEqualToSet:

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.

Show on GitHub

Notifications


                    
                    
                    -addNotificationBlock:

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.

If an error occurs the block will be called with nil for the results parameter and a non-nil error. Currently the only errors that can occur are when opening the Realm on the background worker thread.

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.

Show on GitHub


                    
                    
                    -addNotificationBlock:queue:

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

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: DispatchQueue?) -> 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.

Show on GitHub


                    
                    
                    -addNotificationBlock:keyPaths:queue:

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

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: DispatchQueue?) -> RLMNotificationToken

Parameters

`block`	The block to be called whenever a change occurs.
`keyPaths`	The block will be called for changes occuring 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.

Show on GitHub


                    
                    
                    -addNotificationBlock:keyPaths:

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

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

Show on GitHub

Aggregating Property Values


                    
                    
                    -minOfProperty:

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.

Show on GitHub


                    
                    
                    -maxOfProperty:

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.

Show on GitHub


                    
                    
                    -sumOfProperty:

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.

Show on GitHub


                    
                    
                    -averageOfProperty:

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.

Show on GitHub

Freeze

-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
Show on GitHub
-thaw
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
Show on GitHub

Unavailable Methods

-init
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;
Show on GitHub
+new
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;
Show on GitHub