Merge branch 'dev' into devquid

Author: liquidiert

README.md

@@ -144,6 +144,23 @@ final overloaded = ((text == "meh") | (text == "bleh")) | text.contains("Hello")
 box.query(overloaded as Condition).build(); // the cast is necessary due to the type analyzer
 ```
 
+Ordering
+--------
+
+The results from a query can be ordered using the `order` method, e.g.
+
+```dart
+final q = box.query(Entity_.number > 0)
+  .order(Type_.number)
+  .build();
+
+// ...
+
+final qt = box.query(Entity_.text.notNull())
+  .order(Entity_.text, flags: OBXOrderFlag.DESCENDING | OBXOrderFlag.CASE_SENSITIVE)
+  .build();
+```
+
 Basic technical approach
 ------------------------
 ObjectBox offers a [C API](https://github.com/objectbox/objectbox-c) which can be called by [Dart FFI](https://dart.dev/server/c-interop).

analysis_options.yaml

@@ -1 +1,5 @@
-include: package:pedantic/analysis_options.yaml
+include: package:pedantic/analysis_options.yaml
+
+linter:
+  rules:
+    unrelated_type_equality_checks: false  # query condition operator overrides

lib/src/bindings/constants.dart

@@ -82,25 +82,4 @@ class OBXError {
 
   /// A requested schema object (e.g. entity or property) was not found in the schema
   static const int OBX_ERROR_SCHEMA_OBJECT_NOT_FOUND = 10503;
-}
-
-// query builder
-
-class OBXOrderFlag {
-  /// Reverts the order from ascending (default) to descending.
-  static final DESCENDING = 1;
-
-  /// Makes upper case letters (e.g. "Z") be sorted before lower case letters (e.g. "a").
-  /// If not specified, the default is case insensitive for ASCII characters.
-  static final CASE_SENSITIVE = 2;
-
-  /// For scalars only: changes the comparison to unsigned (default is signed).
-  static final UNSIGNED = 4;
-
-  /// null values will be put last.
-  /// If not specified, by default null values will be put first.
-  static final NULLS_LAST = 8;
-
-  /// null values should be treated equal to zero (scalars only).
-  static final NULLS_ZERO = 16;
-}
+}

lib/src/box.dart

@@ -233,12 +233,12 @@ class Box<T> {
   }
 
   int removeAll() {
-    Pointer<Uint64> removedIds = Pointer<Uint64>.allocate();
+    Pointer<Uint64> removedItems = Pointer<Uint64>.allocate();
     try {
-      checkObx(bindings.obx_box_remove_all(_cBox, removedIds));
-      return removedIds.load<int>();
+      checkObx(bindings.obx_box_remove_all(_cBox, removedItems));
+      return removedItems.load<int>();
     } finally {
-      removedIds.free();
+      removedItems.free();
     }
   }
 

lib/src/query/builder.dart

@@ -17,8 +17,10 @@ class QueryBuilder<T> {
     }
   }
 
+  _createBuilder() => _cBuilder ??= bindings.obx_qb_create(_store.ptr, _entityId);
+
   Query build() {
-    _cBuilder = bindings.obx_qb_create(_store.ptr, _entityId);
+    _createBuilder();
 
     if (0 == _queryCondition.apply(this, true)) {
       _throwExceptionIfNecessary();
@@ -30,15 +32,19 @@ class QueryBuilder<T> {
       checkObx(bindings.obx_qb_close(_cBuilder));
     }
   }
+
+  QueryBuilder<T> order(QueryProperty p, {int flags=0}) {
+    _createBuilder();
+    checkObx(bindings.obx_qb_order(_cBuilder, p._propertyId, flags));
+    return this;
+  }
 }
 
 /*  // Not done yet
     obx_qb_bytes_eq_dart_t obx_qb_bytes_equal;
     obx_qb_bytes_lt_gt_dart_t obx_qb_bytes_greater, obx_qb_bytes_less;
 
     obx_qb_param_alias_dart_t obx_qb_param_alias;
-
-    obx_qb_order_dart_t obx_qb_order;
 */
 
 //////

lib/src/query/index.dart

@@ -1 +1,20 @@
 export "query.dart";
+
+class Order {
+  /// Reverts the order from ascending (default) to descending.
+  static final descending = 1;
+
+  /// Makes upper case letters (e.g. "Z") be sorted before lower case letters (e.g. "a").
+  /// If not specified, the default is case insensitive for ASCII characters.
+  static final caseSensitive = 2;
+
+  /// For scalars only: changes the comparison to unsigned (default is signed).
+  static final unsigned = 4;
+
+  /// null values will be put last.
+  /// If not specified, by default null values will be put first.
+  static final nullsLast = 8;
+
+  /// null values should be treated equal to zero (scalars only).
+  static final nullsAsZero = 16;
+}

test/query_test.dart

@@ -356,6 +356,41 @@ void main() {
     }
   });
 
+  test(".order queryBuilder", () {
+    box.put(TestEntity.initText("World"));
+    box.put(TestEntity.initText("Hello"));
+    box.put(TestEntity.initText("HELLO"));
+    box.put(TestEntity.initText("World"));
+    box.put(TestEntity.initText("Goodbye"));
+    box.put(TestEntity.initText("Cruel"));
+    box.put(TestEntity.initInteger(1337));
+
+    final text = TestEntity_.text;
+
+    final condition = text.notNull();
+
+    final query = box.query(condition)
+      .order(text)
+      .build();
+
+    final queryWithFlags = box.query(condition)
+      .order(text, flags: Order.descending | Order.caseSensitive)
+      .build();
+
+    final result1 = query.find().map((e) => e.text).toList();
+    final result2 = queryWithFlags.find().map((e) => e.text).toList();
+
+    expect("Cruel", result1[0]);
+    expect("World", result2[0]);
+    expect("Hello", result1[2]);
+    expect("Hello", result2[2]);
+    expect("HELLO", result1[3]);
+    expect("HELLO", result2[3]);
+
+    query.close();
+    queryWithFlags.close();
+  });
+
   tearDown(() {
     env.close();
   });