Skip to content

Commit 50918aa

Browse files
greenrobot-teamgreenrobot-team
committed
Document how to use case sensitive conditions for String properties.
1 parent 08c746c commit 50918aa

1 file changed

Lines changed: 96 additions & 10 deletions

File tree

‎objectbox-java/src/main/java/io/objectbox/Property.java‎

Lines changed: 96 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -218,46 +218,111 @@ public PropertyQueryCondition<ENTITY> between(Date lowerBoundary, Date upperBoun
218218
return new LongLongCondition<>(this, LongLongCondition.Operation.BETWEEN, lowerBoundary, upperBoundary);
219219
}
220220

221-
/** Creates an "equal ('=')" condition for this property. */
221+
/**
222+
* Creates an "equal ('=')" condition for this property.
223+
* <p>
224+
* Ignores case when matching results, e.g. {@code equal("example")} matches both "Example" and "example".
225+
* <p>
226+
* Use {@link #equal(String, StringOrder) equal(value, StringOrder.CASE_SENSITIVE)} to only match if case is equal.
227+
* <p>
228+
* Note: Use a case sensitive condition to utilize an {@link io.objectbox.annotation.Index @Index}
229+
* on {@code property}, dramatically speeding up look-up of results.
230+
*
231+
* @see #equal(String, StringOrder)
232+
*/
222233
public PropertyQueryCondition<ENTITY> equal(String value) {
223234
return new StringCondition<>(this, StringCondition.Operation.EQUAL, value);
224235
}
225236

226-
/** Creates an "equal ('=')" condition for this property. */
237+
/**
238+
* Creates an "equal ('=')" condition for this property.
239+
* <p>
240+
* Set {@code order} to {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to only match
241+
* if case is equal. E.g. {@code equal("example", StringOrder.CASE_SENSITIVE)} only matches "example",
242+
* but not "Example".
243+
* <p>
244+
* Note: Use a case sensitive condition to utilize an {@link io.objectbox.annotation.Index @Index}
245+
* on {@code property}, dramatically speeding up look-up of results.
246+
*/
227247
public PropertyQueryCondition<ENTITY> equal(String value, StringOrder order) {
228248
return new StringCondition<>(this, StringCondition.Operation.EQUAL, value, order);
229249
}
230250

231-
/** Creates a "not equal ('&lt;&gt;')" condition for this property. */
251+
/**
252+
* Creates a "not equal ('&lt;&gt;')" condition for this property.
253+
* <p>
254+
* Ignores case when matching results, e.g. {@code notEqual("example")} excludes both "Example" and "example".
255+
* <p>
256+
* Use {@link #notEqual(String, StringOrder) notEqual(value, StringOrder.CASE_SENSITIVE)} to only exclude
257+
* if case is equal.
258+
* <p>
259+
* Note: Use a case sensitive condition to utilize an {@link io.objectbox.annotation.Index @Index}
260+
* on {@code property}, dramatically speeding up look-up of results.
261+
*
262+
* @see #notEqual(String, StringOrder)
263+
*/
232264
public PropertyQueryCondition<ENTITY> notEqual(String value) {
233265
return new StringCondition<>(this, StringCondition.Operation.NOT_EQUAL, value);
234266
}
235267

236-
/** Creates a "not equal ('&lt;&gt;')" condition for this property. */
268+
/**
269+
* Creates a "not equal ('&lt;&gt;')" condition for this property.
270+
* <p>
271+
* Set {@code order} to {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to only exclude
272+
* if case is equal. E.g. {@code notEqual("example", StringOrder.CASE_SENSITIVE)} only excludes "example",
273+
* but not "Example".
274+
* <p>
275+
* Note: Use a case sensitive condition to utilize an {@link io.objectbox.annotation.Index @Index}
276+
* on {@code property}, dramatically speeding up look-up of results.
277+
*/
237278
public PropertyQueryCondition<ENTITY> notEqual(String value, StringOrder order) {
238279
return new StringCondition<>(this, StringCondition.Operation.NOT_EQUAL, value, order);
239280
}
240281

241-
/** Creates a "greater than ('&gt;')" condition for this property. */
282+
/**
283+
* Creates a "greater than ('&gt;')" condition for this property.
284+
* <p>
285+
* Ignores case when matching results. Use the overload and pass
286+
* {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to specify that case should not be ignored.
287+
*
288+
* @see #greater(String, StringOrder)
289+
*/
242290
public PropertyQueryCondition<ENTITY> greater(String value) {
243291
return new StringCondition<>(this, StringCondition.Operation.GREATER, value);
244292
}
245293

