Debian Codegraph @

gcc/jit/docs/cp/topics/expressions.rst

raw
1 .. Copyright (C) 2014-2025 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <[email protected]>
3
4 This is free software: you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by
6 the Free Software Foundation, either version 3 of the License, or
7 (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful, but
10 WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program. If not, see
16 <https://www.gnu.org/licenses/>.
17
18 .. default-domain:: cpp
19
20 Expressions
21 ===========
22
23 Rvalues
24 -------
25 .. class:: gccjit::rvalue
26
27 A :class:`gccjit::rvalue` is an expression that can be computed. It is a
28 subclass of :class:`gccjit::object`, and is a thin wrapper around
29 :c:expr:`gcc_jit_rvalue *` from the C API.
30
31 It can be simple, e.g.:
32
33 * an integer value e.g. `0` or `42`
34 * a string literal e.g. `"Hello world"`
35 * a variable e.g. `i`. These are also lvalues (see below).
36
37 or compound e.g.:
38
39 * a unary expression e.g. `!cond`
40 * a binary expression e.g. `(a + b)`
41 * a function call e.g. `get_distance (&player_ship, &target)`
42 * etc.
43
44 Every rvalue has an associated type, and the API will check to ensure
45 that types match up correctly (otherwise the context will emit an error).
46
47 .. function:: gccjit::type gccjit::rvalue::get_type ()
48
49 Get the type of this rvalue.
50
51
52 Simple expressions
53 ******************
54
55 .. function:: gccjit::rvalue \
56 gccjit::context::new_rvalue (gccjit::type numeric_type, \
57 int value) const
58
59 Given a numeric type (integer or floating point), build an rvalue for
60 the given constant :expr:`int` value.
61
62 .. function:: gccjit::rvalue \
63 gccjit::context::new_rvalue (gccjit::type numeric_type, \
64 long value) const
65
66 Given a numeric type (integer or floating point), build an rvalue for
67 the given constant :expr:`long` value.
68
69 .. function:: gccjit::rvalue \
70 gccjit::context::zero (gccjit::type numeric_type) const
71
72 Given a numeric type (integer or floating point), get the rvalue for
73 zero. Essentially this is just a shortcut for:
74
75 .. code-block:: c++
76
77 ctxt.new_rvalue (numeric_type, 0)
78
79 .. function:: gccjit::rvalue \
80 gccjit::context::one (gccjit::type numeric_type) const
81
82 Given a numeric type (integer or floating point), get the rvalue for
83 one. Essentially this is just a shortcut for:
84
85 .. code-block:: c++
86
87 ctxt.new_rvalue (numeric_type, 1)
88
89 .. function:: gccjit::rvalue \
90 gccjit::context::new_rvalue (gccjit::type numeric_type, \
91 double value) const
92
93 Given a numeric type (integer or floating point), build an rvalue for
94 the given constant :expr:`double` value.
95
96 .. function:: gccjit::rvalue \
97 gccjit::context::new_rvalue (gccjit::type pointer_type, \
98 void *value) const
99
100 Given a pointer type, build an rvalue for the given address.
101
102 .. function:: gccjit::rvalue \
103 gccjit::context::new_rvalue (const std::string &value) const
104
105 Generate an rvalue of type :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR` for
106 the given string. This is akin to a string literal.
107
108 Vector expressions
109 ******************
110
111 .. function:: gccjit::rvalue \
112 gccjit::context::new_rvalue (gccjit::type vector_type, \
113 std::vector<gccjit::rvalue> elements) const
114
115 Given a vector type, and a vector of scalar rvalue elements, generate a
116 vector rvalue.
117
118 The number of elements needs to match that of the vector type.
119
120 Unary Operations
121 ****************
122
123 .. function:: gccjit::rvalue \
124 gccjit::context::new_unary_op (enum gcc_jit_unary_op, \
125 gccjit::type result_type, \
126 gccjit::rvalue rvalue, \
127 gccjit::location loc)
128
129 Build a unary operation out of an input rvalue.
130
131 Parameter ``loc`` is optional.
132
133 This is a thin wrapper around the C API's
134 :c:func:`gcc_jit_context_new_unary_op` and the available unary
135 operations are documented there.
136
137 There are shorter ways to spell the various specific kinds of unary
138 operation:
139
140 .. function:: gccjit::rvalue \
141 gccjit::context::new_minus (gccjit::type result_type, \
142 gccjit::rvalue a, \
143 gccjit::location loc)
144
145 Negate an arithmetic value; for example:
146
147 .. code-block:: c++
148
149 gccjit::rvalue negpi = ctxt.new_minus (t_double, pi);
150
151 builds the equivalent of this C expression:
152
153 .. code-block:: c
154
155 -pi
156
157 .. function:: gccjit::rvalue \
158 new_bitwise_negate (gccjit::type result_type, \
159 gccjit::rvalue a, \
160 gccjit::location loc)
161
162 Bitwise negation of an integer value (one's complement); for example:
163
164 .. code-block:: c++
165
166 gccjit::rvalue mask = ctxt.new_bitwise_negate (t_int, a);
167
168 builds the equivalent of this C expression:
169
170 .. code-block:: c
171
172 ~a
173
174 .. function:: gccjit::rvalue \
175 new_logical_negate (gccjit::type result_type, \
176 gccjit::rvalue a, \
177 gccjit::location loc)
178
179 Logical negation of an arithmetic or pointer value; for example:
180
181 .. code-block:: c++
182
183 gccjit::rvalue guard = ctxt.new_logical_negate (t_bool, cond);
184
185 builds the equivalent of this C expression:
186
187 .. code-block:: c
188
189 !cond
190
191
192 The most concise way to spell them is with overloaded operators:
193
194 .. function:: gccjit::rvalue operator- (gccjit::rvalue a)
195
196 .. code-block:: c++
197
198 gccjit::rvalue negpi = -pi;
199
200
201 .. function:: gccjit::rvalue operator~ (gccjit::rvalue a)
202
203 .. code-block:: c++
204
205 gccjit::rvalue mask = ~a;
206
207 .. function:: gccjit::rvalue operator! (gccjit::rvalue a)
208
209 .. code-block:: c++
210
211 gccjit::rvalue guard = !cond;
212
213
214 Binary Operations
215 *****************
216
217 .. function:: gccjit::rvalue\
218 gccjit::context::new_binary_op (enum gcc_jit_binary_op, \
219 gccjit::type result_type, \
220 gccjit::rvalue a, \
221 gccjit::rvalue b, \
222 gccjit::location loc)
223
224 Build a binary operation out of two constituent rvalues.
225
226 Parameter ``loc`` is optional.
227
228 This is a thin wrapper around the C API's
229 :c:func:`gcc_jit_context_new_binary_op` and the available binary
230 operations are documented there.
231
232 There are shorter ways to spell the various specific kinds of binary
233 operation:
234
235 .. function:: gccjit::rvalue \
236 gccjit::context::new_plus (gccjit::type result_type, \
237 gccjit::rvalue a, gccjit::rvalue b, \
238 gccjit::location loc)
239 gccjit::rvalue \
240 gccjit::context::new_minus (gccjit::type result_type, \
241 gccjit::rvalue a, gccjit::rvalue b, \
242 gccjit::location loc)
243 gccjit::rvalue \
244 gccjit::context::new_mult (gccjit::type result_type, \
245 gccjit::rvalue a, gccjit::rvalue b, \
246 gccjit::location loc)
247 gccjit::rvalue \
248 gccjit::context::new_divide (gccjit::type result_type, \
249 gccjit::rvalue a, gccjit::rvalue b, \
250 gccjit::location loc)
251 gccjit::rvalue \
252 gccjit::context::new_modulo (gccjit::type result_type, \
253 gccjit::rvalue a, gccjit::rvalue b, \
254 gccjit::location loc)
255 gccjit::rvalue \
256 gccjit::context::new_bitwise_and (gccjit::type result_type, \
257 gccjit::rvalue a, gccjit::rvalue b, \
258 gccjit::location loc)
259 gccjit::rvalue \
260 gccjit::context::new_bitwise_xor (gccjit::type result_type, \
261 gccjit::rvalue a, gccjit::rvalue b, \
262 gccjit::location loc)
263 gccjit::rvalue \
264 gccjit::context::new_bitwise_or (gccjit::type result_type, \
265 gccjit::rvalue a, gccjit::rvalue b, \
266 gccjit::location loc)
267 gccjit::rvalue \
268 gccjit::context::new_logical_and (gccjit::type result_type, \
269 gccjit::rvalue a, gccjit::rvalue b, \
270 gccjit::location loc)
271 gccjit::rvalue \
272 gccjit::context::new_logical_or (gccjit::type result_type, \
273 gccjit::rvalue a, gccjit::rvalue b, \
274 gccjit::location loc)
275
276 The most concise way to spell them is with overloaded operators:
277
278 .. function:: gccjit::rvalue operator+ (gccjit::rvalue a, gccjit::rvalue b)
279
280 .. code-block:: c++
281
282 gccjit::rvalue sum = a + b;
283
284 .. function:: gccjit::rvalue operator- (gccjit::rvalue a, gccjit::rvalue b)
285
286 .. code-block:: c++
287
288 gccjit::rvalue diff = a - b;
289
290 .. function:: gccjit::rvalue operator* (gccjit::rvalue a, gccjit::rvalue b)
291
292 .. code-block:: c++
293
294 gccjit::rvalue prod = a * b;
295
296 .. function:: gccjit::rvalue operator/ (gccjit::rvalue a, gccjit::rvalue b)
297
298 .. code-block:: c++
299
300 gccjit::rvalue result = a / b;
301
302 .. function:: gccjit::rvalue operator% (gccjit::rvalue a, gccjit::rvalue b)
303
304 .. code-block:: c++
305
306 gccjit::rvalue mod = a % b;
307
308 .. function:: gccjit::rvalue operator& (gccjit::rvalue a, gccjit::rvalue b)
309
310 .. code-block:: c++
311
312 gccjit::rvalue x = a & b;
313
314 .. function:: gccjit::rvalue operator^ (gccjit::rvalue a, gccjit::rvalue b)
315
316 .. code-block:: c++
317
318 gccjit::rvalue x = a ^ b;
319
320 .. function:: gccjit::rvalue operator| (gccjit::rvalue a, gccjit::rvalue b)
321
322 .. code-block:: c++
323
324 gccjit::rvalue x = a | b;
325
326 .. function:: gccjit::rvalue operator&& (gccjit::rvalue a, gccjit::rvalue b)
327
328 .. code-block:: c++
329
330 gccjit::rvalue cond = a && b;
331
332 .. function:: gccjit::rvalue operator|| (gccjit::rvalue a, gccjit::rvalue b)
333
334 .. code-block:: c++
335
336 gccjit::rvalue cond = a || b;
337
338 These can of course be combined, giving a terse way to build compound
339 expressions:
340
341 .. code-block:: c++
342
343 gccjit::rvalue discriminant = (b * b) - (four * a * c);
344
345
346 Comparisons
347 ***********
348
349 .. function:: gccjit::rvalue \
350 gccjit::context::new_comparison (enum gcc_jit_comparison,\
351 gccjit::rvalue a, \
352 gccjit::rvalue b, \
353 gccjit::location loc)
354
355 Build a boolean rvalue out of the comparison of two other rvalues.
356
357 Parameter ``loc`` is optional.
358
359 This is a thin wrapper around the C API's
360 :c:func:`gcc_jit_context_new_comparison` and the available kinds
361 of comparison are documented there.
362
363 There are shorter ways to spell the various specific kinds of binary
364 operation:
365
366 .. function:: gccjit::rvalue \
367 gccjit::context::new_eq (gccjit::rvalue a, gccjit::rvalue b, \
368 gccjit::location loc)
369 gccjit::rvalue \
370 gccjit::context::new_ne (gccjit::rvalue a, gccjit::rvalue b, \
371 gccjit::location loc)
372 gccjit::rvalue \
373 gccjit::context::new_lt (gccjit::rvalue a, gccjit::rvalue b, \
374 gccjit::location loc)
375 gccjit::rvalue \
376 gccjit::context::new_le (gccjit::rvalue a, gccjit::rvalue b, \
377 gccjit::location loc)
378 gccjit::rvalue \
379 gccjit::context::new_gt (gccjit::rvalue a, gccjit::rvalue b, \
380 gccjit::location loc)
381 gccjit::rvalue \
382 gccjit::context::new_ge (gccjit::rvalue a, gccjit::rvalue b, \
383 gccjit::location loc)
384
385 The most concise way to spell them is with overloaded operators:
386
387 .. function:: gccjit::rvalue \
388 operator== (gccjit::rvalue a, gccjit::rvalue b)
389
390 .. code-block:: c++
391
392 gccjit::rvalue cond = (a == ctxt.zero (t_int));
393
394 .. function:: gccjit::rvalue \
395 operator!= (gccjit::rvalue a, gccjit::rvalue b)
396
397 .. code-block:: c++
398
399 gccjit::rvalue cond = (i != j);
400
401 .. function:: gccjit::rvalue \
402 operator< (gccjit::rvalue a, gccjit::rvalue b)
403
404 .. code-block:: c++
405
406 gccjit::rvalue cond = i < n;
407
408 .. function:: gccjit::rvalue \
409 operator<= (gccjit::rvalue a, gccjit::rvalue b)
410
411 .. code-block:: c++
412
413 gccjit::rvalue cond = i <= n;
414
415 .. function:: gccjit::rvalue \
416 operator> (gccjit::rvalue a, gccjit::rvalue b)
417
418 .. code-block:: c++
419
420 gccjit::rvalue cond = (ch > limit);
421
422 .. function:: gccjit::rvalue \
423 operator>= (gccjit::rvalue a, gccjit::rvalue b)
424
425 .. code-block:: c++
426
427 gccjit::rvalue cond = (score >= ctxt.new_rvalue (t_int, 100));
428
429 .. TODO: beyond this point
430
431 Function calls
432 **************
433 .. function:: gcc_jit_rvalue *\
434 gcc_jit_context_new_call (gcc_jit_context *ctxt,\
435 gcc_jit_location *loc,\
436 gcc_jit_function *func,\
437 int numargs , gcc_jit_rvalue **args)
438
439 Given a function and the given table of argument rvalues, construct a
440 call to the function, with the result as an rvalue.
441
442 .. note::
443
444 :func:`gccjit::context::new_call` merely builds a
445 :class:`gccjit::rvalue` i.e. an expression that can be evaluated,
446 perhaps as part of a more complicated expression.
447 The call *won't* happen unless you add a statement to a function
448 that evaluates the expression.
449
450 For example, if you want to call a function and discard the result
451 (or to call a function with ``void`` return type), use
452 :func:`gccjit::block::add_eval`:
453
454 .. code-block:: c++
455
456 /* Add "(void)printf (arg0, arg1);". */
457 block.add_eval (ctxt.new_call (printf_func, arg0, arg1));
458
459 Function pointers
460 *****************
461
462 .. function:: gccjit::rvalue \
463 gccjit::function::get_address (gccjit::location loc)
464
465 Get the address of a function as an rvalue, of function pointer
466 type.
467
468 Type-coercion
469 *************
470
471 .. function:: gccjit::rvalue \
472 gccjit::context::new_cast (gccjit::rvalue rvalue,\
473 gccjit::type type, \
474 gccjit::location loc)
475
476 Given an rvalue of T, construct another rvalue of another type.
477
478 Currently only a limited set of conversions are possible:
479
480 * int <-> float
481 * int <-> bool
482 * P* <-> Q*, for pointer types P and Q
483
484 Lvalues
485 -------
486
487 .. class:: gccjit::lvalue
488
489 An lvalue is something that can of the *left*-hand side of an assignment:
490 a storage area (such as a variable). It is a subclass of
491 :class:`gccjit::rvalue`, where the rvalue is computed by reading from the
492 storage area.
493
494 It iss a thin wrapper around :c:expr:`gcc_jit_lvalue *` from the C API.
495
496 .. function:: gccjit::rvalue \
497 gccjit::lvalue::get_address (gccjit::location loc)
498
499 Take the address of an lvalue; analogous to:
500
501 .. code-block:: c
502
503 &(EXPR)
504
505 in C.
506
507 Parameter "loc" is optional.
508
509 Global variables
510 ****************
511
512 .. function:: gccjit::lvalue \
513 gccjit::context::new_global (enum gcc_jit_global_kind,\
514 gccjit::type type, \
515 const char *name, \
516 gccjit::location loc)
517
518 Add a new global variable of the given type and name to the context.
519
520 This is a thin wrapper around :c:func:`gcc_jit_context_new_global` from
521 the C API; the "kind" parameter has the same meaning as there.
522
523 Working with pointers, structs and unions
524 -----------------------------------------
525
526 .. function:: gccjit::lvalue \
527 gccjit::rvalue::dereference (gccjit::location loc)
528
529 Given an rvalue of pointer type ``T *``, dereferencing the pointer,
530 getting an lvalue of type ``T``. Analogous to:
531
532 .. code-block:: c++
533
534 *(EXPR)
535
536 in C.
537
538 Parameter "loc" is optional.
539
540 If you don't need to specify the location, this can also be expressed using
541 an overloaded operator:
542
543 .. function:: gccjit::lvalue \
544 gccjit::rvalue::operator* ()
545
546 .. code-block:: c++
547
548 gccjit::lvalue content = *ptr;
549
550 Field access is provided separately for both lvalues and rvalues:
551
552 .. function:: gccjit::lvalue \
553 gccjit::lvalue::access_field (gccjit::field field, \
554 gccjit::location loc)
555
556 Given an lvalue of struct or union type, access the given field,
557 getting an lvalue of the field's type. Analogous to:
558
559 .. code-block:: c++
560
561 (EXPR).field = ...;
562
563 in C.
564
565 .. function:: gccjit::rvalue \
566 gccjit::rvalue::access_field (gccjit::field field, \
567 gccjit::location loc)
568
569 Given an rvalue of struct or union type, access the given field
570 as an rvalue. Analogous to:
571
572 .. code-block:: c++
573
574 (EXPR).field
575
576 in C.
577
578 .. function:: gccjit::lvalue \
579 gccjit::rvalue::dereference_field (gccjit::field field, \
580 gccjit::location loc)
581
582 Given an rvalue of pointer type ``T *`` where T is of struct or union
583 type, access the given field as an lvalue. Analogous to:
584
585 .. code-block:: c++
586
587 (EXPR)->field
588
589 in C, itself equivalent to ``(*EXPR).FIELD``.
590
591 .. function:: gccjit::lvalue \
592 gccjit::context::new_array_access (gccjit::rvalue ptr, \
593 gccjit::rvalue index, \
594 gccjit::location loc)
595
596 Given an rvalue of pointer type ``T *``, get at the element `T` at
597 the given index, using standard C array indexing rules i.e. each
598 increment of ``index`` corresponds to ``sizeof(T)`` bytes.
599 Analogous to:
600
601 .. code-block:: c++
602
603 PTR[INDEX]
604
605 in C (or, indeed, to ``PTR + INDEX``).
606
607 Parameter "loc" is optional.
608
609 For array accesses where you don't need to specify a :class:`gccjit::location`,
610 two overloaded operators are available:
611
612 gccjit::lvalue gccjit::rvalue::operator[] (gccjit::rvalue index)
613
614 .. code-block:: c++
615
616 gccjit::lvalue element = array[idx];
617
618 gccjit::lvalue gccjit::rvalue::operator[] (int index)
619
620 .. code-block:: c++
621
622 gccjit::lvalue element = array[0];