Document how to use case sensitive conditions for String.

Also recommend using case sensitive conditions for indexed strings.

Author: greenrobot-team

objectbox-java/src/main/java/io/objectbox/query/QueryBuilder.java

@@ -22,15 +22,15 @@
 import java.util.Date;
 import java.util.List;
 
+import javax.annotation.Nullable;
+
 import io.objectbox.Box;
 import io.objectbox.EntityInfo;
 import io.objectbox.Property;
 import io.objectbox.annotation.apihint.Experimental;
 import io.objectbox.annotation.apihint.Internal;
 import io.objectbox.relation.RelationInfo;
 
-import javax.annotation.Nullable;
-
 /**
  * With QueryBuilder you define custom queries returning matching entities. Using the methods of this class you can
  * select (filter) results for specific data (for example #{@link #equal(Property, String)} and
@@ -647,42 +647,96 @@ public QueryBuilder<T> notIn(Property<T> property, int[] values) {
     //                                              String
     ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
+    /**
+     * Creates an "equal ('=')" condition for this property.
+     * <p>
+     * Ignores case when matching results, e.g. {@code equal(prop, "example")} matches both "Example" and "example".
+     * <p>
+     * Use {@link #equal(Property, String, StringOrder) equal(prop, value, StringOrder.CASE_SENSITIVE)} to only match
+     * if case is equal.
+     * <p>
+     * Note: Use a case sensitive condition to utilize an {@link io.objectbox.annotation.Index @Index}
+     * on {@code property}, dramatically speeding up look-up of results.
+     */
     public QueryBuilder<T> equal(Property<T> property, String value) {
         verifyHandle();
         checkCombineCondition(nativeEqual(handle, property.getId(), value, false));
         return this;
     }
 
+    /**
+     * Creates an "equal ('=')" condition for this property.
+     * <p>
+     * Set {@code order} to {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to only match
+     * if case is equal. E.g. {@code equal(prop, "example", StringOrder.CASE_SENSITIVE)} only matches "example",
+     * but not "Example".
+     * <p>
+     * Note: Use a case sensitive condition to utilize an {@link io.objectbox.annotation.Index @Index}
+     * on {@code property}, dramatically speeding up look-up of results.
+     */
     public QueryBuilder<T> equal(Property<T> property, String value, StringOrder order) {
         verifyHandle();
         checkCombineCondition(nativeEqual(handle, property.getId(), value, order == StringOrder.CASE_SENSITIVE));
         return this;
     }
 
+    /**
+     * Creates a "not equal ('&lt;&gt;')" condition for this property.
+     * <p>
+     * Ignores case when matching results, e.g. {@code notEqual(prop, "example")} excludes both "Example" and "example".
+     * <p>
+     * Use {@link #notEqual(Property, String, StringOrder) notEqual(prop, value, StringOrder.CASE_SENSITIVE)} to only exclude
+     * if case is equal.
+     * <p>
+     * Note: Use a case sensitive condition to utilize an {@link io.objectbox.annotation.Index @Index}
+     * on {@code property}, dramatically speeding up look-up of results.
+     */
     public QueryBuilder<T> notEqual(Property<T> property, String value) {
         verifyHandle();
         checkCombineCondition(nativeNotEqual(handle, property.getId(), value, false));
         return this;
     }
 
+    /**
+     * Creates a "not equal ('&lt;&gt;')" condition for this property.
+     * <p>
+     * Set {@code order} to {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to only exclude
+     * if case is equal. E.g. {@code notEqual(prop, "example", StringOrder.CASE_SENSITIVE)} only excludes "example",
+     * but not "Example".
+     * <p>
+     * Note: Use a case sensitive condition to utilize an {@link io.objectbox.annotation.Index @Index}
+     * on {@code property}, dramatically speeding up look-up of results.
+     */
     public QueryBuilder<T> notEqual(Property<T> property, String value, StringOrder order) {
         verifyHandle();
         checkCombineCondition(nativeNotEqual(handle, property.getId(), value, order == StringOrder.CASE_SENSITIVE));
         return this;
     }
 
+    /**
+     * Ignores case when matching results. Use the overload and pass
+     * {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to specify that case should not be ignored.
+     */
     public QueryBuilder<T> contains(Property<T> property, String value) {
         verifyHandle();
         checkCombineCondition(nativeContains(handle, property.getId(), value, false));
         return this;
     }
 
+    /**
+     * Ignores case when matching results. Use the overload and pass
+     * {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to specify that case should not be ignored.
+     */
     public QueryBuilder<T> startsWith(Property<T> property, String value) {
         verifyHandle();
         checkCombineCondition(nativeStartsWith(handle, property.getId(), value, false));
         return this;
     }
 
+    /**
+     * Ignores case when matching results. Use the overload and pass
+     * {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to specify that case should not be ignored.
+     */
     public QueryBuilder<T> endsWith(Property<T> property, String value) {
         verifyHandle();
         checkCombineCondition(nativeEndsWith(handle, property.getId(), value, false));
@@ -707,6 +761,10 @@ public QueryBuilder<T> endsWith(Property<T> property, String value, StringOrder
         return this;
     }
 
+    /**
+     * Ignores case when matching results. Use the overload and pass
+     * {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to specify that case should not be ignored.
+     */
     public QueryBuilder<T> less(Property<T> property, String value) {
         return less(property, value, StringOrder.CASE_INSENSITIVE);
     }
@@ -717,6 +775,10 @@ public QueryBuilder<T> less(Property<T> property, String value, StringOrder orde
         return this;
     }
 
+    /**
+     * Ignores case when matching results. Use the overload and pass
+     * {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to specify that case should not be ignored.
+     */
     public QueryBuilder<T> greater(Property<T> property, String value) {
         return greater(property, value, StringOrder.CASE_INSENSITIVE);
     }
@@ -727,6 +789,10 @@ public QueryBuilder<T> greater(Property<T> property, String value, StringOrder o
         return this;
     }
 
+    /**
+     * Ignores case when matching results. Use the overload and pass
+     * {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to specify that case should not be ignored.
+     */
     public QueryBuilder<T> in(Property<T> property, String[] values) {
         return in(property, values, StringOrder.CASE_INSENSITIVE);
     }