246-
/** Creates a "greater than ('&gt;')" condition for this property. */
294+
/**
295+
* Creates a "greater than ('&gt;')" condition for this property.
296+
*/
247297
public PropertyQueryCondition<ENTITY> greater(String value, StringOrder order) {
248298
return new StringCondition<>(this, StringCondition.Operation.GREATER, value, order);
249299
}
250300

251-
/** Creates a "less than ('&lt;')" condition for this property. */
301+
/**
302+
* Creates a "less than ('&lt;')" condition for this property.
303+
* <p>
304+
* Ignores case when matching results. Use the overload and pass
305+
* {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to specify that case should not be ignored.
306+
*
307+
* @see #less(String, StringOrder)
308+
*/
252309
public PropertyQueryCondition<ENTITY> less(String value) {
253310
return new StringCondition<>(this, StringCondition.Operation.LESS, value);
254311
}
255312

256-
/** Creates a "less than ('&lt;')" condition for this property. */
313+
/**
314+
* Creates a "less than ('&lt;')" condition for this property.
315+
*/
257316
public PropertyQueryCondition<ENTITY> less(String value, StringOrder order) {
258317
return new StringCondition<>(this, StringCondition.Operation.LESS, value, order);
259318
}
260319

320+
/**
321+
* Ignores case when matching results. Use the overload and pass
322+
* {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to specify that case should not be ignored.
323+
*
324+
* @see #contains(String, StringOrder)
325+
*/
261326
public PropertyQueryCondition<ENTITY> contains(String value) {
262327
return new StringCondition<>(this, StringCondition.Operation.CONTAINS, value);
263328
}
@@ -266,6 +331,12 @@ public PropertyQueryCondition<ENTITY> contains(String value, StringOrder order)
266331
return new StringCondition<>(this, StringCondition.Operation.CONTAINS, value, order);
267332
}
268333

334+
/**
335+
* Ignores case when matching results. Use the overload and pass
336+
* {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to specify that case should not be ignored.
337+
*
338+
* @see #startsWith(String, StringOrder)
339+
*/
269340
public PropertyQueryCondition<ENTITY> startsWith(String value) {
270341
return new StringCondition<>(this, Operation.STARTS_WITH, value);
271342
}
@@ -274,6 +345,12 @@ public PropertyQueryCondition<ENTITY> startsWith(String value, StringOrder order
274345
return new StringCondition<>(this, Operation.STARTS_WITH, value, order);
275346
}
276347

348+
/**
349+
* Ignores case when matching results. Use the overload and pass
350+
* {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to specify that case should not be ignored.
351+
*
352+
* @see #endsWith(String, StringOrder)
353+
*/
277354
public PropertyQueryCondition<ENTITY> endsWith(String value) {
278355
return new StringCondition<>(this, Operation.ENDS_WITH, value);
279356
}
@@ -282,12 +359,21 @@ public PropertyQueryCondition<ENTITY> endsWith(String value, StringOrder order)
282359
return new StringCondition<>(this, Operation.ENDS_WITH, value, order);
283360
}
284361

285-
/** Creates an "IN (..., ..., ...)" condition for this property. */
362+
/**
363+
* Creates an "IN (..., ..., ...)" condition for this property.
364+
* <p>
365+
* Ignores case when matching results. Use the overload and pass
366+
* {@link StringOrder#CASE_SENSITIVE StringOrder.CASE_SENSITIVE} to specify that case should not be ignored.
367+
*
368+
* @see #oneOf(String[], StringOrder)
369+
*/
286370
public PropertyQueryCondition<ENTITY> oneOf(String[] values) {
287371
return new StringArrayCondition<>(this, StringArrayCondition.Operation.IN, values);
288372
}
289373

290-
/** Creates an "IN (..., ..., ...)" condition for this property. */
374+
/**
375+
* Creates an "IN (..., ..., ...)" condition for this property.
376+
*/
291377
public PropertyQueryCondition<ENTITY> oneOf(String[] values, StringOrder order) {
292378
return new StringArrayCondition<>(this, StringArrayCondition.Operation.IN, values, order);
293379
}

0 commit comments

Comments
 (0)