ObjectBox C and C++ API  0.12.0
obx::Box< EntityT > Class Template Reference

#include <objectbox.hpp>

Public Member Functions

 Box (Store &store)
 
OBX_boxcPtr () const
 
AsyncBox< EntityT > async ()
 Async operations are available through the AsyncBox class. More...
 
QueryBuilder< EntityT > query ()
 Start building a query this entity. More...
 
QueryBuilder< EntityT > query (const QueryCondition &condition)
 Start building a query this entity. More...
 
uint64_t count (uint64_t limit=0)
 Return the number of objects contained by this box. More...
 
bool isEmpty ()
 Returns true if the box contains no objects. More...
 
bool contains (obx_id id)
 Checks whether this box contains an object with the given ID. More...
 
bool contains (const std::vector< obx_id > &ids)
 Checks whether this box contains all objects matching the given IDs. More...
 
std::unique_ptr< EntityT > get (obx_id id)
 Read an object from the database, returning a managed pointer. More...
 
bool get (obx_id id, EntityT &outObject)
 Read an object from the database, replacing the contents of an existing object variable. More...
 
std::vector< std::unique_ptr< EntityT > > get (const std::vector< obx_id > &ids)
 Read multiple objects at once, i.e. in a single read transaction. More...
 
std::vector< std::unique_ptr< EntityT > > getAll ()
 Read all objects from the Box at once, i.e. in a single read transaction. More...
 
obx_id put (EntityT &object, OBXPutMode mode=OBXPutMode_PUT)
 Inserts or updates the given object in the database. More...
 
obx_id put (const EntityT &object, OBXPutMode mode=OBXPutMode_PUT)
 Inserts or updates the given object in the database. More...
 
size_t put (std::vector< EntityT > &objects, std::vector< obx_id > *outIds=nullptr, OBXPutMode mode=OBXPutMode_PUT)
 Puts multiple objects using a single transaction. In case there was an error the transaction is rolled back and none of the changes are persisted. More...
 
size_t put (const std::vector< EntityT > &objects, std::vector< obx_id > *outIds=nullptr, OBXPutMode mode=OBXPutMode_PUT)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
size_t put (std::vector< std::unique_ptr< EntityT >> &objects, std::vector< obx_id > *outIds=nullptr, OBXPutMode mode=OBXPutMode_PUT)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
bool remove (obx_id id)
 Remove the object with the given id. More...
 
uint64_t remove (const std::vector< obx_id > &ids)
 Removes all objects matching the given IDs. More...
 
uint64_t removeAll ()
 Removes all objects from the box. More...
 
template<typename SourceEntityT , typename TargetEntityT >
std::vector< obx_idbacklinkIds (RelationProperty< SourceEntityT, TargetEntityT > toOneRel, obx_id objectId)
 
template<typename SourceEntityT , typename TargetEntityT >
void standaloneRelReplace (RelationStandalone< SourceEntityT, TargetEntityT > toManyRel, obx_id sourceObjectId, const std::vector< obx_id > &targetObjectIds)
 Replace the list of standalone relation target objects on the given source object. More...
 
template<typename TargetEntityT >
void standaloneRelPut (RelationStandalone< EntityT, TargetEntityT > toManyRel, obx_id sourceObjectId, obx_id targetObjectId)
 Insert a standalone relation entry between two objects. More...
 
template<typename TargetEntityT >
void standaloneRelRemove (RelationStandalone< EntityT, TargetEntityT > toManyRel, obx_id sourceObjectId, obx_id targetObjectId)
 Remove a standalone relation entry between two objects. More...
 
template<typename SourceEntityT >
std::vector< obx_idstandaloneRelIds (RelationStandalone< SourceEntityT, EntityT > toManyRel, obx_id objectId)
 Fetch IDs of all objects in this Box related to the given object (typically from another Box). Used for a stand-alone relation and its "regular" direction; this Box represents the target of the relation. More...
 
template<typename TargetEntityT >
std::vector< obx_idstandaloneRelBacklinkIds (RelationStandalone< EntityT, TargetEntityT > toManyRel, obx_id objectId)
 Fetch IDs of all objects in this Box related to the given object (typically from another Box). Used for a stand-alone relation and its "backlink" direction; this Box represents the source of the relation. More...
 
bool timeSeriesMinMax (obx_id *outMinId, int64_t *outMinValue, obx_id *outMaxId, int64_t *outMaxValue)
 Time series: get the limits (min/max time values) over all objects. More...
 
bool timeSeriesMinMax (int64_t rangeBegin, int64_t rangeEnd, obx_id *outMinId, int64_t *outMinValue, obx_id *outMaxId, int64_t *outMaxValue)
 Time series: get the limits (min/max time values) over objects within the given time range. More...
 

Constructor & Destructor Documentation

◆ Box()

template<typename EntityT >
obx::Box< EntityT >::Box ( Store store)
inlineexplicit

Member Function Documentation

◆ async()

template<typename EntityT >
AsyncBox<EntityT> obx::Box< EntityT >::async ( )
inline

Async operations are available through the AsyncBox class.

