Box

public class Box<E>
where E: Store.InspectableEntity

A box to store objects of a particular type.

Thread-safe.

  • The object type this box is managing.

    Declaration

    Swift

    public typealias EntityType = E
  • The count of all stored objects in this box.

    See count(limit:) for a variant with an upper limit.

    Declaration

    Swift

    public var count: Int { get }
  • Indicates whether there are any objects stored inside the box.

    Declaration

    Swift

    public var isEmpty: Bool { get }
  • Limits counting all objects inside the box.

    See count for a variant without an upper limit that is equivalent to count(limit: 0).

    Declaration

    Swift

    public func count(limit: Int) -> Int

    Parameters

    limit

    Maximum value to count up to, or 0 for unlimited count.

    Return Value

    The count of all stored objects in this box or the given limit, whichever is lower.

  • Puts the given object in the box (aka persisting it).

    Throws

    NSError with OBXErrorDomain for database write errors and transaction errors.

    Declaration

    Swift

    @discardableResult
    public func put(_ entity: EntityType) throws -> Id<EntityType>

    Parameters

    entity

    Object to persist.

    Return Value

    ID of the object after persistence. If entity was persisted before, it’s the same as its ID. If entity is a new object, the ID is generated.

  • Puts the given entities in a box using a single transaction.

    Throws

    NSError with OBXErrorDomain for database write errors and transaction errors.

    Declaration

    Swift

    public func put(_ entities: [EntityType]) throws

    Parameters

    entities

    Objects to persist.

  • Get the stored objects for the given ID.

    Declaration

    Swift

    public func get(_ entityId: Id<EntityType>) -> EntityType?

    Parameters

    entityId

    ID of the object.

    Return Value

    The entity, if an object with entityId was found, nil otherwise.

  • Gets entities from the box for each ID in entityIds.

    Declaration

    Swift

    public func dictionaryWithEntities(forIds entityIds: [Id<EntityType>]) -> [Id<EntityType> : Any]

    Parameters

    entityIds

    Object IDs to map to objects.

    Return Value

    Dictionary of all entityIds and the corresponding objects. Value of a key is NSNull when not found.

  • Gets all objects from the box.

    Declaration

    Swift

    public func all() -> [EntityType]

    Return Value

    All stored Objects in this Box.

  • Removes (deletes) the Object by its ID.

    Throws

    NSError with OBXErrorDomain for database write errors.

    Declaration

    Swift

    public func remove(_ entityId: Id<EntityType>) throws

    Parameters

    entityId

    ID of the object to delete.

  • Removes (deletes) the given Object.

    Throws

    NSError with OBXErrorDomain for database write errors.

    Declaration

    Swift

    public func remove(_ entity: EntityType) throws

    Parameters

    entity

    Object to delete.

  • Removes (deletes) the given objects in a single transaction.

    It is valid to pass objects here that haven’t been persisted yet.

    Throws

    NSError with OBXErrorDomain for database write errors.

    Declaration

    Swift

    @discardableResult
    public func remove(_ entities: [EntityType]) throws -> UInt64

    Parameters

    entities

    Objects to delete.

    Return Value

    Count of objects that were removed.

  • Removes (deletes) all objects in a single transaction.

    Throws

    NSError with OBXErrorDomain for database write errors.

    Declaration

    Swift

    @discardableResult
    open func removeAll() throws -> UInt64

    Return Value

    Count of items that were removed.

  • Create a blank query you can configure afterwards.

    Declaration

    Swift

    public func query() -> Query<EntityType>

    Return Value

    Blank query.

  • Create a query with initial conditions expressed inside the block.

    To create an object of the expected return type QueryCondition, you can use comparison operators on the Property metadata object of your entity. Combine multiple conditions with boolean operators. See the type declaration of Property for a list of methods.

    Example:

    class Person: Entity {
        var name: String
        var age: Int
    
        // Code generator creates:
        //
        //     static var name: Property<Person, String>
        //     static var age: Property<Person, Int>
    }
    
    let personBox: Box<Person>
    let query = personBox.query { Person.name.startsWith("M") && Person.age >= 18 }
    

    Operators you might be interested in:

    • Boolean: && and ||
    • Containment: and
    • Equality: == and !=
    • Comparison: < and >

    Number-based properties also offer methods like isBetween, while String-based properties offer startsWith and contains.

    The list of supported operations for each Property<EntityType, ValueType> depends on the ValueType; you can explore Xcode’s auto-completion or refer to our guide at https://objectbox.io.

    Declaration

    Swift

    public func query(_ conditions: () -> QueryCondition<EntityType>) -> Query<EntityType>