ToMany

public final class ToMany<S: EntityInspectable & __EntityRelatable>: ExpressibleByNilLiteral
where S == S.EntityBindingType.EntityType
extension ToMany: RandomAccessCollection
extension ToMany: RangeReplaceableCollection
extension ToMany: CustomStringConvertible
extension ToMany: CustomDebugStringConvertible

Declaration of a to-many relationship to objects of a certain type.

Initialize with nil in your type declarations. The code generator will set different values.

Example:

class Customer: Entity {
    var id: EntityId<Customer> = 0

    /// Annotation with ReferencedType's property name is required; Order is "ReferencedType",
    /// Customer is "OwningType"
    // objectbox: backlink = "customer"
    var orders: ToMany<Order> = nil
    // ...
}

class Order: Entity {
    var id: EntityId<Order> = 0
    var customer: ToOne<Customer> = nil
    // ...
}

Removing relations

A ToMany can be modified just like any other RangeReplaceableCollection. Once you have changed your relation as needed, call applyToDb() on it to actually write the changes to disk.

Note

You can also use a ToMany to create backlinks from ToOne relations. Use the // objectbox: backlink = "propertyName" annotation to tell the code generator which property of ToMany.ReferencedType should be used to determine the backlinks.

  • The type referenced by this relation (where we point):

    Declaration

    Swift

    public typealias ReferencedType = S

  • Indicates if the target objects have been resolved from the database yet.

    Declaration

    Swift

    public var resolved: Bool { get }

  • Undocumented

    Declaration

    Swift

    public var hasPendingDbChanges: Bool { get }

  • Initialize an empty ToMany relation.

    Use this during object creation. The actual ToMany initialization with resolvable backlinks happens in ToMany.relation(sourceBox:sourceId:targetBox:relationId:), ToMany.backlink(sourceBox:sourceProperty:targetId:) etc. which are called by the code generator.

    Declaration

    Swift

    public init(nilLiteral: ())

  • Used by the code generator to connect a backlink to the class containing the corresponding ToOne. sourceProperty is the property on ReferencedType that will be used to search for backlinks.

    Declaration

    Swift

    public static func backlink<OwningType>(sourceBox: Box<ReferencedType>,
                                        sourceProperty: Property<ReferencedType, EntityId<OwningType>,
    OwningType>,
                                        targetId: EntityId<OwningType>) -> ToMany<ReferencedType>

  • Used by the code generator to associate a to-many relation with its store and the model. relationId is the ID of the standalone to-many-relation connecting the entities.

    Declaration

    Swift

    public static func relation<OwningType>(sourceId: EntityId<OwningType>,
                                        targetBox: Box<ReferencedType>,
                                        relationId: obx_schema_id) -> ToMany<ReferencedType>

  • Used by the code generator to associate a to-many backlink with its store and the model. relationId is the ID of the standalone to-many-relation connecting the entities.

    Declaration

    Swift

    public static func backlink<OwningType>(sourceBox: Box<ReferencedType>,
                                        targetId: EntityId<OwningType>,
                                        relationId: obx_schema_id) -> ToMany<ReferencedType>
    where OwningType == OwningType.EntityBindingType.EntityType

  • Discard the cached objects and any pending changes in this relation. The next time you access this relation’s entities, it will re-load the current state from the database.

    Declaration

    Swift

    public func reset()

  • Apply changes made to this ToMany relation to the database (making changes persistent). If this collection contains new objects that were not persisted yet, applyToDb() will put them on-the-fly. For this to work the host object (the object owing this ToMany) must have been put before as its Id is required. Alternatively, if the host object is new itself, put the host object instead: ObjectBox will then call applyToDb() to all ToMany relations internally.

    When you modify a ToMany using Collection functions like append() or remove(), ToMany tracks these changes in memory but does not make them persistent just yet. This allows you to efficiently prepare the data. Then you can call this method to actually write to the database.

    Note: before version 1.4, manual puts for new objects were required.

    Declaration

    Swift

    public func applyToDb() throws

  • Checks the state of this ToMany if calls like applyToDb(), resolveFromDb(), getUncachedFromDb() are likely to succeed.

    Declaration

    Swift

    public var canInteractWithDb: Bool { get }

  • To ensure no error is forced when accessing elements of this ToMany, you can opt to resolve this ToMany upfront. This triggers loading the target objects with the possibility of a thrown error.

    Declaration

    Swift

    public func resolveFromDb() throws

  • Gets fresh target objects unrelated to any cached value in this ToMany. Also no cache is updated.

    Declaration

    Swift

    public func getUncachedFromDb() throws -> [ReferencedType]

  • Gets fresh target IDs unrelated to any cached value in this ToMany. Also no cache is updated.

    Declaration

    Swift

    public func getUncachedIdsFromDb() throws -> [ReferencedType.EntityBindingType.IdType]

  • Replace the entire contents of this relation with the contents of the given collection.

    Declaration

    Swift

    public func replace<C>(_ newElements: __owned C)
    where C: Collection, ReferencedType == C.Element

RandomAccessCollection

  • Declaration

    Swift

    public typealias Index = Int

  • The position of the first element in a nonempty collection.

    Declaration

    Swift

    public var startIndex: Index { get }

  • The collections “past the end” position – that is, the position one greater than the last valid subscript argument.

    Declaration

    Swift

    public var endIndex: Index { get }

  • Returns the position immediately after the given index.

    Declaration

    Swift

    public func index(after i: Index) -> Index

    Parameters

    i

    A valid index of the collection. i must be less than endIndex.

    Return Value

    The index immediately after i.

  • Returns the position immediately before the given index.

    Declaration

    Swift

    public func index(before i: Index) -> Index

    Parameters

    i

    A valid index of the collection. i must be greater than startIndex.

    Return Value

    The index immediately before i.

  • Enable accessing elements of the relation as e.g. customer[0] via array subscript operator.

    Declaration

    Swift

    public subscript(position: Index) -> ReferencedType { get }

  • Declaration

    Swift

    public convenience init()

  • Declaration

    Swift

    public func replaceSubrange<C, R>(_ subrange: R, with newElements: __owned C)
    where C: Collection, R: RangeExpression, ReferencedType == C.Element, Index == R.Bound

  • Declaration

    Swift

    public func removeAll(keepingCapacity keepCapacity: Bool = false)

    Parameters

    keepCapacity

    ignored in this implementation,

  • Declaration

    Swift

    public func removeAll(where shouldBeRemoved: (ReferencedType) throws -> Bool) rethrows