0.9.2

Author: greenrobot

CHANGELOG.md

@@ -1,12 +1,17 @@
+0.9.2 (2020-06-30)
+------------------
+* Rename obx_cursor_ts_limits() to obx_cursor_ts_min_max()
+* Add C++ APIs for query links and TS min/max
+
 0.9.1 (2020-06-23)
 ------------------
 * C++ interface improvements:
-  * "Box::getOptional()" overloads returning std::optional
-  * "Box::put()" overloads taking vectors of std::unique_ptr and std::optional
+  * Box::getOptional() overloads returning std::optional
+  * Box::put() overloads taking vectors of std::unique_ptr and std::optional
   * Query methods: find(), findIds(), count(), remove(), ...
   * Ensure double-free can't happen (added explicit copy & move constructors)
 * Fixed Windows exported symbols - recently added APIs were missing
-* New "obx_cursor_put_object4()" overload taking PutMode as an argument
+* New obx_cursor_put_object4() to allow passing a PutMode
 * Make *_close() functions consistently accept nullptr 
 
 0.9.0 (2020-06-18)

README.md

@@ -3,7 +3,7 @@ ObjectBox C and C++ APIs
 [ObjectBox](https://objectbox.io) is a superfast database for objects.
 This is the **ObjectBox runtime library** to run ObjectBox as an embedded database in your C or C++ application.
 
-**Latest version: 0.9.1** (2020-06-23). See [changelog](CHANGELOG.md) for more details. 
+**Latest version: 0.9.2** (2020-06-30). See [changelog](CHANGELOG.md) for more details. 
 
 In most cases you want to use the C and C++ APIs in combination with the **companion project [ObjectBox Generator](https://github.com/objectbox/objectbox-generator)**.
 Like this, you get a convenient API which requires minimal code on your side to work with the database.

download.sh

@@ -39,7 +39,7 @@ tty -s || quiet=true
 
 # Note: optional arguments like "--quiet" shifts argument positions in the case block above
 
-version=${1:-0.9.1}
+version=${1:-0.9.2}
 repoType=${2:-testing}
 os=${3:-$(uname)}
 arch=${4:-$(uname -m)}

doxygen/Changelog.md

@@ -3,15 +3,20 @@
 ObjectBox C API Changelog
 =========================
 
+0.9.2 (2020-06-30)
+------------------
+* Rename obx_cursor_ts_limits() to obx_cursor_ts_min_max()
+* Add C++ APIs for query links and TS min/max
+
 0.9.1 (2020-06-23)
 ------------------
 * C++ interface improvements:
-  * "Box::getOptional()" overloads returning std::optional
-  * "Box::put()" overloads taking vectors of std::unique_ptr and std::optional
+  * Box::getOptional() overloads returning std::optional
+  * Box::put() overloads taking vectors of std::unique_ptr and std::optional
   * Query methods: find(), findIds(), count(), remove(), ...
   * Ensure double-free can't happen (added explicit copy & move constructors)
 * Fixed Windows exported symbols - recently added APIs were missing
-* New "obx_cursor_put_object4()"
+* New obx_cursor_put_object4() to allow passing a PutMode
 * Make *_close() functions consistently accept nullptr 
 
 0.9.0 (2020-06-18)

doxygen/Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = "ObjectBox C API"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "0.9.1"
+PROJECT_NUMBER         = "0.9.2"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

include/objectbox-cpp.h

@@ -315,6 +315,55 @@ class QueryBuilder {
 
     OBX_query_builder* cPtr() const { return cQueryBuilder_; }
 
+    /// Links the (time series) entity type to another entity space using a time point or range defined in the given
+    /// linked entity type and properties.
+    /// Note: time series functionality (ObjectBox TS) must be available to use this.
+    /// @param linkedEntityId Entity type that defines a time point or range
+    /// @param beginPropertyId Property of the linked entity defining a time point or the begin of a time range.
+    ///        Must be a date type (e.g. PropertyType_Date or PropertyType_DateNano).
+    /// @param endPropertyId Optional property of the linked entity defining the end of a time range.
+    ///        Pass zero to only define a time point (begin_property_id).
+    ///        Must be a date type (e.g. PropertyType_Date or PropertyType_DateNano).
+    template <typename ENTITY_LINKED>
+    QueryBuilder<ENTITY_LINKED> linkTime(obx_schema_id linkedEntityId, obx_schema_id beginPropertyId,
+                                         obx_schema_id endPropertyId = 0) {
+        OBX_query_builder* cQB = obx_qb_link_time(cPtr(), linkedEntityId, beginPropertyId, endPropertyId);
+        checkPtrOrThrow(cQB, "can't build a query link");
+        return QueryBuilder<ENTITY_LINKED>(store_, cQB);
+    }
+
+    /// Create a link based on a property-relation (many-to-one)
+    template <typename ENTITY_LINKED>
+    QueryBuilder<ENTITY_LINKED> linkRelationProperty(obx_schema_id relationPropertyId) {
+        OBX_query_builder* cQB = obx_qb_link_property(cPtr(), relationPropertyId);
+        checkPtrOrThrow(cQB, "can't build a query link");
+        return QueryBuilder<ENTITY_LINKED>(store_, cQB);
+    }
+
+    /// Create a backlink based on a property-relation used in reverse (one-to-many)
+    template <typename ENTITY_LINKED>
+    QueryBuilder<ENTITY_LINKED> backlinkRelationProperty(obx_schema_id sourceEntityId, obx_schema_id sourcePropertyId) {
+        OBX_query_builder* cQB = obx_qb_backlink_property(cPtr(), sourceEntityId, sourcePropertyId);
+        checkPtrOrThrow(cQB, "can't build a query link");
+        return QueryBuilder<ENTITY_LINKED>(store_, cQB);
+    }
+
+    /// Create a link based on a standalone relation (many-to-many)
+    template <typename ENTITY_LINKED>
+    QueryBuilder<ENTITY_LINKED> linkRelationStandalone(obx_schema_id relationId) {
+        OBX_query_builder* cQB = obx_qb_link_standalone(cPtr(), relationId);
+        checkPtrOrThrow(cQB, "can't build a query link");
+        return QueryBuilder<ENTITY_LINKED>(store_, cQB);
+    }
+
+    /// Create a backlink based on a standalone relation (many-to-many, reverse direction)
+    template <typename ENTITY_LINKED>
+    QueryBuilder<ENTITY_LINKED> backlinkRelationStandalone(obx_schema_id relationId) {
+        OBX_query_builder* cQB = obx_qb_backlink_standalone(cPtr(), relationId);
+        checkPtrOrThrow(cQB, "can't build a query link");
+        return QueryBuilder<ENTITY_LINKED>(store_, cQB);
+    }
+
     Query<EntityT> build();
 };
 
@@ -700,11 +749,36 @@ class Box {
     /// @param relationId ID of a standalone relation, whose source type matches this Box
     /// @param objectId object ID of the relation target 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
     std::vector<obx_id> standaloneRelBacklinkIds(obx_schema_id relationId, obx_id objectId) {
         return idVectorOrThrow(obx_box_rel_get_backlink_ids(cBox_, relationId, objectId));
     }
 
+    /// Time series: get the limits (min/max time values) over all objects
+    /// @param outMinId pointer to receive an output (may be nullptr)
+    /// @param outMinValue pointer to receive an output (may be nullptr)
+    /// @param outMaxId pointer to receive an output (may be nullptr)
+    /// @param outMaxValue pointer to receive an output (may be nullptr)
+    /// @returns true if objects were found (IDs/values are available)
+    bool timeSeriesMinMax(obx_id* outMinId, int64_t* outMinValue, obx_id* outMaxId, int64_t* outMaxValue) {
+        CursorTx cursorTx(TxMode::READ, store_, EntityBinding::entityId());
+        obx_err err = obx_cursor_ts_min_max(cursorTx.cPtr(), outMinId, outMinValue, outMaxId, outMaxValue);
+        if (err == OBX_SUCCESS) return true;
+        if (err == OBX_NOT_FOUND) return false;
+        throwLastError();
+    }
+
+    /// 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)
+    bool timeSeriesMinMax(int64_t rangeBegin, int64_t rangeEnd, obx_id* outMinId, int64_t* outMinValue,
+                          obx_id* outMaxId, int64_t* outMaxValue) {
+        CursorTx cursorTx(TxMode::READ, store_, EntityBinding::entityId());
+        obx_err err = obx_cursor_ts_min_max_range(cursorTx.cPtr(), rangeBegin, rangeEnd, outMinId, outMinValue,
+                                                  outMaxId, outMaxValue);
+        if (err == OBX_SUCCESS) return true;
+        if (err == OBX_NOT_FOUND) return false;
+        throwLastError();
+    }
+
 private:
     template <typename Vector>
     void putMany(Vector& objects, std::vector<obx_id>* outIds, OBXPutMode mode) {

include/objectbox.h

@@ -42,7 +42,7 @@ extern "C" {
 /// obx_version() or obx_version_is_at_least().
 #define OBX_VERSION_MAJOR 0
 #define OBX_VERSION_MINOR 9
-#define OBX_VERSION_PATCH 1  // values >= 100 are reserved for dev releases leading to the next minor/major increase
+#define OBX_VERSION_PATCH 2  // values >= 100 are reserved for dev releases leading to the next minor/major increase
 
 //----------------------------------------------
 // Common types
@@ -616,19 +616,25 @@ OBX_id_array* obx_cursor_rel_ids(OBX_cursor* cursor, obx_schema_id relation_id,
 // Time series
 //----------------------------------------------
 
-// TODO box based functions
-// TODO is there a better name than "limit"? Maybe something about min/max or first/last (as in C++ API)?
-//      Split in obx_cursor_ts_min() and obx_cursor_ts_max()?
+// TODO box based functions? (already available in C++ obx::Box)
 
 /// Time series: get the limits (min/max time values) over all objects
+/// @param out_min_id pointer to receive an output (may be NULL)
+/// @param out_min_value pointer to receive an output (may be NULL)
+/// @param out_max_id pointer to receive an output (may be NULL)
+/// @param out_max_value pointer to receive an output (may be NULL)
 /// @returns OBX_NOT_FOUND if no objects are stored
-obx_err obx_cursor_ts_limits(OBX_cursor* cursor, obx_id* out_begin_id, int64_t* out_begin_value, obx_id* out_end_id,
-                             int64_t* out_end_value);
+obx_err obx_cursor_ts_min_max(OBX_cursor* cursor, obx_id* out_min_id, int64_t* out_min_value, obx_id* out_max_id,
+                              int64_t* out_max_value);
 
 /// Time series: get the limits (min/max time values) over objects within the given time range
+/// @param out_min_id pointer to receive an output (may be NULL)
+/// @param out_min_value pointer to receive an output (may be NULL)
+/// @param out_max_id pointer to receive an output (may be NULL)
+/// @param out_max_value pointer to receive an output (may be NULL)
 /// @returns OBX_NOT_FOUND if no objects are stored in the given range
-obx_err obx_cursor_ts_limits_range(OBX_cursor* cursor, int64_t range_begin, int64_t range_end, obx_id* out_begin_id,
-                                   int64_t* out_begin_value, obx_id* out_end_id, int64_t* out_end_value);
+obx_err obx_cursor_ts_min_max_range(OBX_cursor* cursor, int64_t range_begin, int64_t range_end, obx_id* out_min_id,
+                                   int64_t* out_min_value, obx_id* out_max_id, int64_t* out_max_value);
 
 //----------------------------------------------
 // Box