Returns
a shared AsyncBox instance with the default timeout (1s) for enqueueing. Note: while this looks like it creates a new instance, it's only a thin wrapper and the actual ObjectBox core internal async box really is shared.
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ backlinkIds()

template<typename EntityT >
template<typename SourceEntityT , typename TargetEntityT >
std::vector<obx_id> obx::Box< EntityT >::backlinkIds ( RelationProperty< SourceEntityT, TargetEntityT >  toOneRel,
obx_id  objectId 
)
inline

◆ contains() [1/2]

template<typename EntityT >
bool obx::Box< EntityT >::contains ( const std::vector< obx_id > &  ids)
inline

Checks whether this box contains all objects matching the given IDs.

◆ contains() [2/2]

template<typename EntityT >
bool obx::Box< EntityT >::contains ( obx_id  id)
inline

Checks whether this box contains an object with the given ID.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ count()

template<typename EntityT >
uint64_t obx::Box< EntityT >::count ( uint64_t  limit = 0)
inline

Return the number of objects contained by this box.

Parameters
limitif provided: stop counting at the given limit - useful if you need to make sure the Box has "at least" this many objects but you don't need to know the exact number.
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ cPtr()

template<typename EntityT >
OBX_box* obx::Box< EntityT >::cPtr ( ) const
inline

◆ get() [1/3]

template<typename EntityT >
std::vector<std::unique_ptr<EntityT> > obx::Box< EntityT >::get ( const std::vector< obx_id > &  ids)
inline

Read multiple objects at once, i.e. in a single read transaction.

Returns
a vector of object pointers index-matching the given ids. In case some objects are not found, it's position in the result will be NULL, thus the result will always have the same size as the given ids argument.

◆ get() [2/3]

template<typename EntityT >
std::unique_ptr<EntityT> obx::Box< EntityT >::get ( obx_id  id)
inline

Read an object from the database, returning a managed pointer.

Returns
an object pointer or nullptr if an object with the given ID doesn't exist.
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ get() [3/3]

template<typename EntityT >
bool obx::Box< EntityT >::get ( obx_id  id,
EntityT &  outObject 
)
inline

Read an object from the database, replacing the contents of an existing object variable.

Returns
true on success, false if the ID was not found, in which case outObject is untouched.

◆ getAll()

template<typename EntityT >
std::vector<std::unique_ptr<EntityT> > obx::Box< EntityT >::getAll ( )
inline

Read all objects from the Box at once, i.e. in a single read transaction.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ isEmpty()

template<typename EntityT >
bool obx::Box< EntityT >::isEmpty ( )
inline

Returns true if the box contains no objects.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ put() [1/5]

template<typename EntityT >
obx_id obx::Box< EntityT >::put ( const EntityT &  object,
OBXPutMode  mode = OBXPutMode_PUT 
)
inline

Inserts or updates the given object in the database.

Returns
newly assigned object ID in case this was an insert, otherwise the original ID from the object param.

◆ put() [2/5]

template<typename EntityT >
size_t obx::Box< EntityT >::put ( const std::vector< EntityT > &  objects,
std::vector< obx_id > *  outIds = nullptr,
OBXPutMode  mode = OBXPutMode_PUT 
)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns
the number of put elements (always equal to objects.size() for this overload)

◆ put() [3/5]

template<typename EntityT >
obx_id obx::Box< EntityT >::put ( EntityT &  object,
OBXPutMode  mode = OBXPutMode_PUT 
)
inline

Inserts or updates the given object in the database.

Parameters
objectwill be updated with a newly inserted ID if the one specified previously was zero. If an ID was already specified (non-zero), it will remain unchanged.
Returns
object ID from the object param (see object param docs).
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ put() [4/5]

template<typename EntityT >
size_t obx::Box< EntityT >::put ( std::vector< EntityT > &  objects,
std::vector< obx_id > *  outIds = nullptr,
OBXPutMode  mode = OBXPutMode_PUT 
)
inline

Puts multiple objects using a single transaction. In case there was an error the transaction is rolled back and none of the changes are persisted.

Parameters
objectsobjects to insert (if their IDs are zero) or update. ID properties on the newly inserted objects will be updated. If the transaction fails, the assigned IDs on the given objects will be incorrect.
outIdsmay be provided to collect IDs from the objects. This collects not only new IDs assigned after an insert but also existing IDs if an object isn't new but updated instead. Thus, the outIds vector will always end up with the same number of items as objects argument, with indexes corresponding between the two. Note: outIds content is reset before executing to make sure the indexes match the objects argument even if outIds is reused between multiple calls.
Exceptions
revertsthe changes if an error occurs.
Returns
the number of put elements (always equal to objects.size() for this overload)

◆ put() [5/5]

template<typename EntityT >
size_t obx::Box< EntityT >::put ( std::vector< std::unique_ptr< EntityT >> &  objects,
std::vector< obx_id > *  outIds = nullptr,
OBXPutMode  mode = OBXPutMode_PUT 
)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns
the number of put elements, i.e. the number of std::unique_ptr != nullptr

◆ query() [1/2]

