All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_predexp.h
Go to the documentation of this file.
1 /*
2  * Copyright 2016-2017 Aerospike, Inc.
3  *
4  * Portions may be licensed to Aerospike, Inc. under one or more contributor
5  * license agreements.
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
8  * use this file except in compliance with the License. You may obtain a copy of
9  * the License at http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14  * License for the specific language governing permissions and limitations under
15  * the License.
16  */
17 #pragma once
18 
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 
23 struct as_predexp_base_s;
24 
25 typedef void (*as_predexp_base_dtor_fn) (struct as_predexp_base_s *);
26 typedef size_t (*as_predexp_base_size_fn) (struct as_predexp_base_s *);
27 typedef uint8_t * (*as_predexp_base_write_fn) (struct as_predexp_base_s *, uint8_t *p);
28 
29 /**
30  * Defines a predicate expression base.
31  */
32 typedef struct as_predexp_base_s {
33 
34  /**
35  * Destructor for this object.
36  */
38 
39  /**
40  * Returns serialization size of this object.
41  */
43 
44  /**
45  * Serialize this object into a command.
46  */
48 
50 
51 /**
52  * Create an AND logical predicate expression.
53  *
54  * The AND predicate expression returns true if all of its children
55  * are true.
56  *
57  * The nexpr parameter specifies how many children to pop off the
58  * expression stack. These children must be "logical" expressions
59  * and not "value" expressions.
60  *
61  * For example, the following sequence of predicate expressions
62  * selects records where the value of bin "c" is between 11 and 20
63  * inclusive:
64  *
65  * ~~~~~~~~~~{.c}
66  * as_query_predexp_inita(&q, 7);
67  * as_query_predexp_add(&q, as_predexp_integer_bin("c"));
68  * as_query_predexp_add(&q, as_predexp_integer_value(11));
69  * as_query_predexp_add(&q, as_predexp_integer_greatereq());
70  * as_query_predexp_add(&q, as_predexp_integer_bin("c"));
71  * as_query_predexp_add(&q, as_predexp_integer_value(20));
72  * as_query_predexp_add(&q, as_predexp_integer_lesseq());
73  * as_query_predexp_add(&q, as_predexp_and(2));
74  * ~~~~~~~~~~
75  *
76  * @param nexpr The number of child expressions to AND.
77  *
78  * @returns a predicate expression suitable for adding to a query or
79  * scan.
80  */
82 as_predexp_and(uint16_t nexpr);
83 
84 /**
85  * Create an OR logical predicate expression.
86  *
87  * The OR predicate expression returns true if any of its children
88  * are true.
89  *
90  * The nexpr parameter specifies how many children to pop off the
91  * expression stack. These children must be "logical" expressions
92  * and not "value" expressions.
93  *
94  * For example, the following sequence of predicate expressions
95  * selects records where the value of bin "pet" is "cat" or "dog".
96  *
97  * ~~~~~~~~~~{.c}
98  * as_query_predexp_inita(&q, 7);
99  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
100  * as_query_predexp_add(&q, as_predexp_string_bin("pet"));
101  * as_query_predexp_add(&q, as_predexp_string_equal());
102  * as_query_predexp_add(&q, as_predexp_string_value("dog"));
103  * as_query_predexp_add(&q, as_predexp_string_bin("pet"));
104  * as_query_predexp_add(&q, as_predexp_string_equal());
105  * as_query_predexp_add(&q, as_predexp_or(2));
106  * ~~~~~~~~~~
107  *
108  * @param nexpr The number of child expressions to OR.
109  *
110  * @returns a predicate expression suitable for adding to a query or
111  * scan.
112  */
114 as_predexp_or(uint16_t nexpr);
115 
116 /**
117  * Create a NOT logical predicate expression.
118  *
119  * The NOT predicate expression returns true if its child is false.
120  *
121  * The NOT expression pops a single child off the expression stack.
122  * This child must be a "logical" expression and not a "value"
123  * expression.
124  *
125  * For example, the following sequence of predicate expressions
126  * selects records where the value of bin "pet" is not "dog".
127  *
128  * ~~~~~~~~~~{.c}
129  * as_query_predexp_inita(&q, 4);
130  * as_query_predexp_add(&q, as_predexp_string_value("dog"));
131  * as_query_predexp_add(&q, as_predexp_string_bin("pet"));
132  * as_query_predexp_add(&q, as_predexp_string_equal());
133  * as_query_predexp_add(&q, as_predexp_not());
134  * ~~~~~~~~~~
135  *
136  * @returns a predicate expression suitable for adding to a query or
137  * scan.
138  */
141 
142 /**
143  * Create a constant integer value predicate expression.
144  *
145  * The integer value predicate expression pushes a single constant
146  * integer value onto the expression stack.
147  *
148  * For example, the following sequence of predicate expressions
149  * selects records where the value of bin "c" is between 11 and 20
150  * inclusive:
151  *
152  * ~~~~~~~~~~{.c}
153  * as_query_predexp_inita(&q, 7);
154  * as_query_predexp_add(&q, as_predexp_integer_bin("c"));
155  * as_query_predexp_add(&q, as_predexp_integer_value(11));
156  * as_query_predexp_add(&q, as_predexp_integer_greatereq());
157  * as_query_predexp_add(&q, as_predexp_integer_bin("c"));
158  * as_query_predexp_add(&q, as_predexp_integer_value(20));
159  * as_query_predexp_add(&q, as_predexp_integer_lesseq());
160  * as_query_predexp_add(&q, as_predexp_and(2));
161  * ~~~~~~~~~~
162  *
163  * @param value The integer value.
164  *
165  * @returns a predicate expression suitable for adding to a query or
166  * scan.
167  */
169 as_predexp_integer_value(int64_t value);
170 
171 /**
172  * Create a constant string value predicate expression.
173  *
174  * The string value predicate expression pushes a single constant
175  * string value onto the expression stack.
176  *
177  * For example, the following sequence of predicate expressions
178  * selects records where the value of bin "pet" is "cat" or "dog":
179  *
180  * ~~~~~~~~~~{.c}
181  * as_query_predexp_inita(&q, 7);
182  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
183  * as_query_predexp_add(&q, as_predexp_string_bin("pet"));
184  * as_query_predexp_add(&q, as_predexp_string_equal());
185  * as_query_predexp_add(&q, as_predexp_string_value("dog"));
186  * as_query_predexp_add(&q, as_predexp_string_bin("pet"));
187  * as_query_predexp_add(&q, as_predexp_string_equal());
188  * as_query_predexp_add(&q, as_predexp_or(2));
189  * ~~~~~~~~~~
190  *
191  * @param value The string value.
192  *
193  * @returns a predicate expression suitable for adding to a query or
194  * scan.
195  */
197 as_predexp_string_value(char const * value);
198 
199 /**
200  * Create a constant GeoJSON value predicate expression.
201  *
202  * The GeoJSON value predicate expression pushes a single constant
203  * GeoJSON value onto the expression stack.
204  *
205  * For example, the following sequence of predicate expressions
206  * selects records where a point in bin "loc" is inside the
207  * specified polygon:
208  *
209  * ~~~~~~~~~~{.c}
210  * char const * region =
211  * "{ "
212  * " \"type\": \"Polygon\", "
213  * " \"coordinates\": [ "
214  * " [[-122.500000, 37.000000],[-121.000000, 37.000000], "
215  * " [-121.000000, 38.080000],[-122.500000, 38.080000], "
216  * " [-122.500000, 37.000000]] "
217  * " ] "
218  * " } ";
219  *
220  * as_query_predexp_inita(&query, 3);
221  * as_query_predexp_add(&query, as_predexp_geojson_bin("loc"));
222  * as_query_predexp_add(&query, as_predexp_geojson_value(region));
223  * as_query_predexp_add(&query, as_predexp_geojson_within());
224  * ~~~~~~~~~~
225  *
226  * @param value The GeoJSON string value.
227  *
228  * @returns a predicate expression suitable for adding to a query or
229  * scan.
230  */
232 as_predexp_geojson_value(char const * value);
233 
234 /**
235  * Create an integer bin value predicate expression.
236  *
237  * The integer bin predicate expression pushes a single integer bin
238  * value extractor onto the expression stack.
239  *
240  * For example, the following sequence of predicate expressions
241  * selects records where the value of bin "c" is between 11 and 20
242  * inclusive:
243  *
244  * ~~~~~~~~~~{.c}
245  * as_query_predexp_inita(&q, 7);
246  * as_query_predexp_add(&q, as_predexp_integer_bin("c"));
247  * as_query_predexp_add(&q, as_predexp_integer_value(11));
248  * as_query_predexp_add(&q, as_predexp_integer_greatereq());
249  * as_query_predexp_add(&q, as_predexp_integer_bin("c"));
250  * as_query_predexp_add(&q, as_predexp_integer_value(20));
251  * as_query_predexp_add(&q, as_predexp_integer_lesseq());
252  * as_query_predexp_add(&q, as_predexp_and(2));
253  * ~~~~~~~~~~
254  *
255  * @param binname The name of the bin.
256  *
257  * @returns a predicate expression suitable for adding to a query or
258  * scan.
259  */
261 as_predexp_integer_bin(char const * binname);
262 
263 /**
264  * Create an string bin value predicate expression.
265  *
266  * The string bin predicate expression pushes a single string bin
267  * value extractor onto the expression stack.
268  *
269  * For example, the following sequence of predicate expressions
270  * selects records where the value of bin "pet" is "cat" or "dog":
271  *
272  * ~~~~~~~~~~{.c}
273  * as_query_predexp_inita(&q, 7);
274  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
275  * as_query_predexp_add(&q, as_predexp_string_bin("pet"));
276  * as_query_predexp_add(&q, as_predexp_string_equal());
277  * as_query_predexp_add(&q, as_predexp_string_value("dog"));
278  * as_query_predexp_add(&q, as_predexp_string_bin("pet"));
279  * as_query_predexp_add(&q, as_predexp_string_equal());
280  * as_query_predexp_add(&q, as_predexp_or(2));
281  * ~~~~~~~~~~
282  *
283  * @param binname The name of the bin.
284  *
285  * @returns a predicate expression suitable for adding to a query or
286  * scan.
287  */
289 as_predexp_string_bin(char const * binname);
290 
291 /**
292  * Create an GeoJSON bin value predicate expression.
293  *
294  * The GeoJSON bin predicate expression pushes a single GeoJSON bin
295  * value extractor onto the expression stack.
296  *
297  * For example, the following sequence of predicate expressions
298  * selects records where a point in bin "loc" is inside the
299  * specified polygon:
300  *
301  * ~~~~~~~~~~{.c}
302  * char const * region =
303  * "{ "
304  * " \"type\": \"Polygon\", "
305  * " \"coordinates\": [ "
306  * " [[-122.500000, 37.000000],[-121.000000, 37.000000], "
307  * " [-121.000000, 38.080000],[-122.500000, 38.080000], "
308  * " [-122.500000, 37.000000]] "
309  * " ] "
310  * " } ";
311  *
312  * as_query_predexp_inita(&query, 3);
313  * as_query_predexp_add(&query, as_predexp_geojson_bin("loc"));
314  * as_query_predexp_add(&query, as_predexp_geojson_value(region));
315  * as_query_predexp_add(&query, as_predexp_geojson_within());
316  * ~~~~~~~~~~
317  *
318  * @param binname The name of the bin.
319  *
320  * @returns a predicate expression suitable for adding to a query or
321  * scan.
322  */
324 as_predexp_geojson_bin(char const * binname);
325 
326 /**
327  * Create a list bin value predicate expression.
328  *
329  * The list bin predicate expression pushes a single list bin value
330  * extractor onto the expression stack. List bin values may be used
331  * with list iteration expressions to evaluate a subexpression for
332  * each of the elements of the list.
333  *
334  * For example, the following sequence of predicate expressions
335  * selects records where one of the list items is "cat":
336  *
337  * ~~~~~~~~~~{.c}
338  * as_query_predexp_inita(&q, 5);
339  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
340  * as_query_predexp_add(&q, as_predexp_string_var("item"));
341  * as_query_predexp_add(&q, as_predexp_string_equal());
342  * as_query_predexp_add(&q, as_predexp_list_bin("pets"));
343  * as_query_predexp_add(&q, as_predexp_list_iterate_or("item"));
344  * ~~~~~~~~~~
345  *
346  * @param binname The name of the bin.
347  *
348  * @returns a predicate expression suitable for adding to a query or
349  * scan.
350  */
352 as_predexp_list_bin(char const * binname);
353 
354 /**
355  * Create a map bin value predicate expression.
356  *
357  * The map bin predicate expression pushes a single map bin value
358  * extractor onto the expression stack. Map bin values may be used
359  * with map iteration expressions to evaluate a subexpression for
360  * each of the elements of the map.
361  *
362  * For example, the following sequence of predicate expressions
363  * selects records where the map contains a key of "cat":
364  *
365  * ~~~~~~~~~~{.c}
366  * as_query_predexp_inita(&q, 5);
367  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
368  * as_query_predexp_add(&q, as_predexp_string_var("key"));
369  * as_query_predexp_add(&q, as_predexp_string_equal());
370  * as_query_predexp_add(&q, as_predexp_map_bin("petcount"));
371  * as_query_predexp_add(&q, as_predexp_mapkey_iterate_or("key"));
372  * ~~~~~~~~~~
373  *
374  * @param binname The name of the bin.
375  *
376  * @returns a predicate expression suitable for adding to a query or
377  * scan.
378  */
380 as_predexp_map_bin(char const * binname);
381 
382 /**
383  * Create an integer iteration variable (value) predicate expression.
384  *
385  * The integer iteration variable is used in the subexpression child
386  * of a list or map iterator and takes the value of each element in
387  * the collection as it is traversed.
388  *
389  * For example, the following sequence of predicate expressions
390  * selects records where the list contains a value of 42:
391  *
392  * ~~~~~~~~~~{.c}
393  * as_query_predexp_inita(&q, 5);
394  * as_query_predexp_add(&q, as_predexp_integer_var("item"));
395  * as_query_predexp_add(&q, as_predexp_integer_value(42));
396  * as_query_predexp_add(&q, as_predexp_integer_equal());
397  * as_query_predexp_add(&q, as_predexp_list_bin("numbers"));
398  * as_query_predexp_add(&q, as_predexp_list_iterate_or("item"));
399  * ~~~~~~~~~~
400  *
401  * @param varname The name of the iteration variable.
402  *
403  * @returns a predicate expression suitable for adding to a query or
404  * scan.
405  */
407 as_predexp_integer_var(char const * varname);
408 
409 /**
410  * Create an string iteration variable (value) predicate expression.
411  *
412  * The string iteration variable is used in the subexpression child
413  * of a list or map iterator and takes the value of each element in
414  * the collection as it is traversed.
415  *
416  * For example, the following sequence of predicate expressions
417  * selects records where one of the list items is "cat":
418  *
419  * ~~~~~~~~~~{.c}
420  * as_query_predexp_inita(&q, 5);
421  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
422  * as_query_predexp_add(&q, as_predexp_string_var("item"));
423  * as_query_predexp_add(&q, as_predexp_string_equal());
424  * as_query_predexp_add(&q, as_predexp_list_bin("pets"));
425  * as_query_predexp_add(&q, as_predexp_list_iterate_or("item"));
426  * ~~~~~~~~~~
427  *
428  * @param varname The name of the iteration variable.
429  *
430  * @returns a predicate expression suitable for adding to a query or
431  * scan.
432  */
434 as_predexp_string_var(char const * varname);
435 
436 /**
437  * Create an GeoJSON iteration variable (value) predicate expression.
438  *
439  * The GeoJSON iteration variable is used in the subexpression child
440  * of a list or map iterator and takes the value of each element in
441  * the collection as it is traversed.
442  *
443  * @param varname The name of the iteration variable.
444  *
445  * @returns a predicate expression suitable for adding to a query or
446  * scan.
447  */
449 as_predexp_geojson_var(char const * varname);
450 
451 /**
452  * Create a record device size metadata value predicate expression.
453  *
454  * The record device size expression assumes the value of the size in
455  * bytes that the record occupies on device storage. For non-persisted
456  * records, this value is 0.
457  *
458  * For example, the following sequence of predicate expressions
459  * selects records whose device storage size is larger than 65K:
460  *
461  * ~~~~~~~~~~{.c}
462  * as_query_predexp_inita(&q, 3);
463  * as_query_predexp_add(&q, as_predexp_rec_device_size());
464  * as_query_predexp_add(&q, as_predexp_integer_value(65 * 1024));
465  * as_query_predexp_add(&q, as_predexp_integer_greater());
466  * ~~~~~~~~~~
467  *
468  * @returns a predicate expression suitable for adding to a query or
469  * scan.
470  */
473 
474 /**
475  * Create a last update record metadata value predicate expression.
476  *
477  * The record last update expression assumes the value of the number
478  * of nanoseconds since the unix epoch that the record was last
479  * updated.
480  *
481  * For example, the following sequence of predicate expressions
482  * selects records that have been updated after an timestamp:
483  *
484  * ~~~~~~~~~~{.c}
485  * as_query_predexp_inita(&q, 3);
486  * as_query_predexp_add(&q, as_predexp_rec_last_update());
487  * as_query_predexp_add(&q, as_predexp_integer_value(g_tstampns));
488  * as_query_predexp_add(&q, as_predexp_integer_greater());
489  * ~~~~~~~~~~
490  *
491  * @returns a predicate expression suitable for adding to a query or
492  * scan.
493  */
496 
497 /**
498  * Create a void time record metadata value predicate expression.
499  *
500  * The record void time expression assumes the value of the number of
501  * nanoseconds since the unix epoch when the record will expire. The
502  * special value of 0 means the record will not expire.
503  *
504  * For example, the following sequence of predicate expressions
505  * selects records that have void time set to 0 (no expiration):
506  *
507  * ~~~~~~~~~~{.c}
508  * as_query_predexp_inita(&q, 3);
509  * as_query_predexp_add(&q, as_predexp_rec_void_time());
510  * as_query_predexp_add(&q, as_predexp_integer_value(0));
511  * as_query_predexp_add(&q, as_predexp_integer_equal());
512  * ~~~~~~~~~~
513  *
514  * @returns a predicate expression suitable for adding to a query or
515  * scan.
516  */
519 
520 /**
521  * Create an integer comparison logical predicate expression.
522  *
523  * The integer comparison expressions pop a pair of value expressions
524  * off the expression stack and compare them. The deeper of the two
525  * child expressions (pushed earlier) is considered the left side of
526  * the expression and the shallower (pushed later) is considered the
527  * right side.
528  *
529  * If the value of either of the child expressions is unknown because
530  * a specified bin does not exist or contains a value of the wrong
531  * type the result of the comparison is false. If a true outcome is
532  * desirable in this situation use the complimentary comparison and
533  * enclose in a logical NOT.
534  *
535  * For example, the following sequence of predicate expressions
536  * selects records that have bin "foo" greater than 42:
537  *
538  * ~~~~~~~~~~{.c}
539  * as_query_predexp_inita(&q, 3);
540  * as_query_predexp_add(&q, as_predexp_integer_bin("foo"));
541  * as_query_predexp_add(&q, as_predexp_integer_value(42));
542  * as_query_predexp_add(&q, as_predexp_integer_greater());
543  * ~~~~~~~~~~
544  *
545  * @returns a predicate expression suitable for adding to a query or
546  * scan.
547  */
550 
553 
556 
559 
562 
565 
566 /**
567  * Create an string comparison logical predicate expression.
568  *
569  * The string comparison expressions pop a pair of value expressions
570  * off the expression stack and compare them. The deeper of the two
571  * child expressions (pushed earlier) is considered the left side of
572  * the expression and the shallower (pushed later) is considered the
573  * right side.
574  *
575  * If the value of either of the child expressions is unknown because
576  * a specified bin does not exist or contains a value of the wrong
577  * type the result of the comparison is false. If a true outcome is
578  * desirable in this situation use the complimentary comparison and
579  * enclose in a logical NOT.
580  *
581  * For example, the following sequence of predicate expressions
582  * selects records that have bin "pet" equal to "cat":
583  *
584  * ~~~~~~~~~~{.c}
585  * as_query_predexp_inita(&q, 3);
586  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
587  * as_query_predexp_add(&q, as_predexp_string_bin("pet"));
588  * as_query_predexp_add(&q, as_predexp_string_equal());
589  * ~~~~~~~~~~
590  *
591  * @returns a predicate expression suitable for adding to a query or
592  * scan.
593  */
596 
599 
600 /**
601  * Create an string regular expression logical predicate expression.
602  *
603  * The string regex expression pops two children off the expression
604  * stack and compares a child value expression to a regular
605  * expression. The left child (pushed earlier) must contain the
606  * string value to be matched. The right child (pushed later) must
607  * be a string value containing a valid regular expression..
608  *
609  * If the value of the left child is unknown because a specified
610  * bin does not exist or contains a value of the wrong type the
611  * result of the regex match is false.
612  *
613  * The cflags argument is passed to the regcomp library routine on
614  * the server. Useful values include REG_EXTENDED, REG_ICASE and
615  * REG_NEWLINE.
616  *
617  * For example, the following sequence of predicate expressions
618  * selects records that have bin "hex" value ending in '1' or '2':
619  *
620  * ~~~~~~~~~~{.c}
621  * as_query_predexp_inita(&q, 3);
622  * as_query_predexp_add(&q, as_predexp_string_bin("hex"));
623  * as_query_predexp_add(&q, as_predexp_string_value("0x00.[12]"));
624  * as_query_predexp_add(&q, as_predexp_string_regex(REG_ICASE));
625  * ~~~~~~~~~~
626  *
627  * @param cflags POSIX regex cflags value.
628  *
629  * @returns a predicate expression suitable for adding to a query or
630  * scan.
631  */
633 as_predexp_string_regex(uint32_t cflags);
634 
635 /**
636  * Create an GeoJSON Points-in-Region logical predicate expression.
637  *
638  * The Points-in-Region (within) expression pops two children off the
639  * expression stack and checks to see if a child GeoJSON point is
640  * inside a specified GeoJSON region. The left child (pushed
641  * earlier) must contain a GeoJSON value specifying a point. The
642  * right child (pushed later) must be a GeoJSON value containing a
643  * region.
644  *
645  * If the value of the left child is unknown because a specified bin
646  * does not exist or contains a value of the wrong type the result of
647  * the within expression is false.
648  *
649  * For example, the following sequence of predicate expressions
650  * selects records where a point in bin "loc" is inside the
651  * specified polygon:
652  *
653  * ~~~~~~~~~~{.c}
654  * char const * region =
655  * "{ "
656  * " \"type\": \"Polygon\", "
657  * " \"coordinates\": [ "
658  * " [[-122.500000, 37.000000],[-121.000000, 37.000000], "
659  * " [-121.000000, 38.080000],[-122.500000, 38.080000], "
660  * " [-122.500000, 37.000000]] "
661  * " ] "
662  * " } ";
663  *
664  * as_query_predexp_inita(&query, 3);
665  * as_query_predexp_add(&query, as_predexp_geojson_bin("loc"));
666  * as_query_predexp_add(&query, as_predexp_geojson_value(region));
667  * as_query_predexp_add(&query, as_predexp_geojson_within());
668  * ~~~~~~~~~~
669  *
670  * @returns a predicate expression suitable for adding to a query or
671  * scan.
672  */
675 
676 /**
677  * Create an GeoJSON Regions-Containing-Point logical predicate expression.
678  *
679  * The Regions-Containing-Point (contains) expression pops two
680  * children off the expression stack and checks to see if a child
681  * GeoJSON region contains a specified GeoJSON point. The left child
682  * (pushed earlier) must contain a GeoJSON value specifying a
683  * possibly enclosing region. The right child (pushed later) must be
684  * a GeoJSON value containing a point.
685  *
686  * If the value of the left child is unknown because a specified bin
687  * does not exist or contains a value of the wrong type the result of
688  * the contains expression is false.
689  *
690  * For example, the following sequence of predicate expressions
691  * selects records where a region in bin "rgn" contains the specified
692  * query point:
693  *
694  * ~~~~~~~~~~{.c}
695  * char const * point =
696  * "{ "
697  * " \"type\": \"Point\", "
698  * " \"coordinates\": [ -122.0986857, 37.4214209 ] "
699  * "} ";
700  *
701  * as_query_predexp_inita(&query, 3);
702  * as_query_predexp_add(&query, as_predexp_geojson_bin("rgn"));
703  * as_query_predexp_add(&query, as_predexp_geojson_value(point));
704  * as_query_predexp_add(&query, as_predexp_geojson_contains());
705  * ~~~~~~~~~~
706  *
707  * @returns a predicate expression suitable for adding to a query or
708  * scan.
709  */
712 
713 /**
714  * Create an list iteration OR logical predicate expression.
715  *
716  * The list iteration expression pops two children off the expression
717  * stack. The left child (pushed earlier) must contain a logical
718  * subexpression containing one or more matching iteration variable
719  * expressions. The right child (pushed later) must specify a list
720  * bin. The list iteration traverses the list and repeatedly
721  * evaluates the subexpression substituting each list element's value
722  * into the matching iteration variable. The result of the iteration
723  * expression is a logical OR of all of the individual element
724  * evaluations.
725  *
726  * If the list bin contains zero elements as_predexp_list_iterate_or
727  * will return false.
728  *
729  * For example, the following sequence of predicate expressions
730  * selects records where one of the list items is "cat":
731  *
732  * ~~~~~~~~~~{.c}
733  * as_query_predexp_inita(&q, 5);
734  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
735  * as_query_predexp_add(&q, as_predexp_string_var("item"));
736  * as_query_predexp_add(&q, as_predexp_string_equal());
737  * as_query_predexp_add(&q, as_predexp_list_bin("pets"));
738  * as_query_predexp_add(&q, as_predexp_list_iterate_or("item"));
739  * ~~~~~~~~~~
740  *
741  * @param varname The name of the list item iteration variable.
742  *
743  * @returns a predicate expression suitable for adding to a query or
744  * scan.
745  */
747 as_predexp_list_iterate_or(char const * varname);
748 
749 /**
750  * Create an list iteration AND logical predicate expression.
751  *
752  * The list iteration expression pops two children off the expression
753  * stack. The left child (pushed earlier) must contain a logical
754  * subexpression containing one or more matching iteration variable
755  * expressions. The right child (pushed later) must specify a list
756  * bin. The list iteration traverses the list and repeatedly
757  * evaluates the subexpression substituting each list element's value
758  * into the matching iteration variable. The result of the iteration
759  * expression is a logical AND of all of the individual element
760  * evaluations.
761  *
762  * If the list bin contains zero elements as_predexp_list_iterate_and
763  * will return true. This is useful when testing for exclusion (see
764  * example).
765  *
766  * For example, the following sequence of predicate expressions
767  * selects records where none of the list items is "cat":
768  *
769  * ~~~~~~~~~~{.c}
770  * as_query_predexp_inita(&q, 6);
771  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
772  * as_query_predexp_add(&q, as_predexp_string_var("item"));
773  * as_query_predexp_add(&q, as_predexp_string_equal());
774  * as_query_predexp_add(&q, as_predexp_not());
775  * as_query_predexp_add(&q, as_predexp_list_bin("pets"));
776  * as_query_predexp_add(&q, as_predexp_list_iterate_and("item"));
777  * ~~~~~~~~~~
778  *
779  * @param varname The name of the list item iteration variable.
780  *
781  * @returns a predicate expression suitable for adding to a query or
782  * scan.
783  */
785 as_predexp_list_iterate_and(char const * varname);
786 
787 /**
788  * Create an map key iteration OR logical predicate expression.
789  *
790  * The mapkey iteration expression pops two children off the
791  * expression stack. The left child (pushed earlier) must contain a
792  * logical subexpression containing one or more matching iteration
793  * variable expressions. The right child (pushed later) must specify
794  * a map bin. The mapkey iteration traverses the map and repeatedly
795  * evaluates the subexpression substituting each map key value into
796  * the matching iteration variable. The result of the iteration
797  * expression is a logical OR of all of the individual element
798  * evaluations.
799  *
800  * If the map bin contains zero elements as_predexp_mapkey_iterate_or
801  * will return false.
802  *
803  * For example, the following sequence of predicate expressions
804  * selects records where one of the map keys is "cat":
805  *
806  * ~~~~~~~~~~{.c}
807  * as_query_predexp_inita(&q, 5);
808  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
809  * as_query_predexp_add(&q, as_predexp_string_var("item"));
810  * as_query_predexp_add(&q, as_predexp_string_equal());
811  * as_query_predexp_add(&q, as_predexp_map_bin("petcount"));
812  * as_query_predexp_add(&q, as_predexp_mapkey_iterate_or("item"));
813  * ~~~~~~~~~~
814  *
815  * @param varname The name of the map key iteration variable.
816  *
817  * @returns a predicate expression suitable for adding to a query or
818  * scan.
819  */
821 as_predexp_mapkey_iterate_or(char const * varname);
822 
823 /**
824  * Create an map key iteration AND logical predicate expression.
825  *
826  * The mapkey iteration expression pops two children off the
827  * expression stack. The left child (pushed earlier) must contain a
828  * logical subexpression containing one or more matching iteration
829  * variable expressions. The right child (pushed later) must specify
830  * a map bin. The mapkey iteration traverses the map and repeatedly
831  * evaluates the subexpression substituting each map key value into
832  * the matching iteration variable. The result of the iteration
833  * expression is a logical AND of all of the individual element
834  * evaluations.
835  *
836  * If the map bin contains zero elements as_predexp_mapkey_iterate_and
837  * will return true. This is useful when testing for exclusion (see
838  * example).
839  *
840  * For example, the following sequence of predicate expressions
841  * selects records where none of the map keys is "cat":
842  *
843  * ~~~~~~~~~~{.c}
844  * as_query_predexp_inita(&q, 6);
845  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
846  * as_query_predexp_add(&q, as_predexp_string_var("item"));
847  * as_query_predexp_add(&q, as_predexp_string_equal());
848  * as_query_predexp_add(&q, as_predexp_not());
849  * as_query_predexp_add(&q, as_predexp_map_bin("petcount"));
850  * as_query_predexp_add(&q, as_predexp_mapkey_iterate_or("item"));
851  * ~~~~~~~~~~
852  *
853  * @param varname The name of the map key iteration variable.
854  *
855  * @returns a predicate expression suitable for adding to a query or
856  * scan.
857  */
859 as_predexp_mapkey_iterate_and(char const * varname);
860 
861 /**
862  * Create an map value iteration OR logical predicate expression.
863  *
864  * The mapval iteration expression pops two children off the
865  * expression stack. The left child (pushed earlier) must contain a
866  * logical subexpression containing one or more matching iteration
867  * variable expressions. The right child (pushed later) must specify
868  * a map bin. The mapval iteration traverses the map and repeatedly
869  * evaluates the subexpression substituting each map value into the
870  * matching iteration variable. The result of the iteration
871  * expression is a logical OR of all of the individual element
872  * evaluations.
873  *
874  * If the map bin contains zero elements as_predexp_mapval_iterate_or
875  * will return false.
876  *
877  * For example, the following sequence of predicate expressions
878  * selects records where one of the map values is 0:
879  *
880  * ~~~~~~~~~~{.c}
881  * as_query_predexp_inita(&q, 5);
882  * as_query_predexp_add(&q, as_predexp_integer_var("count"));
883  * as_query_predexp_add(&q, as_predexp_integer_value(0));
884  * as_query_predexp_add(&q, as_predexp_integer_equal());
885  * as_query_predexp_add(&q, as_predexp_map_bin("petcount"));
886  * as_query_predexp_add(&q, as_predexp_mapval_iterate_or("count"));
887  * ~~~~~~~~~~
888  *
889  * @param varname The name of the map value iteration variable.
890  *
891  * @returns a predicate expression suitable for adding to a query or
892  * scan.
893  */
895 as_predexp_mapval_iterate_or(char const * varname);
896 
897 /**
898  * Create an map value iteration AND logical predicate expression.
899  *
900  * The mapval iteration expression pops two children off the
901  * expression stack. The left child (pushed earlier) must contain a
902  * logical subexpression containing one or more matching iteration
903  * variable expressions. The right child (pushed later) must specify
904  * a map bin. The mapval iteration traverses the map and repeatedly
905  * evaluates the subexpression substituting each map value into the
906  * matching iteration variable. The result of the iteration
907  * expression is a logical AND of all of the individual element
908  * evaluations.
909  *
910  * If the map bin contains zero elements as_predexp_mapval_iterate_and
911  * will return true. This is useful when testing for exclusion (see
912  * example).
913  *
914  * For example, the following sequence of predicate expressions
915  * selects records where none of the map values is 0:
916  *
917  * ~~~~~~~~~~{.c}
918  * as_query_predexp_inita(&q, 6);
919  * as_query_predexp_add(&q, as_predexp_integer_var("count"));
920  * as_query_predexp_add(&q, as_predexp_integer_value(0));
921  * as_query_predexp_add(&q, as_predexp_integer_equal());
922  * as_query_predexp_add(&q, as_predexp_not());
923  * as_query_predexp_add(&q, as_predexp_map_bin("petcount"));
924  * as_query_predexp_add(&q, as_predexp_mapval_iterate_and("count"));
925  * ~~~~~~~~~~
926  *
927  * @param varname The name of the map value iteration variable.
928  *
929  * @returns a predicate expression suitable for adding to a query or
930  * scan.
931  */
933 as_predexp_mapval_iterate_and(char const * varname);
934 
935 #ifdef __cplusplus
936 } // end extern "C"
937 #endif