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 a digest modulo record metadata value predicate expression.
522  *
523  * The digest modulo expression assumes the value of 4 bytes of the
524  * record's key digest modulo it's modulus argument.
525  *
526  * For example, the following sequence of predicate expressions
527  * selects records that have digest(key) % 3 == 1):
528  *
529  * ~~~~~~~~~~{.c}
530  * as_query_predexp_inita(&q, 3);
531  * as_query_predexp_add(&q, as_predexp_rec_digest_modulo(3));
532  * as_query_predexp_add(&q, as_predexp_integer_value(1));
533  * as_query_predexp_add(&q, as_predexp_integer_equal());
534  * ~~~~~~~~~~
535  *
536  * @param mod The modulus argument.
537  *
538  * @returns a predicate expression suitable for adding to a query or
539  * scan.
540  */
542 as_predexp_rec_digest_modulo(int32_t mod);
543 
544 /**
545  * Create an integer comparison logical predicate expression.
546  *
547  * The integer comparison expressions pop a pair of value expressions
548  * off the expression stack and compare them. The deeper of the two
549  * child expressions (pushed earlier) is considered the left side of
550  * the expression and the shallower (pushed later) is considered the
551  * right side.
552  *
553  * If the value of either of the child expressions is unknown because
554  * a specified bin does not exist or contains a value of the wrong
555  * type the result of the comparison is false. If a true outcome is
556  * desirable in this situation use the complimentary comparison and
557  * enclose in a logical NOT.
558  *
559  * For example, the following sequence of predicate expressions
560  * selects records that have bin "foo" greater than 42:
561  *
562  * ~~~~~~~~~~{.c}
563  * as_query_predexp_inita(&q, 3);
564  * as_query_predexp_add(&q, as_predexp_integer_bin("foo"));
565  * as_query_predexp_add(&q, as_predexp_integer_value(42));
566  * as_query_predexp_add(&q, as_predexp_integer_greater());
567  * ~~~~~~~~~~
568  *
569  * @returns a predicate expression suitable for adding to a query or
570  * scan.
571  */
574 
577 
580 
583 
586 
589 
590 /**
591  * Create an string comparison logical predicate expression.
592  *
593  * The string comparison expressions pop a pair of value expressions
594  * off the expression stack and compare them. The deeper of the two
595  * child expressions (pushed earlier) is considered the left side of
596  * the expression and the shallower (pushed later) is considered the
597  * right side.
598  *
599  * If the value of either of the child expressions is unknown because
600  * a specified bin does not exist or contains a value of the wrong
601  * type the result of the comparison is false. If a true outcome is
602  * desirable in this situation use the complimentary comparison and
603  * enclose in a logical NOT.
604  *
605  * For example, the following sequence of predicate expressions
606  * selects records that have bin "pet" equal to "cat":
607  *
608  * ~~~~~~~~~~{.c}
609  * as_query_predexp_inita(&q, 3);
610  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
611  * as_query_predexp_add(&q, as_predexp_string_bin("pet"));
612  * as_query_predexp_add(&q, as_predexp_string_equal());
613  * ~~~~~~~~~~
614  *
615  * @returns a predicate expression suitable for adding to a query or
616  * scan.
617  */
620 
623 
624 /**
625  * Create an string regular expression logical predicate expression.
626  *
627  * The string regex expression pops two children off the expression
628  * stack and compares a child value expression to a regular
629  * expression. The left child (pushed earlier) must contain the
630  * string value to be matched. The right child (pushed later) must
631  * be a string value containing a valid regular expression..
632  *
633  * If the value of the left child is unknown because a specified
634  * bin does not exist or contains a value of the wrong type the
635  * result of the regex match is false.
636  *
637  * The cflags argument is passed to the regcomp library routine on
638  * the server. Useful values include REG_EXTENDED, REG_ICASE and
639  * REG_NEWLINE.
640  *
641  * For example, the following sequence of predicate expressions
642  * selects records that have bin "hex" value ending in '1' or '2':
643  *
644  * ~~~~~~~~~~{.c}
645  * as_query_predexp_inita(&q, 3);
646  * as_query_predexp_add(&q, as_predexp_string_bin("hex"));
647  * as_query_predexp_add(&q, as_predexp_string_value("0x00.[12]"));
648  * as_query_predexp_add(&q, as_predexp_string_regex(REG_ICASE));
649  * ~~~~~~~~~~
650  *
651  * @param cflags POSIX regex cflags value.
652  *
653  * @returns a predicate expression suitable for adding to a query or
654  * scan.
655  */
657 as_predexp_string_regex(uint32_t cflags);
658 
659 /**
660  * Create an GeoJSON Points-in-Region logical predicate expression.
661  *
662  * The Points-in-Region (within) expression pops two children off the
663  * expression stack and checks to see if a child GeoJSON point is
664  * inside a specified GeoJSON region. The left child (pushed
665  * earlier) must contain a GeoJSON value specifying a point. The
666  * right child (pushed later) must be a GeoJSON value containing a
667  * region.
668  *
669  * If the value of the left child is unknown because a specified bin
670  * does not exist or contains a value of the wrong type the result of
671  * the within expression is false.
672  *
673  * For example, the following sequence of predicate expressions
674  * selects records where a point in bin "loc" is inside the
675  * specified polygon:
676  *
677  * ~~~~~~~~~~{.c}
678  * char const * region =
679  * "{ "
680  * " \"type\": \"Polygon\", "
681  * " \"coordinates\": [ "
682  * " [[-122.500000, 37.000000],[-121.000000, 37.000000], "
683  * " [-121.000000, 38.080000],[-122.500000, 38.080000], "
684  * " [-122.500000, 37.000000]] "
685  * " ] "
686  * " } ";
687  *
688  * as_query_predexp_inita(&query, 3);
689  * as_query_predexp_add(&query, as_predexp_geojson_bin("loc"));
690  * as_query_predexp_add(&query, as_predexp_geojson_value(region));
691  * as_query_predexp_add(&query, as_predexp_geojson_within());
692  * ~~~~~~~~~~
693  *
694  * @returns a predicate expression suitable for adding to a query or
695  * scan.
696  */
699 
700 /**
701  * Create an GeoJSON Regions-Containing-Point logical predicate expression.
702  *
703  * The Regions-Containing-Point (contains) expression pops two
704  * children off the expression stack and checks to see if a child
705  * GeoJSON region contains a specified GeoJSON point. The left child
706  * (pushed earlier) must contain a GeoJSON value specifying a
707  * possibly enclosing region. The right child (pushed later) must be
708  * a GeoJSON value containing a point.
709  *
710  * If the value of the left child is unknown because a specified bin
711  * does not exist or contains a value of the wrong type the result of
712  * the contains expression is false.
713  *
714  * For example, the following sequence of predicate expressions
715  * selects records where a region in bin "rgn" contains the specified
716  * query point:
717  *
718  * ~~~~~~~~~~{.c}
719  * char const * point =
720  * "{ "
721  * " \"type\": \"Point\", "
722  * " \"coordinates\": [ -122.0986857, 37.4214209 ] "
723  * "} ";
724  *
725  * as_query_predexp_inita(&query, 3);
726  * as_query_predexp_add(&query, as_predexp_geojson_bin("rgn"));
727  * as_query_predexp_add(&query, as_predexp_geojson_value(point));
728  * as_query_predexp_add(&query, as_predexp_geojson_contains());
729  * ~~~~~~~~~~
730  *
731  * @returns a predicate expression suitable for adding to a query or
732  * scan.
733  */
736 
737 /**
738  * Create an list iteration OR logical predicate expression.
739  *
740  * The list iteration expression pops two children off the expression
741  * stack. The left child (pushed earlier) must contain a logical
742  * subexpression containing one or more matching iteration variable
743  * expressions. The right child (pushed later) must specify a list
744  * bin. The list iteration traverses the list and repeatedly
745  * evaluates the subexpression substituting each list element's value
746  * into the matching iteration variable. The result of the iteration
747  * expression is a logical OR of all of the individual element
748  * evaluations.
749  *
750  * If the list bin contains zero elements as_predexp_list_iterate_or
751  * will return false.
752  *
753  * For example, the following sequence of predicate expressions
754  * selects records where one of the list items is "cat":
755  *
756  * ~~~~~~~~~~{.c}
757  * as_query_predexp_inita(&q, 5);
758  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
759  * as_query_predexp_add(&q, as_predexp_string_var("item"));
760  * as_query_predexp_add(&q, as_predexp_string_equal());
761  * as_query_predexp_add(&q, as_predexp_list_bin("pets"));
762  * as_query_predexp_add(&q, as_predexp_list_iterate_or("item"));
763  * ~~~~~~~~~~
764  *
765  * @param varname The name of the list item iteration variable.
766  *
767  * @returns a predicate expression suitable for adding to a query or
768  * scan.
769  */
771 as_predexp_list_iterate_or(char const * varname);
772 
773 /**
774  * Create an list iteration AND logical predicate expression.
775  *
776  * The list iteration expression pops two children off the expression
777  * stack. The left child (pushed earlier) must contain a logical
778  * subexpression containing one or more matching iteration variable
779  * expressions. The right child (pushed later) must specify a list
780  * bin. The list iteration traverses the list and repeatedly
781  * evaluates the subexpression substituting each list element's value
782  * into the matching iteration variable. The result of the iteration
783  * expression is a logical AND of all of the individual element
784  * evaluations.
785  *
786  * If the list bin contains zero elements as_predexp_list_iterate_and
787  * will return true. This is useful when testing for exclusion (see
788  * example).
789  *
790  * For example, the following sequence of predicate expressions
791  * selects records where none of the list items is "cat":
792  *
793  * ~~~~~~~~~~{.c}
794  * as_query_predexp_inita(&q, 6);
795  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
796  * as_query_predexp_add(&q, as_predexp_string_var("item"));
797  * as_query_predexp_add(&q, as_predexp_string_equal());
798  * as_query_predexp_add(&q, as_predexp_not());
799  * as_query_predexp_add(&q, as_predexp_list_bin("pets"));
800  * as_query_predexp_add(&q, as_predexp_list_iterate_and("item"));
801  * ~~~~~~~~~~
802  *
803  * @param varname The name of the list item iteration variable.
804  *
805  * @returns a predicate expression suitable for adding to a query or
806  * scan.
807  */
809 as_predexp_list_iterate_and(char const * varname);
810 
811 /**
812  * Create an map key iteration OR logical predicate expression.
813  *
814  * The mapkey iteration expression pops two children off the
815  * expression stack. The left child (pushed earlier) must contain a
816  * logical subexpression containing one or more matching iteration
817  * variable expressions. The right child (pushed later) must specify
818  * a map bin. The mapkey iteration traverses the map and repeatedly
819  * evaluates the subexpression substituting each map key value into
820  * the matching iteration variable. The result of the iteration
821  * expression is a logical OR of all of the individual element
822  * evaluations.
823  *
824  * If the map bin contains zero elements as_predexp_mapkey_iterate_or
825  * will return false.
826  *
827  * For example, the following sequence of predicate expressions
828  * selects records where one of the map keys is "cat":
829  *
830  * ~~~~~~~~~~{.c}
831  * as_query_predexp_inita(&q, 5);
832  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
833  * as_query_predexp_add(&q, as_predexp_string_var("item"));
834  * as_query_predexp_add(&q, as_predexp_string_equal());
835  * as_query_predexp_add(&q, as_predexp_map_bin("petcount"));
836  * as_query_predexp_add(&q, as_predexp_mapkey_iterate_or("item"));
837  * ~~~~~~~~~~
838  *
839  * @param varname The name of the map key iteration variable.
840  *
841  * @returns a predicate expression suitable for adding to a query or
842  * scan.
843  */
845 as_predexp_mapkey_iterate_or(char const * varname);
846 
847 /**
848  * Create an map key iteration AND logical predicate expression.
849  *
850  * The mapkey iteration expression pops two children off the
851  * expression stack. The left child (pushed earlier) must contain a
852  * logical subexpression containing one or more matching iteration
853  * variable expressions. The right child (pushed later) must specify
854  * a map bin. The mapkey iteration traverses the map and repeatedly
855  * evaluates the subexpression substituting each map key value into
856  * the matching iteration variable. The result of the iteration
857  * expression is a logical AND of all of the individual element
858  * evaluations.
859  *
860  * If the map bin contains zero elements as_predexp_mapkey_iterate_and
861  * will return true. This is useful when testing for exclusion (see
862  * example).
863  *
864  * For example, the following sequence of predicate expressions
865  * selects records where none of the map keys is "cat":
866  *
867  * ~~~~~~~~~~{.c}
868  * as_query_predexp_inita(&q, 6);
869  * as_query_predexp_add(&q, as_predexp_string_value("cat"));
870  * as_query_predexp_add(&q, as_predexp_string_var("item"));
871  * as_query_predexp_add(&q, as_predexp_string_equal());
872  * as_query_predexp_add(&q, as_predexp_not());
873  * as_query_predexp_add(&q, as_predexp_map_bin("petcount"));
874  * as_query_predexp_add(&q, as_predexp_mapkey_iterate_or("item"));
875  * ~~~~~~~~~~
876  *
877  * @param varname The name of the map key iteration variable.
878  *
879  * @returns a predicate expression suitable for adding to a query or
880  * scan.
881  */
883 as_predexp_mapkey_iterate_and(char const * varname);
884 
885 /**
886  * Create an map value iteration OR logical predicate expression.
887  *
888  * The mapval iteration expression pops two children off the
889  * expression stack. The left child (pushed earlier) must contain a
890  * logical subexpression containing one or more matching iteration
891  * variable expressions. The right child (pushed later) must specify
892  * a map bin. The mapval iteration traverses the map and repeatedly
893  * evaluates the subexpression substituting each map value into the
894  * matching iteration variable. The result of the iteration
895  * expression is a logical OR of all of the individual element
896  * evaluations.
897  *
898  * If the map bin contains zero elements as_predexp_mapval_iterate_or
899  * will return false.
900  *
901  * For example, the following sequence of predicate expressions
902  * selects records where one of the map values is 0:
903  *
904  * ~~~~~~~~~~{.c}
905  * as_query_predexp_inita(&q, 5);
906  * as_query_predexp_add(&q, as_predexp_integer_var("count"));
907  * as_query_predexp_add(&q, as_predexp_integer_value(0));
908  * as_query_predexp_add(&q, as_predexp_integer_equal());
909  * as_query_predexp_add(&q, as_predexp_map_bin("petcount"));
910  * as_query_predexp_add(&q, as_predexp_mapval_iterate_or("count"));
911  * ~~~~~~~~~~
912  *
913  * @param varname The name of the map value iteration variable.
914  *
915  * @returns a predicate expression suitable for adding to a query or
916  * scan.
917  */
919 as_predexp_mapval_iterate_or(char const * varname);
920 
921 /**
922  * Create an map value iteration AND logical predicate expression.
923  *
924  * The mapval iteration expression pops two children off the
925  * expression stack. The left child (pushed earlier) must contain a
926  * logical subexpression containing one or more matching iteration
927  * variable expressions. The right child (pushed later) must specify
928  * a map bin. The mapval iteration traverses the map and repeatedly
929  * evaluates the subexpression substituting each map value into the
930  * matching iteration variable. The result of the iteration
931  * expression is a logical AND of all of the individual element
932  * evaluations.
933  *
934  * If the map bin contains zero elements as_predexp_mapval_iterate_and
935  * will return true. This is useful when testing for exclusion (see
936  * example).
937  *
938  * For example, the following sequence of predicate expressions
939  * selects records where none of the map values is 0:
940  *
941  * ~~~~~~~~~~{.c}
942  * as_query_predexp_inita(&q, 6);
943  * as_query_predexp_add(&q, as_predexp_integer_var("count"));
944  * as_query_predexp_add(&q, as_predexp_integer_value(0));
945  * as_query_predexp_add(&q, as_predexp_integer_equal());
946  * as_query_predexp_add(&q, as_predexp_not());
947  * as_query_predexp_add(&q, as_predexp_map_bin("petcount"));
948  * as_query_predexp_add(&q, as_predexp_mapval_iterate_and("count"));
949  * ~~~~~~~~~~
950  *
951  * @param varname The name of the map value iteration variable.
952  *
953  * @returns a predicate expression suitable for adding to a query or
954  * scan.
955  */
957 as_predexp_mapval_iterate_and(char const * varname);
958 
959 #ifdef __cplusplus
960 } // end extern "C"
961 #endif