template<typename EntityT >
QueryBuilder<EntityT> obx::Box< EntityT >::query ( )
inline

Start building a query this entity.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ query() [2/2]

template<typename EntityT >
QueryBuilder<EntityT> obx::Box< EntityT >::query ( const QueryCondition &  condition)
inline

Start building a query this entity.

◆ remove() [1/2]

template<typename EntityT >
uint64_t obx::Box< EntityT >::remove ( const std::vector< obx_id > &  ids)
inline

Removes all objects matching the given IDs.

Returns
number of removed objects between 0 and ids.size() (if all IDs existed)

◆ remove() [2/2]

template<typename EntityT >
bool obx::Box< EntityT >::remove ( obx_id  id)
inline

Remove the object with the given id.

Returns
whether the object was removed or not (because it didn't exist)
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ removeAll()

template<typename EntityT >
uint64_t obx::Box< EntityT >::removeAll ( )
inline

Removes all objects from the box.

Returns
the number of removed objects
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ standaloneRelBacklinkIds()

template<typename EntityT >
template<typename TargetEntityT >
std::vector<obx_id> obx::Box< EntityT >::standaloneRelBacklinkIds ( RelationStandalone< EntityT, TargetEntityT >  toManyRel,
obx_id  objectId 
)
inline

Fetch IDs of all objects in this Box related to the given object (typically from another Box). Used for a stand-alone relation and its "backlink" direction; this Box represents the source of the relation.

Parameters
relationIdID of a standalone relation, whose source type matches this Box
objectIdobject ID of the relation target type (typically from another Box)
Returns
resulting IDs representing objects in this Box
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ standaloneRelIds()

template<typename EntityT >
template<typename SourceEntityT >
std::vector<obx_id> obx::Box< EntityT >::standaloneRelIds ( RelationStandalone< SourceEntityT, EntityT >  toManyRel,
obx_id  objectId 
)
inline

Fetch IDs of all objects in this Box related to the given object (typically from another Box). Used for a stand-alone relation and its "regular" direction; this Box represents the target of the relation.

Parameters
relationIdID of a standalone relation, whose target type matches this Box
objectIdobject ID of the relation source type (typically from another Box)
Returns
resulting IDs representing objects in this Box
Todo:
improve docs by providing an example with a clear distinction between source and target type
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ standaloneRelPut()

template<typename EntityT >
template<typename TargetEntityT >
void obx::Box< EntityT >::standaloneRelPut ( RelationStandalone< EntityT, TargetEntityT >  toManyRel,
obx_id  sourceObjectId,
obx_id  targetObjectId 
)
inline

Insert a standalone relation entry between two objects.

Parameters
toManyRelmust be a standalone relation ID with source object entity belonging to this box
sourceObjectIdidentifies an object from this box
targetObjectIdidentifies an object from a target box (as per the relation definition)
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ standaloneRelRemove()

template<typename EntityT >
template<typename TargetEntityT >
void obx::Box< EntityT >::standaloneRelRemove ( RelationStandalone< EntityT, TargetEntityT >  toManyRel,
obx_id  sourceObjectId,
obx_id  targetObjectId 
)
inline

Remove a standalone relation entry between two objects.

Parameters
toManyRelmust be a standalone relation ID with source object entity belonging to this box
sourceObjectIdidentifies an object from this box
targetObjectIdidentifies an object from a target box (as per the relation definition)
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ standaloneRelReplace()

template<typename EntityT >
template<typename SourceEntityT , typename TargetEntityT >
void obx::Box< EntityT >::standaloneRelReplace ( RelationStandalone< SourceEntityT, TargetEntityT >  toManyRel,
obx_id  sourceObjectId,
const std::vector< obx_id > &  targetObjectIds 
)
inline

Replace the list of standalone relation target objects on the given source object.

Parameters
toManyRelmust be a standalone relation ID with source object entity belonging to this box
sourceObjectIdidentifies an object from this box
targetObjectIdsidentifies objects from a target box (as per the relation definition)
Todo:
consider providing a method similar to the one in Go - inserting target objects with 0 IDs
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ timeSeriesMinMax() [1/2]

template<typename EntityT >
bool obx::Box< EntityT >::timeSeriesMinMax ( int64_t  rangeBegin,
int64_t  rangeEnd,
obx_id outMinId,
int64_t *  outMinValue,
obx_id outMaxId,
int64_t *  outMaxValue 
)
inline

Time series: get the limits (min/max time values) over objects within the given time range.

Returns
true if objects were found in the given range (IDs/values are available)

◆ timeSeriesMinMax() [2/2]

template<typename EntityT >
bool obx::Box< EntityT >::timeSeriesMinMax ( obx_id outMinId,
int64_t *  outMinValue,
obx_id outMaxId,
int64_t *  outMaxValue 
)
inline

Time series: get the limits (min/max time values) over all objects.

Parameters
outMinIdpointer to receive an output (may be nullptr)
outMinValuepointer to receive an output (may be nullptr)
outMaxIdpointer to receive an output (may be nullptr)
outMaxValuepointer to receive an output (may be nullptr)
Returns
true if objects were found (IDs/values are available)
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.