iOS/Pods/Realm/include/RLMCollection.h

   1 ////////////////////////////////////////////////////////////////////////////
   2 //
   3 // Copyright 2014 Realm Inc.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the "License");
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 // http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17 ////////////////////////////////////////////////////////////////////////////
  18
  19 #import <Foundation/Foundation.h>
  20
  21 #import <Realm/RLMThreadSafeReference.h>
  22
  23 NS_ASSUME_NONNULL_BEGIN
  24
  25 @class RLMRealm, RLMResults, RLMSortDescriptor, RLMNotificationToken, RLMCollectionChange;
  26 typedef NS_ENUM(int32_t, RLMPropertyType);
  27
  28 /**
  29  A homogenous collection of Realm-managed objects. Examples of conforming types
  30  include `RLMArray`, `RLMResults`, and `RLMLinkingObjects`.
  31  */
  32 @protocol RLMCollection <NSFastEnumeration, RLMThreadConfined>
  33
  34 @required
  35
  36 #pragma mark - Properties
  37
  38 /**
  39  The number of objects in the collection.
  40  */
  41 @property (nonatomic, readonly, assign) NSUInteger count;
  42
  43 /**
  44  The type of the objects in the collection.
  45  */
  46 @property (nonatomic, readonly, assign) RLMPropertyType type;
  47
  48 /**
  49  Indicates whether the objects in the collection can be `nil`.
  50  */
  51 @property (nonatomic, readonly, getter = isOptional) BOOL optional;
  52
  53 /**
  54  The class name  of the objects contained in the collection.
  55
  56  Will be `nil` if `type` is not RLMPropertyTypeObject.
  57  */
  58 @property (nonatomic, readonly, copy, nullable) NSString *objectClassName;
  59
  60 /**
  61  The Realm which manages the collection, or `nil` for unmanaged collections.
  62  */
  63 @property (nonatomic, readonly) RLMRealm *realm;
  64
  65 #pragma mark - Accessing Objects from a Collection
  66
  67 /**
  68  Returns the object at the index specified.
  69
  70  @param index   The index to look up.
  71
  72  @return An object of the type contained in the collection.
  73  */
  74 - (id)objectAtIndex:(NSUInteger)index;
  75
  76 /**
  77  Returns the first object in the collection.
  78
  79  Returns `nil` if called on an empty collection.
  80
  81  @return An object of the type contained in the collection.
  82  */
  83 - (nullable id)firstObject;
  84
  85 /**
  86  Returns the last object in the collection.
  87
  88  Returns `nil` if called on an empty collection.
  89
  90  @return An object of the type contained in the collection.
  91  */
  92 - (nullable id)lastObject;
  93
  94 #pragma mark - Querying a Collection
  95
  96 /**
  97  Returns the index of an object in the collection.
  98
  99  Returns `NSNotFound` if the object is not found in the collection.
 100
 101  @param object  An object (of the same type as returned from the `objectClassName` selector).
 102  */
 103 - (NSUInteger)indexOfObject:(id)object;
 104
 105 /**
 106  Returns the index of the first object in the collection matching the predicate.
 107
 108  @param predicateFormat A predicate format string, optionally followed by a variable number of arguments.
 109
 110  @return    The index of the object, or `NSNotFound` if the object is not found in the collection.
 111  */
 112 - (NSUInteger)indexOfObjectWhere:(NSString *)predicateFormat, ...;
 113
 114 /// :nodoc:
 115 - (NSUInteger)indexOfObjectWhere:(NSString *)predicateFormat args:(va_list)args;
 116
 117 /**
 118  Returns the index of the first object in the collection matching the predicate.
 119
 120  @param predicate   The predicate with which to filter the objects.
 121
 122  @return    The index of the object, or `NSNotFound` if the object is not found in the collection.
 123  */
 124 - (NSUInteger)indexOfObjectWithPredicate:(NSPredicate *)predicate;
 125
 126 /**
 127  Returns all objects matching the given predicate in the collection.
 128
 129  @param predicateFormat A predicate format string, optionally followed by a variable number of arguments.
 130
 131  @return    An `RLMResults` containing objects that match the given predicate.
 132  */
 133 - (RLMResults *)objectsWhere:(NSString *)predicateFormat, ...;
 134
 135 /// :nodoc:
 136 - (RLMResults *)objectsWhere:(NSString *)predicateFormat args:(va_list)args;
 137
 138 /**
 139  Returns all objects matching the given predicate in the collection.
 140
 141  @param predicate   The predicate with which to filter the objects.
 142
 143  @return            An `RLMResults` containing objects that match the given predicate.
 144  */
 145 - (RLMResults *)objectsWithPredicate:(NSPredicate *)predicate;
 146
 147 /**
 148  Returns a sorted `RLMResults` from the collection.
 149
 150  @param keyPath     The keyPath to sort by.
 151  @param ascending   The direction to sort in.
 152
 153  @return    An `RLMResults` sorted by the specified key path.
 154  */
 155 - (RLMResults *)sortedResultsUsingKeyPath:(NSString *)keyPath ascending:(BOOL)ascending;
 156
 157 /**
 158  Returns a sorted `RLMResults` from the collection.
 159
 160  @param properties  An array of `RLMSortDescriptor`s to sort by.
 161
 162  @return    An `RLMResults` sorted by the specified properties.
 163  */
 164 - (RLMResults *)sortedResultsUsingDescriptors:(NSArray<RLMSortDescriptor *> *)properties;
 165
 166 /// :nodoc:
 167 - (id)objectAtIndexedSubscript:(NSUInteger)index;
 168
 169 /**
 170  Returns an `NSArray` containing the results of invoking `valueForKey:` using `key` on each of the collection's objects.
 171
 172  @param key The name of the property.
 173
 174  @return An `NSArray` containing results.
 175  */
 176 - (nullable id)valueForKey:(NSString *)key;
 177
 178 /**
 179  Invokes `setValue:forKey:` on each of the collection's objects using the specified `value` and `key`.
 180
 181  @warning This method may only be called during a write transaction.
 182
 183  @param value The object value.
 184  @param key   The name of the property.
 185  */
 186 - (void)setValue:(nullable id)value forKey:(NSString *)key;
 187
 188 #pragma mark - Notifications
 189
 190 /**
 191  Registers a block to be called each time the collection changes.
 192
 193  The block will be asynchronously called with the initial collection, and then
 194  called again after each write transaction which changes either any of the
 195  objects in the collection, or which objects are in the collection.
 196
 197  The `change` parameter will be `nil` the first time the block is called.
 198  For each call after that, it will contain information about
 199  which rows in the collection were added, removed or modified. If a write transaction
 200  did not modify any objects in this collection, the block is not called at all.
 201  See the `RLMCollectionChange` documentation for information on how the changes
 202  are reported and an example of updating a `UITableView`.
 203
 204  If an error occurs the block will be called with `nil` for the collection
 205  parameter and a non-`nil` error. Currently the only errors that can occur are
 206  when opening the Realm on the background worker thread.
 207
 208  At the time when the block is called, the collection object will be fully
 209  evaluated and up-to-date, and as long as you do not perform a write transaction
 210  on the same thread or explicitly call `-[RLMRealm refresh]`, accessing it will
 211  never perform blocking work.
 212
 213  Notifications are delivered via the standard run loop, and so can't be
 214  delivered while the run loop is blocked by other activity. When
 215  notifications can't be delivered instantly, multiple notifications may be
 216  coalesced into a single notification. This can include the notification
 217  with the initial collection. For example, the following code performs a write
 218  transaction immediately after adding the notification block, so there is no
 219  opportunity for the initial notification to be delivered first. As a
 220  result, the initial notification will reflect the state of the Realm after
 221  the write transaction.
 222
 223      id<RLMCollection> collection = [Dog allObjects];
 224      NSLog(@"dogs.count: %zu", dogs.count); // => 0
 225      self.token = [collection addNotificationBlock:^(id<RLMCollection> dogs,
 226                                                   RLMCollectionChange *changes,
 227                                                   NSError *error) {
 228          // Only fired once for the example
 229          NSLog(@"dogs.count: %zu", dogs.count); // => 1
 230      }];
 231      [realm transactionWithBlock:^{
 232          Dog *dog = [[Dog alloc] init];
 233          dog.name = @"Rex";
 234          [realm addObject:dog];
 235      }];
 236      // end of run loop execution context
 237
 238  You must retain the returned token for as long as you want updates to continue
 239  to be sent to the block. To stop receiving updates, call `-invalidate` on the token.
 240
 241  @warning This method cannot be called during a write transaction, or when the
 242           containing Realm is read-only.
 243
 244  @param block The block to be called each time the collection changes.
 245  @return A token which must be held for as long as you want collection notifications to be delivered.
 246  */
 247 - (RLMNotificationToken *)addNotificationBlock:(void (^)(id<RLMCollection> __nullable collection,
 248                                                          RLMCollectionChange *__nullable change,
 249                                                          NSError *__nullable error))block __attribute__((warn_unused_result));
 250
 251 #pragma mark - Aggregating Property Values
 252
 253 /**
 254  Returns the minimum (lowest) value of the given property among all the objects
 255  in the collection.
 256
 257      NSNumber *min = [results minOfProperty:@"age"];
 258
 259  @warning You cannot use this method on `RLMObject`, `RLMArray`, and `NSData` properties.
 260
 261  @param property The property whose minimum value is desired. Only properties of
 262                  types `int`, `float`, `double`, and `NSDate` are supported.
 263
 264  @return The minimum value of the property, or `nil` if the Results are empty.
 265  */
 266 - (nullable id)minOfProperty:(NSString *)property;
 267
 268 /**
 269  Returns the maximum (highest) value of the given property among all the objects
 270  in the collection.
 271
 272      NSNumber *max = [results maxOfProperty:@"age"];
 273
 274  @warning You cannot use this method on `RLMObject`, `RLMArray`, and `NSData` properties.
 275
 276  @param property The property whose maximum value is desired. Only properties of
 277                  types `int`, `float`, `double`, and `NSDate` are supported.
 278
 279  @return The maximum value of the property, or `nil` if the Results are empty.
 280  */
 281 - (nullable id)maxOfProperty:(NSString *)property;
 282
 283 /**
 284  Returns the sum of the values of a given property over all the objects in the collection.
 285
 286      NSNumber *sum = [results sumOfProperty:@"age"];
 287
 288  @warning You cannot use this method on `RLMObject`, `RLMArray`, and `NSData` properties.
 289
 290  @param property The property whose values should be summed. Only properties of
 291                  types `int`, `float`, and `double` are supported.
 292
 293  @return The sum of the given property.
 294  */
 295 - (NSNumber *)sumOfProperty:(NSString *)property;
 296
 297 /**
 298  Returns the average value of a given property over the objects in the collection.
 299
 300      NSNumber *average = [results averageOfProperty:@"age"];
 301
 302  @warning You cannot use this method on `RLMObject`, `RLMArray`, and `NSData` properties.
 303
 304  @param property The property whose average value should be calculated. Only
 305                  properties of types `int`, `float`, and `double` are supported.
 306
 307  @return    The average value of the given property, or `nil` if the Results are empty.
 308  */
 309 - (nullable NSNumber *)averageOfProperty:(NSString *)property;
 310
 311 @end
 312
 313 /**
 314  An `RLMSortDescriptor` stores a property name and a sort order for use with
 315  `sortedResultsUsingDescriptors:`. It is similar to `NSSortDescriptor`, but supports
 316  only the subset of functionality which can be efficiently run by Realm's query
 317  engine.
 318
 319  `RLMSortDescriptor` instances are immutable.
 320  */
 321 @interface RLMSortDescriptor : NSObject
 322
 323 #pragma mark - Properties
 324
 325 /**
 326  The key path which the sort descriptor orders results by.
 327  */
 328 @property (nonatomic, readonly) NSString *keyPath;
 329
 330 /**
 331  Whether the descriptor sorts in ascending or descending order.
 332  */
 333 @property (nonatomic, readonly) BOOL ascending;
 334
 335 #pragma mark - Methods
 336
 337 /**
 338  Returns a new sort descriptor for the given key path and sort direction.
 339  */
 340 + (instancetype)sortDescriptorWithKeyPath:(NSString *)keyPath ascending:(BOOL)ascending;
 341
 342 /**
 343  Returns a copy of the receiver with the sort direction reversed.
 344  */
 345 - (instancetype)reversedSortDescriptor;
 346
 347 @end
 348
 349 /**
 350  A `RLMCollectionChange` object encapsulates information about changes to collections
 351  that are reported by Realm notifications.
 352
 353  `RLMCollectionChange` is passed to the notification blocks registered with
 354  `-addNotificationBlock` on `RLMArray` and `RLMResults`, and reports what rows in the
 355  collection changed since the last time the notification block was called.
 356
 357  The change information is available in two formats: a simple array of row
 358  indices in the collection for each type of change, and an array of index paths
 359  in a requested section suitable for passing directly to `UITableView`'s batch
 360  update methods. A complete example of updating a `UITableView` named `tv`:
 361
 362      [tv beginUpdates];
 363      [tv deleteRowsAtIndexPaths:[changes deletionsInSection:0] withRowAnimation:UITableViewRowAnimationAutomatic];
 364      [tv insertRowsAtIndexPaths:[changes insertionsInSection:0] withRowAnimation:UITableViewRowAnimationAutomatic];
 365      [tv reloadRowsAtIndexPaths:[changes modificationsInSection:0] withRowAnimation:UITableViewRowAnimationAutomatic];
 366      [tv endUpdates];
 367
 368  All of the arrays in an `RLMCollectionChange` are always sorted in ascending order.
 369  */
 370 @interface RLMCollectionChange : NSObject
 371 /// The indices of objects in the previous version of the collection which have
 372 /// been removed from this one.
 373 @property (nonatomic, readonly) NSArray<NSNumber *> *deletions;
 374
 375 /// The indices in the new version of the collection which were newly inserted.
 376 @property (nonatomic, readonly) NSArray<NSNumber *> *insertions;
 377
 378 /**
 379  The indices in the new version of the collection which were modified.
 380
 381  For `RLMResults`, this means that one or more of the properties of the object at
 382  that index were modified (or an object linked to by that object was
 383  modified).
 384
 385  For `RLMArray`, the array itself being modified to contain a
 386  different object at that index will also be reported as a modification.
 387  */
 388 @property (nonatomic, readonly) NSArray<NSNumber *> *modifications;
 389
 390 /// Returns the index paths of the deletion indices in the given section.
 391 - (NSArray<NSIndexPath *> *)deletionsInSection:(NSUInteger)section;
 392
 393 /// Returns the index paths of the insertion indices in the given section.
 394 - (NSArray<NSIndexPath *> *)insertionsInSection:(NSUInteger)section;
 395
 396 /// Returns the index paths of the modification indices in the given section.
 397 - (NSArray<NSIndexPath *> *)modificationsInSection:(NSUInteger)section;
 398 @end
 399
 400 NS_ASSUME_NONNULL_END