iOS/Pods/RealmSwift/RealmSwift/RealmCollection.swift

   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
  20 import Realm
  21
  22 /**
  23  An iterator for a `RealmCollection` instance.
  24  */
  25 public struct RLMIterator<Element: RealmCollectionValue>: IteratorProtocol {
  26     private var generatorBase: NSFastEnumerationIterator
  27
  28     init(collection: RLMCollection) {
  29         generatorBase = NSFastEnumerationIterator(collection)
  30     }
  31
  32     /// Advance to the next element and return it, or `nil` if no next element exists.
  33     public mutating func next() -> Element? {
  34         let next = generatorBase.next()
  35         if let next = next as? Object? {
  36             if next == nil {
  37                 return nil as Element?
  38             }
  39             return unsafeBitCast(next, to: Optional<Element>.self)
  40         }
  41         return next as! Element?
  42     }
  43 }
  44
  45 /**
  46  A `RealmCollectionChange` value encapsulates information about changes to collections
  47  that are reported by Realm notifications.
  48
  49  The change information is available in two formats: a simple array of row
  50  indices in the collection for each type of change, and an array of index paths
  51  in a requested section suitable for passing directly to `UITableView`'s batch
  52  update methods.
  53
  54  The arrays of indices in the `.update` case follow `UITableView`'s batching
  55  conventions, and can be passed as-is to a table view's batch update functions after being converted to index paths.
  56  For example, for a simple one-section table view, you can do the following:
  57
  58  ```swift
  59  self.notificationToken = results.observe { changes in
  60      switch changes {
  61      case .initial:
  62          // Results are now populated and can be accessed without blocking the UI
  63          self.tableView.reloadData()
  64          break
  65      case .update(_, let deletions, let insertions, let modifications):
  66          // Query results have changed, so apply them to the TableView
  67          self.tableView.beginUpdates()
  68          self.tableView.insertRows(at: insertions.map { IndexPath(row: $0, section: 0) },
  69             with: .automatic)
  70          self.tableView.deleteRows(at: deletions.map { IndexPath(row: $0, section: 0) },
  71             with: .automatic)
  72          self.tableView.reloadRows(at: modifications.map { IndexPath(row: $0, section: 0) },
  73             with: .automatic)
  74          self.tableView.endUpdates()
  75          break
  76      case .error(let err):
  77          // An error occurred while opening the Realm file on the background worker thread
  78          fatalError("\(err)")
  79          break
  80      }
  81  }
  82  ```
  83  */
  84 public enum RealmCollectionChange<CollectionType> {
  85     /**
  86      `.initial` indicates that the initial run of the query has completed (if
  87      applicable), and the collection can now be used without performing any
  88      blocking work.
  89      */
  90     case initial(CollectionType)
  91
  92     /**
  93      `.update` indicates that a write transaction has been committed which
  94      either changed which objects are in the collection, and/or modified one
  95      or more of the objects in the collection.
  96
  97      All three of the change arrays are always sorted in ascending order.
  98
  99      - parameter deletions:     The indices in the previous version of the collection which were removed from this one.
 100      - parameter insertions:    The indices in the new collection which were added in this version.
 101      - parameter modifications: The indices of the objects in the new collection which were modified in this version.
 102      */
 103     case update(CollectionType, deletions: [Int], insertions: [Int], modifications: [Int])
 104
 105     /**
 106      If an error occurs, notification blocks are called one time with a `.error`
 107      result and an `NSError` containing details about the error. This can only
 108      currently happen if opening the Realm on a background thread to calcuate
 109      the change set fails. The callback will never be called again after it is
 110      invoked with a .error value.
 111      */
 112     case error(Error)
 113
 114     static func fromObjc(value: CollectionType, change: RLMCollectionChange?, error: Error?) -> RealmCollectionChange {
 115         if let error = error {
 116             return .error(error)
 117         }
 118         if let change = change {
 119             return .update(value,
 120                 deletions: forceCast(change.deletions, to: [Int].self),
 121                 insertions: forceCast(change.insertions, to: [Int].self),
 122                 modifications: forceCast(change.modifications, to: [Int].self))
 123         }
 124         return .initial(value)
 125     }
 126 }
 127
 128 private func forceCast<A, U>(_ from: A, to type: U.Type) -> U {
 129     return from as! U
 130 }
 131
 132 /// A type which can be stored in a Realm List or Results
 133 public protocol RealmCollectionValue {
 134     /// :nodoc:
 135     // swiftlint:disable:next identifier_name
 136     static func _rlmArray() -> RLMArray<AnyObject>
 137 }
 138
 139 extension RealmCollectionValue {
 140     /// :nodoc:
 141     // swiftlint:disable:next identifier_name
 142     public static func _rlmArray() -> RLMArray<AnyObject> {
 143         return RLMArray(objectType: .int, optional: false)
 144     }
 145 }
 146
 147 extension Optional: RealmCollectionValue {
 148     /// :nodoc:
 149     // swiftlint:disable:next identifier_name
 150     public static func _rlmArray() -> RLMArray<AnyObject> {
 151         switch Wrapped.self {
 152         case is Int.Type, is Int8.Type, is Int16.Type, is Int32.Type, is Int64.Type:
 153             return RLMArray(objectType: .int, optional: true)
 154         case is Bool.Type:   return RLMArray(objectType: .bool, optional: true)
 155         case is Float.Type:  return RLMArray(objectType: .float, optional: true)
 156         case is Double.Type: return RLMArray(objectType: .double, optional: true)
 157         case is String.Type: return RLMArray(objectType: .string, optional: true)
 158         case is Data.Type:   return RLMArray(objectType: .data, optional: true)
 159         case is Date.Type:   return RLMArray(objectType: .date, optional: true)
 160         default: fatalError("Unsupported type for List: \(Wrapped.self)?")
 161         }
 162     }
 163 }
 164
 165 extension Int: RealmCollectionValue {}
 166 extension Int8: RealmCollectionValue {}
 167 extension Int16: RealmCollectionValue {}
 168 extension Int32: RealmCollectionValue {}
 169 extension Int64: RealmCollectionValue {}
 170 extension Float: RealmCollectionValue {
 171     /// :nodoc:
 172     // swiftlint:disable:next identifier_name
 173     public static func _rlmArray() -> RLMArray<AnyObject> {
 174         return RLMArray(objectType: .float, optional: false)
 175     }
 176 }
 177 extension Double: RealmCollectionValue {
 178     /// :nodoc:
 179     // swiftlint:disable:next identifier_name
 180     public static func _rlmArray() -> RLMArray<AnyObject> {
 181         return RLMArray(objectType: .double, optional: false)
 182     }
 183 }
 184 extension Bool: RealmCollectionValue {
 185     /// :nodoc:
 186     // swiftlint:disable:next identifier_name
 187     public static func _rlmArray() -> RLMArray<AnyObject> {
 188         return RLMArray(objectType: .bool, optional: false)
 189     }
 190 }
 191
 192 extension String: RealmCollectionValue {
 193     /// :nodoc:
 194     // swiftlint:disable:next identifier_name
 195     public static func _rlmArray() -> RLMArray<AnyObject> {
 196         return RLMArray(objectType: .string, optional: false)
 197     }
 198 }
 199 extension Date: RealmCollectionValue {
 200     /// :nodoc:
 201     // swiftlint:disable:next identifier_name
 202     public static func _rlmArray() -> RLMArray<AnyObject> {
 203         return RLMArray(objectType: .date, optional: false)
 204     }
 205 }
 206 extension Data: RealmCollectionValue {
 207     /// :nodoc:
 208     // swiftlint:disable:next identifier_name
 209     public static func _rlmArray() -> RLMArray<AnyObject> {
 210         return RLMArray(objectType: .data, optional: false)
 211     }
 212 }
 213
 214 #if swift(>=3.2)
 215 // FIXME: When we drop support for Swift 3.1, change ElementType to Element
 216 // throughout the project (this is a non-breaking change). We use ElementType
 217 // only because of limitations in Swift 3.1's compiler.
 218 /// :nodoc:
 219 public protocol RealmCollectionBase: RandomAccessCollection, LazyCollectionProtocol, CustomStringConvertible, ThreadConfined where Element: RealmCollectionValue {
 220     typealias ElementType = Element
 221 }
 222 #else
 223 /// :nodoc:
 224 public protocol RealmCollectionBase: RandomAccessCollection, LazyCollectionProtocol, CustomStringConvertible, ThreadConfined {
 225     /// The type of the objects contained in the collection.
 226     associatedtype ElementType: RealmCollectionValue
 227 }
 228 #endif
 229
 230 /**
 231  A homogenous collection of `Object`s which can be retrieved, filtered, sorted, and operated upon.
 232 */
 233 public protocol RealmCollection: RealmCollectionBase {
 234     // Must also conform to `AssistedObjectiveCBridgeable`
 235
 236     // MARK: Properties
 237
 238     /// The Realm which manages the collection, or `nil` for unmanaged collections.
 239     var realm: Realm? { get }
 240
 241     /**
 242      Indicates if the collection can no longer be accessed.
 243
 244      The collection can no longer be accessed if `invalidate()` is called on the `Realm` that manages the collection.
 245      */
 246     var isInvalidated: Bool { get }
 247
 248     /// The number of objects in the collection.
 249     var count: Int { get }
 250
 251     /// A human-readable description of the objects contained in the collection.
 252     var description: String { get }
 253
 254
 255     // MARK: Index Retrieval
 256
 257     /**
 258      Returns the index of an object in the collection, or `nil` if the object is not present.
 259
 260      - parameter object: An object.
 261      */
 262     func index(of object: ElementType) -> Int?
 263
 264     /**
 265      Returns the index of the first object matching the predicate, or `nil` if no objects match.
 266
 267      - parameter predicate: The predicate to use to filter the objects.
 268      */
 269     func index(matching predicate: NSPredicate) -> Int?
 270
 271     /**
 272      Returns the index of the first object matching the predicate, or `nil` if no objects match.
 273
 274      - parameter predicateFormat: A predicate format string, optionally followed by a variable number of arguments.
 275      */
 276     func index(matching predicateFormat: String, _ args: Any...) -> Int?
 277
 278
 279     // MARK: Filtering
 280
 281     /**
 282      Returns a `Results` containing all objects matching the given predicate in the collection.
 283
 284      - parameter predicateFormat: A predicate format string, optionally followed by a variable number of arguments.
 285      */
 286     func filter(_ predicateFormat: String, _ args: Any...) -> Results<ElementType>
 287
 288     /**
 289      Returns a `Results` containing all objects matching the given predicate in the collection.
 290
 291      - parameter predicate: The predicate to use to filter the objects.
 292      */
 293     func filter(_ predicate: NSPredicate) -> Results<ElementType>
 294
 295
 296     // MARK: Sorting
 297
 298     /**
 299      Returns a `Results` containing the objects in the collection, but sorted.
 300
 301      Objects are sorted based on the values of the given key path. For example, to sort a collection of `Student`s from
 302      youngest to oldest based on their `age` property, you might call
 303      `students.sorted(byKeyPath: "age", ascending: true)`.
 304
 305      - warning: Collections may only be sorted by properties of boolean, `Date`, `NSDate`, single and double-precision
 306                 floating point, integer, and string types.
 307
 308      - parameter keyPath:   The key path to sort by.
 309      - parameter ascending: The direction to sort in.
 310      */
 311     func sorted(byKeyPath keyPath: String, ascending: Bool) -> Results<ElementType>
 312
 313     /**
 314      Returns a `Results` containing the objects in the collection, but sorted.
 315
 316      - warning: Collections may only be sorted by properties of boolean, `Date`, `NSDate`, single and double-precision
 317                 floating point, integer, and string types.
 318
 319      - see: `sorted(byKeyPath:ascending:)`
 320
 321      - parameter sortDescriptors: A sequence of `SortDescriptor`s to sort by.
 322      */
 323     func sorted<S: Sequence>(by sortDescriptors: S) -> Results<ElementType> where S.Iterator.Element == SortDescriptor
 324
 325     // MARK: Aggregate Operations
 326
 327     /**
 328      Returns the minimum (lowest) value of the given property among all the objects in the collection, or `nil` if the
 329      collection is empty.
 330
 331      - warning: Only a property whose type conforms to the `MinMaxType` protocol can be specified.
 332
 333      - parameter property: The name of a property whose minimum value is desired.
 334      */
 335     func min<T: MinMaxType>(ofProperty property: String) -> T?
 336
 337     /**
 338      Returns the maximum (highest) value of the given property among all the objects in the collection, or `nil` if the
 339      collection is empty.
 340
 341      - warning: Only a property whose type conforms to the `MinMaxType` protocol can be specified.
 342
 343      - parameter property: The name of a property whose minimum value is desired.
 344      */
 345     func max<T: MinMaxType>(ofProperty property: String) -> T?
 346
 347     /**
 348     Returns the sum of the given property for objects in the collection, or `nil` if the collection is empty.
 349
 350     - warning: Only names of properties of a type conforming to the `AddableType` protocol can be used.
 351
 352     - parameter property: The name of a property conforming to `AddableType` to calculate sum on.
 353     */
 354     func sum<T: AddableType>(ofProperty property: String) -> T
 355
 356     /**
 357      Returns the average value of a given property over all the objects in the collection, or `nil` if
 358      the collection is empty.
 359
 360      - warning: Only a property whose type conforms to the `AddableType` protocol can be specified.
 361
 362      - parameter property: The name of a property whose values should be summed.
 363      */
 364     func average(ofProperty property: String) -> Double?
 365
 366
 367     // MARK: Key-Value Coding
 368
 369     /**
 370      Returns an `Array` containing the results of invoking `valueForKey(_:)` with `key` on each of the collection's
 371      objects.
 372
 373      - parameter key: The name of the property whose values are desired.
 374      */
 375     func value(forKey key: String) -> Any?
 376
 377     /**
 378      Returns an `Array` containing the results of invoking `valueForKeyPath(_:)` with `keyPath` on each of the
 379      collection's objects.
 380
 381      - parameter keyPath: The key path to the property whose values are desired.
 382      */
 383     func value(forKeyPath keyPath: String) -> Any?
 384
 385     /**
 386      Invokes `setValue(_:forKey:)` on each of the collection's objects using the specified `value` and `key`.
 387
 388      - warning: This method may only be called during a write transaction.
 389
 390      - parameter value: The object value.
 391      - parameter key:   The name of the property whose value should be set on each object.
 392      */
 393     func setValue(_ value: Any?, forKey key: String)
 394
 395     // MARK: Notifications
 396
 397     /**
 398      Registers a block to be called each time the collection changes.
 399
 400      The block will be asynchronously called with the initial results, and then called again after each write
 401      transaction which changes either any of the objects in the collection, or which objects are in the collection.
 402
 403      The `change` parameter that is passed to the block reports, in the form of indices within the collection, which of
 404      the objects were added, removed, or modified during each write transaction. See the `RealmCollectionChange`
 405      documentation for more information on the change information supplied and an example of how to use it to update a
 406      `UITableView`.
 407
 408      At the time when the block is called, the collection will be fully evaluated and up-to-date, and as long as you do
 409      not perform a write transaction on the same thread or explicitly call `realm.refresh()`, accessing it will never
 410      perform blocking work.
 411
 412      Notifications are delivered via the standard run loop, and so can't be delivered while the run loop is blocked by
 413      other activity. When notifications can't be delivered instantly, multiple notifications may be coalesced into a
 414      single notification. This can include the notification with the initial collection.
 415
 416      For example, the following code performs a write transaction immediately after adding the notification block, so
 417      there is no opportunity for the initial notification to be delivered first. As a result, the initial notification
 418      will reflect the state of the Realm after the write transaction.
 419
 420      ```swift
 421      let results = realm.objects(Dog.self)
 422      print("dogs.count: \(dogs?.count)") // => 0
 423      let token = dogs.observe { changes in
 424      switch changes {
 425          case .initial(let dogs):
 426              // Will print "dogs.count: 1"
 427              print("dogs.count: \(dogs.count)")
 428              break
 429          case .update:
 430              // Will not be hit in this example
 431              break
 432          case .error:
 433              break
 434          }
 435      }
 436      try! realm.write {
 437          let dog = Dog()
 438          dog.name = "Rex"
 439          person.dogs.append(dog)
 440      }
 441      // end of run loop execution context
 442      ```
 443
 444      You must retain the returned token for as long as you want updates to be sent to the block. To stop receiving
 445      updates, call `invalidate()` on the token.
 446
 447      - warning: This method cannot be called during a write transaction, or when the containing Realm is read-only.
 448
 449      - parameter block: The block to be called whenever a change occurs.
 450      - returns: A token which must be held for as long as you want updates to be delivered.
 451      */
 452     func observe(_ block: @escaping (RealmCollectionChange<Self>) -> Void) -> NotificationToken
 453
 454     /// :nodoc:
 455     func _observe(_ block: @escaping (RealmCollectionChange<AnyRealmCollection<ElementType>>) -> Void) -> NotificationToken
 456 }
 457
 458 /// :nodoc:
 459 public protocol OptionalProtocol {
 460     associatedtype Wrapped
 461     /// :nodoc:
 462     // swiftlint:disable:next identifier_name
 463     func _rlmInferWrappedType() -> Wrapped
 464 }
 465
 466 extension Optional: OptionalProtocol {
 467     /// :nodoc:
 468     // swiftlint:disable:next identifier_name
 469     public func _rlmInferWrappedType() -> Wrapped { return self! }
 470 }
 471
 472
 473 // FIXME: See the declaration of RealmCollectionBase for why this `#if` is required.
 474 #if swift(>=3.2)
 475 public extension RealmCollection where Element: MinMaxType {
 476     /**
 477      Returns the minimum (lowest) value of the collection, or `nil` if the collection is empty.
 478      */
 479     public func min() -> Element? {
 480         return min(ofProperty: "self")
 481     }
 482     /**
 483      Returns the maximum (highest) value of the collection, or `nil` if the collection is empty.
 484      */
 485     public func max() -> Element? {
 486         return max(ofProperty: "self")
 487     }
 488 }
 489
 490 public extension RealmCollection where Element: OptionalProtocol, Element.Wrapped: MinMaxType {
 491     /**
 492      Returns the minimum (lowest) value of the collection, or `nil` if the collection is empty.
 493      */
 494     public func min() -> Element.Wrapped? {
 495         return min(ofProperty: "self")
 496     }
 497     /**
 498      Returns the maximum (highest) value of the collection, or `nil` if the collection is empty.
 499      */
 500     public func max() -> Element.Wrapped? {
 501         return max(ofProperty: "self")
 502     }
 503 }
 504
 505 public extension RealmCollection where Element: AddableType {
 506     /**
 507      Returns the sum of the values in the collection, or `nil` if the collection is empty.
 508      */
 509     public func sum() -> Element {
 510         return sum(ofProperty: "self")
 511     }
 512     /**
 513      Returns the average of all of the values in the collection.
 514      */
 515     public func average() -> Double? {
 516         return average(ofProperty: "self")
 517     }
 518 }
 519
 520 public extension RealmCollection where Element: OptionalProtocol, Element.Wrapped: AddableType {
 521     /**
 522      Returns the sum of the values in the collection, or `nil` if the collection is empty.
 523      */
 524     public func sum() -> Element.Wrapped {
 525         return sum(ofProperty: "self")
 526     }
 527     /**
 528      Returns the average of all of the values in the collection.
 529      */
 530     public func average() -> Double? {
 531         return average(ofProperty: "self")
 532     }
 533 }
 534
 535 public extension RealmCollection where Element: Comparable {
 536     /**
 537      Returns a `Results` containing the objects in the collection, but sorted.
 538
 539      Objects are sorted based on their values. For example, to sort a collection of `Date`s from
 540      neweset to oldest based, you might call `dates.sorted(ascending: true)`.
 541
 542      - parameter ascending: The direction to sort in.
 543      */
 544     public func sorted(ascending: Bool = true) -> Results<Element> {
 545         return sorted(byKeyPath: "self", ascending: ascending)
 546     }
 547 }
 548
 549 public extension RealmCollection where Element: OptionalProtocol, Element.Wrapped: Comparable {
 550     /**
 551      Returns a `Results` containing the objects in the collection, but sorted.
 552
 553      Objects are sorted based on their values. For example, to sort a collection of `Date`s from
 554      neweset to oldest based, you might call `dates.sorted(ascending: true)`.
 555
 556      - parameter ascending: The direction to sort in.
 557      */
 558     public func sorted(ascending: Bool = true) -> Results<Element> {
 559         return sorted(byKeyPath: "self", ascending: ascending)
 560     }
 561 }
 562 #else
 563 public extension RealmCollection where ElementType: MinMaxType {
 564     /**
 565      Returns the minimum (lowest) value of the collection, or `nil` if the collection is empty.
 566      */
 567     public func min() -> ElementType? {
 568         return min(ofProperty: "self")
 569     }
 570     /**
 571      Returns the maximum (highest) value of the collection, or `nil` if the collection is empty.
 572      */
 573     public func max() -> ElementType? {
 574         return max(ofProperty: "self")
 575     }
 576 }
 577
 578 public extension RealmCollection where ElementType: OptionalProtocol, ElementType.Wrapped: MinMaxType {
 579     /**
 580      Returns the minimum (lowest) value of the collection, or `nil` if the collection is empty.
 581      */
 582     public func min() -> ElementType.Wrapped? {
 583         return min(ofProperty: "self")
 584     }
 585     /**
 586      Returns the maximum (highest) value of the collection, or `nil` if the collection is empty.
 587      */
 588     public func max() -> ElementType.Wrapped? {
 589         return max(ofProperty: "self")
 590     }
 591 }
 592
 593 public extension RealmCollection where ElementType: AddableType {
 594     /**
 595      Returns the sum of the values in the collection, or `nil` if the collection is empty.
 596      */
 597     public func sum() -> ElementType {
 598         return sum(ofProperty: "self")
 599     }
 600     /**
 601      Returns the average of all of the values in the collection.
 602      */
 603     public func average() -> Double? {
 604         return average(ofProperty: "self")
 605     }
 606 }
 607
 608 public extension RealmCollection where ElementType: OptionalProtocol, ElementType.Wrapped: AddableType {
 609     /**
 610      Returns the sum of the values in the collection, or `nil` if the collection is empty.
 611      */
 612     public func sum() -> ElementType.Wrapped {
 613         return sum(ofProperty: "self")
 614     }
 615     /**
 616      Returns the average of all of the values in the collection.
 617      */
 618     public func average() -> Double? {
 619         return average(ofProperty: "self")
 620     }
 621 }
 622
 623 public extension RealmCollection where ElementType: Comparable {
 624     /**
 625      Returns a `Results` containing the objects in the collection, but sorted.
 626
 627      Objects are sorted based on their values. For example, to sort a collection of `Date`s from
 628      neweset to oldest based, you might call `dates.sorted(ascending: true)`.
 629
 630      - parameter ascending: The direction to sort in.
 631      */
 632     public func sorted(ascending: Bool = true) -> Results<ElementType> {
 633         return sorted(byKeyPath: "self", ascending: ascending)
 634     }
 635 }
 636
 637 public extension RealmCollection where ElementType: OptionalProtocol, ElementType.Wrapped: Comparable {
 638     /**
 639      Returns a `Results` containing the objects in the collection, but sorted.
 640
 641      Objects are sorted based on their values. For example, to sort a collection of `Date`s from
 642      neweset to oldest based, you might call `dates.sorted(ascending: true)`.
 643
 644      - parameter ascending: The direction to sort in.
 645      */
 646     public func sorted(ascending: Bool = true) -> Results<ElementType> {
 647         return sorted(byKeyPath: "self", ascending: ascending)
 648     }
 649 }
 650 #endif
 651
 652 private class _AnyRealmCollectionBase<T: RealmCollectionValue>: AssistedObjectiveCBridgeable {
 653     typealias Wrapper = AnyRealmCollection<Element>
 654     typealias Element = T
 655     var realm: Realm? { fatalError() }
 656     var isInvalidated: Bool { fatalError() }
 657     var count: Int { fatalError() }
 658     var description: String { fatalError() }
 659     func index(of object: Element) -> Int? { fatalError() }
 660     func index(matching predicate: NSPredicate) -> Int? { fatalError() }
 661     func index(matching predicateFormat: String, _ args: Any...) -> Int? { fatalError() }
 662     func filter(_ predicateFormat: String, _ args: Any...) -> Results<Element> { fatalError() }
 663     func filter(_ predicate: NSPredicate) -> Results<Element> { fatalError() }
 664     func sorted(byKeyPath keyPath: String, ascending: Bool) -> Results<Element> { fatalError() }
 665     func sorted<S: Sequence>(by sortDescriptors: S) -> Results<Element> where S.Iterator.Element == SortDescriptor {
 666         fatalError()
 667     }
 668     func min<T: MinMaxType>(ofProperty property: String) -> T? { fatalError() }
 669     func max<T: MinMaxType>(ofProperty property: String) -> T? { fatalError() }
 670     func sum<T: AddableType>(ofProperty property: String) -> T { fatalError() }
 671     func average(ofProperty property: String) -> Double? { fatalError() }
 672     subscript(position: Int) -> Element { fatalError() }
 673     func makeIterator() -> RLMIterator<T> { fatalError() }
 674     var startIndex: Int { fatalError() }
 675     var endIndex: Int { fatalError() }
 676     func value(forKey key: String) -> Any? { fatalError() }
 677     func value(forKeyPath keyPath: String) -> Any? { fatalError() }
 678     func setValue(_ value: Any?, forKey key: String) { fatalError() }
 679     func _observe(_ block: @escaping (RealmCollectionChange<Wrapper>) -> Void)
 680         -> NotificationToken { fatalError() }
 681     class func bridging(from objectiveCValue: Any, with metadata: Any?) -> Self { fatalError() }
 682     var bridged: (objectiveCValue: Any, metadata: Any?) { fatalError() }
 683 }
 684
 685 private final class _AnyRealmCollection<C: RealmCollection>: _AnyRealmCollectionBase<C.ElementType> {
 686     let base: C
 687     init(base: C) {
 688         self.base = base
 689     }
 690
 691     // MARK: Properties
 692
 693     override var realm: Realm? { return base.realm }
 694     override var isInvalidated: Bool { return base.isInvalidated }
 695     override var count: Int { return base.count }
 696     override var description: String { return base.description }
 697
 698
 699     // MARK: Index Retrieval
 700
 701     override func index(of object: C.ElementType) -> Int? { return base.index(of: object) }
 702
 703     override func index(matching predicate: NSPredicate) -> Int? { return base.index(matching: predicate) }
 704
 705     override func index(matching predicateFormat: String, _ args: Any...) -> Int? {
 706         return base.index(matching: NSPredicate(format: predicateFormat, argumentArray: unwrapOptionals(in: args)))
 707     }
 708
 709     // MARK: Filtering
 710
 711     override func filter(_ predicateFormat: String, _ args: Any...) -> Results<C.ElementType> {
 712         return base.filter(NSPredicate(format: predicateFormat, argumentArray: unwrapOptionals(in: args)))
 713     }
 714
 715     override func filter(_ predicate: NSPredicate) -> Results<C.ElementType> { return base.filter(predicate) }
 716
 717     // MARK: Sorting
 718
 719     override func sorted(byKeyPath keyPath: String, ascending: Bool) -> Results<C.ElementType> {
 720         return base.sorted(byKeyPath: keyPath, ascending: ascending)
 721     }
 722
 723     override func sorted<S: Sequence>
 724         (by sortDescriptors: S) -> Results<C.ElementType> where S.Iterator.Element == SortDescriptor {
 725         return base.sorted(by: sortDescriptors)
 726     }
 727
 728
 729     // MARK: Aggregate Operations
 730
 731     override func min<T: MinMaxType>(ofProperty property: String) -> T? {
 732         return base.min(ofProperty: property)
 733     }
 734
 735     override func max<T: MinMaxType>(ofProperty property: String) -> T? {
 736         return base.max(ofProperty: property)
 737     }
 738
 739     override func sum<T: AddableType>(ofProperty property: String) -> T {
 740         return base.sum(ofProperty: property)
 741     }
 742
 743     override func average(ofProperty property: String) -> Double? {
 744         return base.average(ofProperty: property)
 745     }
 746
 747
 748     // MARK: Sequence Support
 749
 750     override subscript(position: Int) -> C.ElementType {
 751         #if swift(>=3.2)
 752             return base[position as! C.Index]
 753         #else
 754             return base[position as! C.Index] as! C.ElementType
 755         #endif
 756     }
 757
 758     override func makeIterator() -> RLMIterator<Element> {
 759         // FIXME: it should be possible to avoid this force-casting
 760         return base.makeIterator() as! RLMIterator<Element>
 761     }
 762
 763
 764     // MARK: Collection Support
 765
 766     override var startIndex: Int {
 767         // FIXME: it should be possible to avoid this force-casting
 768         return base.startIndex as! Int
 769     }
 770
 771     override var endIndex: Int {
 772         // FIXME: it should be possible to avoid this force-casting
 773         return base.endIndex as! Int
 774     }
 775
 776
 777     // MARK: Key-Value Coding
 778
 779     override func value(forKey key: String) -> Any? { return base.value(forKey: key) }
 780
 781     override func value(forKeyPath keyPath: String) -> Any? { return base.value(forKeyPath: keyPath) }
 782
 783     override func setValue(_ value: Any?, forKey key: String) { base.setValue(value, forKey: key) }
 784
 785     // MARK: Notifications
 786
 787     /// :nodoc:
 788     override func _observe(_ block: @escaping (RealmCollectionChange<Wrapper>) -> Void)
 789         -> NotificationToken { return base._observe(block) }
 790
 791     // MARK: AssistedObjectiveCBridgeable
 792
 793     override class func bridging(from objectiveCValue: Any, with metadata: Any?) -> _AnyRealmCollection {
 794         return _AnyRealmCollection(
 795             base: (C.self as! AssistedObjectiveCBridgeable.Type).bridging(from: objectiveCValue, with: metadata) as! C)
 796     }
 797
 798     override var bridged: (objectiveCValue: Any, metadata: Any?) {
 799         return (base as! AssistedObjectiveCBridgeable).bridged
 800     }
 801 }
 802
 803 /**
 804  A type-erased `RealmCollection`.
 805
 806  Instances of `RealmCollection` forward operations to an opaque underlying collection having the same `Element` type.
 807  */
 808 public final class AnyRealmCollection<Element: RealmCollectionValue>: RealmCollection {
 809
 810     /// The type of the objects contained within the collection.
 811     public typealias ElementType = Element
 812
 813     public func index(after i: Int) -> Int { return i + 1 }
 814     public func index(before i: Int) -> Int { return i - 1 }
 815
 816     /// The type of the objects contained in the collection.
 817     fileprivate let base: _AnyRealmCollectionBase<Element>
 818
 819     fileprivate init(base: _AnyRealmCollectionBase<Element>) {
 820         self.base = base
 821     }
 822
 823     /// Creates an `AnyRealmCollection` wrapping `base`.
 824     public init<C: RealmCollection>(_ base: C) where C.ElementType == Element {
 825         self.base = _AnyRealmCollection(base: base)
 826     }
 827
 828     // MARK: Properties
 829
 830     /// The Realm which manages the collection, or `nil` if the collection is unmanaged.
 831     public var realm: Realm? { return base.realm }
 832
 833     /**
 834      Indicates if the collection can no longer be accessed.
 835
 836      The collection can no longer be accessed if `invalidate()` is called on the containing `realm`.
 837      */
 838     public var isInvalidated: Bool { return base.isInvalidated }
 839
 840     /// The number of objects in the collection.
 841     public var count: Int { return base.count }
 842
 843     /// A human-readable description of the objects contained in the collection.
 844     public var description: String { return base.description }
 845
 846
 847     // MARK: Index Retrieval
 848
 849     /**
 850      Returns the index of the given object, or `nil` if the object is not in the collection.
 851
 852      - parameter object: An object.
 853      */
 854     public func index(of object: Element) -> Int? { return base.index(of: object) }
 855
 856     /**
 857      Returns the index of the first object matching the given predicate, or `nil` if no objects match.
 858
 859      - parameter predicate: The predicate with which to filter the objects.
 860      */
 861     public func index(matching predicate: NSPredicate) -> Int? { return base.index(matching: predicate) }
 862
 863     /**
 864      Returns the index of the first object matching the given predicate, or `nil` if no objects match.
 865
 866      - parameter predicateFormat: A predicate format string, optionally followed by a variable number of arguments.
 867      */
 868     public func index(matching predicateFormat: String, _ args: Any...) -> Int? {
 869         return base.index(matching: NSPredicate(format: predicateFormat, argumentArray: unwrapOptionals(in: args)))
 870     }
 871
 872     // MARK: Filtering
 873
 874     /**
 875      Returns a `Results` containing all objects matching the given predicate in the collection.
 876
 877      - parameter predicateFormat: A predicate format string, optionally followed by a variable number of arguments.
 878      */
 879     public func filter(_ predicateFormat: String, _ args: Any...) -> Results<Element> {
 880         return base.filter(NSPredicate(format: predicateFormat, argumentArray: unwrapOptionals(in: args)))
 881     }
 882
 883     /**
 884      Returns a `Results` containing all objects matching the given predicate in the collection.
 885
 886      - parameter predicate: The predicate with which to filter the objects.
 887
 888      - returns: A `Results` containing objects that match the given predicate.
 889      */
 890     public func filter(_ predicate: NSPredicate) -> Results<Element> { return base.filter(predicate) }
 891
 892
 893     // MARK: Sorting
 894
 895     /**
 896      Returns a `Results` containing the objects in the collection, but sorted.
 897
 898      Objects are sorted based on the values of the given key path. For example, to sort a collection of `Student`s from
 899      youngest to oldest based on their `age` property, you might call
 900      `students.sorted(byKeyPath: "age", ascending: true)`.
 901
 902      - warning:  Collections may only be sorted by properties of boolean, `Date`, `NSDate`, single and double-precision
 903                  floating point, integer, and string types.
 904
 905      - parameter keyPath:  The key path to sort by.
 906      - parameter ascending: The direction to sort in.
 907      */
 908     public func sorted(byKeyPath keyPath: String, ascending: Bool) -> Results<Element> {
 909         return base.sorted(byKeyPath: keyPath, ascending: ascending)
 910     }
 911
 912     /**
 913      Returns a `Results` containing the objects in the collection, but sorted.
 914
 915      - warning:  Collections may only be sorted by properties of boolean, `Date`, `NSDate`, single and double-precision
 916                  floating point, integer, and string types.
 917
 918      - see: `sorted(byKeyPath:ascending:)`
 919
 920      - parameter sortDescriptors: A sequence of `SortDescriptor`s to sort by.
 921      */
 922     public func sorted<S: Sequence>(by sortDescriptors: S) -> Results<Element>
 923         where S.Iterator.Element == SortDescriptor {
 924         return base.sorted(by: sortDescriptors)
 925     }
 926
 927
 928     // MARK: Aggregate Operations
 929
 930     /**
 931      Returns the minimum (lowest) value of the given property among all the objects in the collection, or `nil` if the
 932      collection is empty.
 933
 934      - warning: Only a property whose type conforms to the `MinMaxType` protocol can be specified.
 935
 936      - parameter property: The name of a property whose minimum value is desired.
 937      */
 938     public func min<T: MinMaxType>(ofProperty property: String) -> T? {
 939         return base.min(ofProperty: property)
 940     }
 941
 942     /**
 943      Returns the maximum (highest) value of the given property among all the objects in the collection, or `nil` if the
 944      collection is empty.
 945
 946      - warning: Only a property whose type conforms to the `MinMaxType` protocol can be specified.
 947
 948      - parameter property: The name of a property whose minimum value is desired.
 949      */
 950     public func max<T: MinMaxType>(ofProperty property: String) -> T? {
 951         return base.max(ofProperty: property)
 952     }
 953
 954     /**
 955      Returns the sum of the values of a given property over all the objects in the collection.
 956
 957      - warning: Only a property whose type conforms to the `AddableType` protocol can be specified.
 958
 959      - parameter property: The name of a property whose values should be summed.
 960      */
 961     public func sum<T: AddableType>(ofProperty property: String) -> T { return base.sum(ofProperty: property) }
 962
 963     /**
 964      Returns the average value of a given property over all the objects in the collection, or `nil` if the collection is
 965      empty.
 966
 967      - warning: Only the name of a property whose type conforms to the `AddableType` protocol can be specified.
 968
 969      - parameter property: The name of a property whose average value should be calculated.
 970      */
 971     public func average(ofProperty property: String) -> Double? { return base.average(ofProperty: property) }
 972
 973
 974     // MARK: Sequence Support
 975
 976     /**
 977      Returns the object at the given `index`.
 978
 979      - parameter index: The index.
 980      */
 981     public subscript(position: Int) -> Element { return base[position] }
 982
 983     /// Returns a `RLMIterator` that yields successive elements in the collection.
 984     public func makeIterator() -> RLMIterator<Element> { return base.makeIterator() }
 985
 986
 987     // MARK: Collection Support
 988
 989     /// The position of the first element in a non-empty collection.
 990     /// Identical to endIndex in an empty collection.
 991     public var startIndex: Int { return base.startIndex }
 992
 993     /// The collection's "past the end" position.
 994     /// endIndex is not a valid argument to subscript, and is always reachable from startIndex by
 995     /// zero or more applications of successor().
 996     public var endIndex: Int { return base.endIndex }
 997
 998
 999     // MARK: Key-Value Coding
1000
1001     /**
1002      Returns an `Array` containing the results of invoking `valueForKey(_:)` with `key` on each of the collection's
1003      objects.
1004
1005      - parameter key: The name of the property whose values are desired.
1006      */
1007     public func value(forKey key: String) -> Any? { return base.value(forKey: key) }
1008
1009     /**
1010      Returns an `Array` containing the results of invoking `valueForKeyPath(_:)` with `keyPath` on each of the
1011      collection's objects.
1012
1013      - parameter keyPath: The key path to the property whose values are desired.
1014      */
1015     public func value(forKeyPath keyPath: String) -> Any? { return base.value(forKeyPath: keyPath) }
1016
1017     /**
1018      Invokes `setValue(_:forKey:)` on each of the collection's objects using the specified `value` and `key`.
1019
1020      - warning: This method may only be called during a write transaction.
1021
1022      - parameter value: The value to set the property to.
1023      - parameter key:   The name of the property whose value should be set on each object.
1024      */
1025     public func setValue(_ value: Any?, forKey key: String) { base.setValue(value, forKey: key) }
1026
1027     // MARK: Notifications
1028
1029     /**
1030      Registers a block to be called each time the collection changes.
1031
1032      The block will be asynchronously called with the initial results, and then called again after each write
1033      transaction which changes either any of the objects in the collection, or which objects are in the collection.
1034
1035      The `change` parameter that is passed to the block reports, in the form of indices within the collection, which of
1036      the objects were added, removed, or modified during each write transaction. See the `RealmCollectionChange`
1037      documentation for more information on the change information supplied and an example of how to use it to update a
1038      `UITableView`.
1039
1040      At the time when the block is called, the collection will be fully evaluated and up-to-date, and as long as you do
1041      not perform a write transaction on the same thread or explicitly call `realm.refresh()`, accessing it will never
1042      perform blocking work.
1043
1044      Notifications are delivered via the standard run loop, and so can't be delivered while the run loop is blocked by
1045      other activity. When notifications can't be delivered instantly, multiple notifications may be coalesced into a
1046      single notification. This can include the notification with the initial collection.
1047
1048      For example, the following code performs a write transaction immediately after adding the notification block, so
1049      there is no opportunity for the initial notification to be delivered first. As a result, the initial notification
1050      will reflect the state of the Realm after the write transaction.
1051
1052      ```swift
1053      let results = realm.objects(Dog.self)
1054      print("dogs.count: \(dogs?.count)") // => 0
1055      let token = dogs.observe { changes in
1056          switch changes {
1057          case .initial(let dogs):
1058              // Will print "dogs.count: 1"
1059              print("dogs.count: \(dogs.count)")
1060              break
1061          case .update:
1062              // Will not be hit in this example
1063              break
1064          case .error:
1065              break
1066          }
1067      }
1068      try! realm.write {
1069          let dog = Dog()
1070          dog.name = "Rex"
1071          person.dogs.append(dog)
1072      }
1073      // end of run loop execution context
1074      ```
1075
1076      You must retain the returned token for as long as you want updates to be sent to the block. To stop receiving
1077      updates, call `invalidate()` on the token.
1078
1079      - warning: This method cannot be called during a write transaction, or when the containing Realm is read-only.
1080
1081      - parameter block: The block to be called whenever a change occurs.
1082      - returns: A token which must be held for as long as you want updates to be delivered.
1083      */
1084     public func observe(_ block: @escaping (RealmCollectionChange<AnyRealmCollection>) -> Void)
1085         -> NotificationToken { return base._observe(block) }
1086
1087     /// :nodoc:
1088     public func _observe(_ block: @escaping (RealmCollectionChange<AnyRealmCollection>) -> Void)
1089         -> NotificationToken { return base._observe(block) }
1090 }
1091
1092 // MARK: AssistedObjectiveCBridgeable
1093
1094 private struct AnyRealmCollectionBridgingMetadata<T: RealmCollectionValue> {
1095     var baseMetadata: Any?
1096     var baseType: _AnyRealmCollectionBase<T>.Type
1097 }
1098
1099 extension AnyRealmCollection: AssistedObjectiveCBridgeable {
1100     static func bridging(from objectiveCValue: Any, with metadata: Any?) -> AnyRealmCollection {
1101         guard let metadata = metadata as? AnyRealmCollectionBridgingMetadata<Element> else { preconditionFailure() }
1102         return AnyRealmCollection(base: metadata.baseType.bridging(from: objectiveCValue, with: metadata.baseMetadata))
1103     }
1104
1105     var bridged: (objectiveCValue: Any, metadata: Any?) {
1106         return (
1107             objectiveCValue: base.bridged.objectiveCValue,
1108             metadata: AnyRealmCollectionBridgingMetadata(baseMetadata: base.bridged.metadata, baseType: type(of: base))
1109         )
1110     }
1111 }
1112
1113 // MARK: Unavailable
1114
1115 extension RealmCollection {
1116     @available(*, unavailable, renamed: "sorted(byKeyPath:ascending:)")
1117     func sorted(byProperty property: String, ascending: Bool) -> Results<ElementType> { fatalError() }
1118
1119     @available(*, unavailable, renamed: "observe(_:)")
1120     public func addNotificationBlock(_ block: @escaping (RealmCollectionChange<Self>) -> Void) -> NotificationToken {
1121         fatalError()
1122     }
1123 }