expressions.rst revision 1.1
1.. Copyright (C) 2014-2015 Free Software Foundation, Inc. 2 Originally contributed by David Malcolm <dmalcolm@redhat.com> 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 <http://www.gnu.org/licenses/>. 17 18.. default-domain:: c 19 20Expressions 21=========== 22 23Rvalues 24------- 25.. type:: gcc_jit_rvalue 26 27A :c:type:`gcc_jit_rvalue *` is an expression that can be computed. 28 29It can be simple, e.g.: 30 31 * an integer value e.g. `0` or `42` 32 * a string literal e.g. `"Hello world"` 33 * a variable e.g. `i`. These are also lvalues (see below). 34 35or compound e.g.: 36 37 * a unary expression e.g. `!cond` 38 * a binary expression e.g. `(a + b)` 39 * a function call e.g. `get_distance (&player_ship, &target)` 40 * etc. 41 42Every rvalue has an associated type, and the API will check to ensure 43that types match up correctly (otherwise the context will emit an error). 44 45.. function:: gcc_jit_type *gcc_jit_rvalue_get_type (gcc_jit_rvalue *rvalue) 46 47 Get the type of this rvalue. 48 49.. function:: gcc_jit_object *gcc_jit_rvalue_as_object (gcc_jit_rvalue *rvalue) 50 51 Upcast the given rvalue to be an object. 52 53 54Simple expressions 55****************** 56 57.. function:: gcc_jit_rvalue *\ 58 gcc_jit_context_new_rvalue_from_int (gcc_jit_context *ctxt, \ 59 gcc_jit_type *numeric_type, \ 60 int value) 61 62 Given a numeric type (integer or floating point), build an rvalue for 63 the given constant :c:type:`int` value. 64 65.. function:: gcc_jit_rvalue *\ 66 gcc_jit_context_new_rvalue_from_long (gcc_jit_context *ctxt, \ 67 gcc_jit_type *numeric_type, \ 68 long value) 69 70 Given a numeric type (integer or floating point), build an rvalue for 71 the given constant :c:type:`long` value. 72 73.. function:: gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context *ctxt, \ 74 gcc_jit_type *numeric_type) 75 76 Given a numeric type (integer or floating point), get the rvalue for 77 zero. Essentially this is just a shortcut for: 78 79 .. code-block:: c 80 81 gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 0) 82 83.. function:: gcc_jit_rvalue *gcc_jit_context_one (gcc_jit_context *ctxt, \ 84 gcc_jit_type *numeric_type) 85 86 Given a numeric type (integer or floating point), get the rvalue for 87 one. Essentially this is just a shortcut for: 88 89 .. code-block:: c 90 91 gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 1) 92 93.. function:: gcc_jit_rvalue *\ 94 gcc_jit_context_new_rvalue_from_double (gcc_jit_context *ctxt, \ 95 gcc_jit_type *numeric_type, \ 96 double value) 97 98 Given a numeric type (integer or floating point), build an rvalue for 99 the given constant :c:type:`double` value. 100 101.. function:: gcc_jit_rvalue *\ 102 gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context *ctxt, \ 103 gcc_jit_type *pointer_type, \ 104 void *value) 105 106 Given a pointer type, build an rvalue for the given address. 107 108.. function:: gcc_jit_rvalue *gcc_jit_context_null (gcc_jit_context *ctxt, \ 109 gcc_jit_type *pointer_type) 110 111 Given a pointer type, build an rvalue for ``NULL``. Essentially this 112 is just a shortcut for: 113 114 .. code-block:: c 115 116 gcc_jit_context_new_rvalue_from_ptr (ctxt, pointer_type, NULL) 117 118.. function:: gcc_jit_rvalue *\ 119 gcc_jit_context_new_string_literal (gcc_jit_context *ctxt, \ 120 const char *value) 121 122 Generate an rvalue for the given NIL-terminated string, of type 123 :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`. 124 125 The parameter ``value`` must be non-NULL. The call takes a copy of the 126 underlying string, so it is valid to pass in a pointer to an on-stack 127 buffer. 128 129Unary Operations 130**************** 131 132.. function:: gcc_jit_rvalue * \ 133 gcc_jit_context_new_unary_op (gcc_jit_context *ctxt, \ 134 gcc_jit_location *loc, \ 135 enum gcc_jit_unary_op op, \ 136 gcc_jit_type *result_type, \ 137 gcc_jit_rvalue *rvalue) 138 139 Build a unary operation out of an input rvalue. 140 141.. type:: enum gcc_jit_unary_op 142 143The available unary operations are: 144 145========================================== ============ 146Unary Operation C equivalent 147========================================== ============ 148:c:macro:`GCC_JIT_UNARY_OP_MINUS` `-(EXPR)` 149:c:macro:`GCC_JIT_UNARY_OP_BITWISE_NEGATE` `~(EXPR)` 150:c:macro:`GCC_JIT_UNARY_OP_LOGICAL_NEGATE` `!(EXPR)` 151:c:macro:`GCC_JIT_UNARY_OP_ABS` `abs (EXPR)` 152========================================== ============ 153 154.. c:macro:: GCC_JIT_UNARY_OP_MINUS 155 156 Negate an arithmetic value; analogous to: 157 158 .. code-block:: c 159 160 -(EXPR) 161 162 in C. 163 164.. c:macro:: GCC_JIT_UNARY_OP_BITWISE_NEGATE 165 166 Bitwise negation of an integer value (one's complement); analogous 167 to: 168 169 .. code-block:: c 170 171 ~(EXPR) 172 173 in C. 174 175.. c:macro:: GCC_JIT_UNARY_OP_LOGICAL_NEGATE 176 177 Logical negation of an arithmetic or pointer value; analogous to: 178 179 .. code-block:: c 180 181 !(EXPR) 182 183 in C. 184 185.. c:macro:: GCC_JIT_UNARY_OP_ABS 186 187 Absolute value of an arithmetic expression; analogous to: 188 189 .. code-block:: c 190 191 abs (EXPR) 192 193 in C. 194 195Binary Operations 196***************** 197 198.. function:: gcc_jit_rvalue *gcc_jit_context_new_binary_op (gcc_jit_context *ctxt, \ 199 gcc_jit_location *loc, \ 200 enum gcc_jit_binary_op op, \ 201 gcc_jit_type *result_type, \ 202 gcc_jit_rvalue *a, gcc_jit_rvalue *b) 203 204 Build a binary operation out of two constituent rvalues. 205 206.. type:: enum gcc_jit_binary_op 207 208The available binary operations are: 209 210======================================== ============ 211Binary Operation C equivalent 212======================================== ============ 213:c:macro:`GCC_JIT_BINARY_OP_PLUS` `x + y` 214:c:macro:`GCC_JIT_BINARY_OP_MINUS` `x - y` 215:c:macro:`GCC_JIT_BINARY_OP_MULT` `x * y` 216:c:macro:`GCC_JIT_BINARY_OP_DIVIDE` `x / y` 217:c:macro:`GCC_JIT_BINARY_OP_MODULO` `x % y` 218:c:macro:`GCC_JIT_BINARY_OP_BITWISE_AND` `x & y` 219:c:macro:`GCC_JIT_BINARY_OP_BITWISE_XOR` `x ^ y` 220:c:macro:`GCC_JIT_BINARY_OP_BITWISE_OR` `x | y` 221:c:macro:`GCC_JIT_BINARY_OP_LOGICAL_AND` `x && y` 222:c:macro:`GCC_JIT_BINARY_OP_LOGICAL_OR` `x || y` 223:c:macro:`GCC_JIT_BINARY_OP_LSHIFT` `x << y` 224:c:macro:`GCC_JIT_BINARY_OP_RSHIFT` `x >> y` 225======================================== ============ 226 227.. c:macro:: GCC_JIT_BINARY_OP_PLUS 228 229 Addition of arithmetic values; analogous to: 230 231 .. code-block:: c 232 233 (EXPR_A) + (EXPR_B) 234 235 in C. 236 237 For pointer addition, use :c:func:`gcc_jit_context_new_array_access`. 238 239.. c:macro:: GCC_JIT_BINARY_OP_MINUS 240 241 Subtraction of arithmetic values; analogous to: 242 243 .. code-block:: c 244 245 (EXPR_A) - (EXPR_B) 246 247 in C. 248 249.. c:macro:: GCC_JIT_BINARY_OP_MULT 250 251 Multiplication of a pair of arithmetic values; analogous to: 252 253 .. code-block:: c 254 255 (EXPR_A) * (EXPR_B) 256 257 in C. 258 259.. c:macro:: GCC_JIT_BINARY_OP_DIVIDE 260 261 Quotient of division of arithmetic values; analogous to: 262 263 .. code-block:: c 264 265 (EXPR_A) / (EXPR_B) 266 267 in C. 268 269 The result type affects the kind of division: if the result type is 270 integer-based, then the result is truncated towards zero, whereas 271 a floating-point result type indicates floating-point division. 272 273.. c:macro:: GCC_JIT_BINARY_OP_MODULO 274 275 Remainder of division of arithmetic values; analogous to: 276 277 .. code-block:: c 278 279 (EXPR_A) % (EXPR_B) 280 281 in C. 282 283.. c:macro:: GCC_JIT_BINARY_OP_BITWISE_AND 284 285 Bitwise AND; analogous to: 286 287 .. code-block:: c 288 289 (EXPR_A) & (EXPR_B) 290 291 in C. 292 293.. c:macro:: GCC_JIT_BINARY_OP_BITWISE_XOR 294 295 Bitwise exclusive OR; analogous to: 296 297 .. code-block:: c 298 299 (EXPR_A) ^ (EXPR_B) 300 301 in C. 302 303.. c:macro:: GCC_JIT_BINARY_OP_BITWISE_OR 304 305 Bitwise inclusive OR; analogous to: 306 307 .. code-block:: c 308 309 (EXPR_A) | (EXPR_B) 310 311 in C. 312 313.. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_AND 314 315 Logical AND; analogous to: 316 317 .. code-block:: c 318 319 (EXPR_A) && (EXPR_B) 320 321 in C. 322 323.. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_OR 324 325 Logical OR; analogous to: 326 327 .. code-block:: c 328 329 (EXPR_A) || (EXPR_B) 330 331 in C. 332 333.. c:macro:: GCC_JIT_BINARY_OP_LSHIFT 334 335 Left shift; analogous to: 336 337 .. code-block:: c 338 339 (EXPR_A) << (EXPR_B) 340 341 in C. 342 343.. c:macro:: GCC_JIT_BINARY_OP_RSHIFT 344 345 Right shift; analogous to: 346 347 .. code-block:: c 348 349 (EXPR_A) >> (EXPR_B) 350 351 in C. 352 353Comparisons 354*********** 355 356.. function:: gcc_jit_rvalue *\ 357 gcc_jit_context_new_comparison (gcc_jit_context *ctxt,\ 358 gcc_jit_location *loc,\ 359 enum gcc_jit_comparison op,\ 360 gcc_jit_rvalue *a, gcc_jit_rvalue *b) 361 362 Build a boolean rvalue out of the comparison of two other rvalues. 363 364.. type:: enum gcc_jit_comparison 365 366======================================= ============ 367Comparison C equivalent 368======================================= ============ 369:c:macro:`GCC_JIT_COMPARISON_EQ` `x == y` 370:c:macro:`GCC_JIT_COMPARISON_NE` `x != y` 371:c:macro:`GCC_JIT_COMPARISON_LT` `x < y` 372:c:macro:`GCC_JIT_COMPARISON_LE` `x <= y` 373:c:macro:`GCC_JIT_COMPARISON_GT` `x > y` 374:c:macro:`GCC_JIT_COMPARISON_GE` `x >= y` 375======================================= ============ 376 377 378Function calls 379************** 380.. function:: gcc_jit_rvalue *\ 381 gcc_jit_context_new_call (gcc_jit_context *ctxt,\ 382 gcc_jit_location *loc,\ 383 gcc_jit_function *func,\ 384 int numargs , gcc_jit_rvalue **args) 385 386 Given a function and the given table of argument rvalues, construct a 387 call to the function, with the result as an rvalue. 388 389 .. note:: 390 391 :c:func:`gcc_jit_context_new_call` merely builds a 392 :c:type:`gcc_jit_rvalue` i.e. an expression that can be evaluated, 393 perhaps as part of a more complicated expression. 394 The call *won't* happen unless you add a statement to a function 395 that evaluates the expression. 396 397 For example, if you want to call a function and discard the result 398 (or to call a function with ``void`` return type), use 399 :c:func:`gcc_jit_block_add_eval`: 400 401 .. code-block:: c 402 403 /* Add "(void)printf (arg0, arg1);". */ 404 gcc_jit_block_add_eval ( 405 block, NULL, 406 gcc_jit_context_new_call ( 407 ctxt, 408 NULL, 409 printf_func, 410 2, args)); 411 412Type-coercion 413************* 414 415.. function:: gcc_jit_rvalue *\ 416 gcc_jit_context_new_cast (gcc_jit_context *ctxt,\ 417 gcc_jit_location *loc,\ 418 gcc_jit_rvalue *rvalue,\ 419 gcc_jit_type *type) 420 421 Given an rvalue of T, construct another rvalue of another type. 422 423 Currently only a limited set of conversions are possible: 424 425 * int <-> float 426 * int <-> bool 427 * P* <-> Q*, for pointer types P and Q 428 429Lvalues 430------- 431 432.. type:: gcc_jit_lvalue 433 434An lvalue is something that can of the *left*-hand side of an assignment: 435a storage area (such as a variable). It is also usable as an rvalue, 436where the rvalue is computed by reading from the storage area. 437 438.. function:: gcc_jit_object *\ 439 gcc_jit_lvalue_as_object (gcc_jit_lvalue *lvalue) 440 441 Upcast an lvalue to be an object. 442 443.. function:: gcc_jit_rvalue *\ 444 gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue *lvalue) 445 446 Upcast an lvalue to be an rvalue. 447 448.. function:: gcc_jit_rvalue *\ 449 gcc_jit_lvalue_get_address (gcc_jit_lvalue *lvalue,\ 450 gcc_jit_location *loc) 451 452 Take the address of an lvalue; analogous to: 453 454 .. code-block:: c 455 456 &(EXPR) 457 458 in C. 459 460Global variables 461**************** 462 463.. function:: gcc_jit_lvalue *\ 464 gcc_jit_context_new_global (gcc_jit_context *ctxt,\ 465 gcc_jit_location *loc,\ 466 enum gcc_jit_global_kind kind,\ 467 gcc_jit_type *type,\ 468 const char *name) 469 470 Add a new global variable of the given type and name to the context. 471 472 The parameter ``name`` must be non-NULL. The call takes a copy of the 473 underlying string, so it is valid to pass in a pointer to an on-stack 474 buffer. 475 476 The "kind" parameter determines the visibility of the "global" outside 477 of the :c:type:`gcc_jit_result`: 478 479 .. type:: enum gcc_jit_global_kind 480 481 .. c:macro:: GCC_JIT_GLOBAL_EXPORTED 482 483 Global is defined by the client code and is visible 484 by name outside of this JIT context via 485 :c:func:`gcc_jit_result_get_global` (and this value is required for 486 the global to be accessible via that entrypoint). 487 488 .. c:macro:: GCC_JIT_GLOBAL_INTERNAL 489 490 Global is defined by the client code, but is invisible 491 outside of it. Analogous to a "static" global within a .c file. 492 Specifically, the variable will only be visible within this 493 context and within child contexts. 494 495 .. c:macro:: GCC_JIT_GLOBAL_IMPORTED 496 497 Global is not defined by the client code; we're merely 498 referring to it. Analogous to using an "extern" global from a 499 header file. 500 501Working with pointers, structs and unions 502----------------------------------------- 503 504.. function:: gcc_jit_lvalue *\ 505 gcc_jit_rvalue_dereference (gcc_jit_rvalue *rvalue,\ 506 gcc_jit_location *loc) 507 508 Given an rvalue of pointer type ``T *``, dereferencing the pointer, 509 getting an lvalue of type ``T``. Analogous to: 510 511 .. code-block:: c 512 513 *(EXPR) 514 515 in C. 516 517Field access is provided separately for both lvalues and rvalues. 518 519.. function:: gcc_jit_lvalue *\ 520 gcc_jit_lvalue_access_field (gcc_jit_lvalue *struct_,\ 521 gcc_jit_location *loc,\ 522 gcc_jit_field *field) 523 524 Given an lvalue of struct or union type, access the given field, 525 getting an lvalue of the field's type. Analogous to: 526 527 .. code-block:: c 528 529 (EXPR).field = ...; 530 531 in C. 532 533.. function:: gcc_jit_rvalue *\ 534 gcc_jit_rvalue_access_field (gcc_jit_rvalue *struct_,\ 535 gcc_jit_location *loc,\ 536 gcc_jit_field *field) 537 538 Given an rvalue of struct or union type, access the given field 539 as an rvalue. Analogous to: 540 541 .. code-block:: c 542 543 (EXPR).field 544 545 in C. 546 547.. function:: gcc_jit_lvalue *\ 548 gcc_jit_rvalue_dereference_field (gcc_jit_rvalue *ptr,\ 549 gcc_jit_location *loc,\ 550 gcc_jit_field *field) 551 552 Given an rvalue of pointer type ``T *`` where T is of struct or union 553 type, access the given field as an lvalue. Analogous to: 554 555 .. code-block:: c 556 557 (EXPR)->field 558 559 in C, itself equivalent to ``(*EXPR).FIELD``. 560 561.. function:: gcc_jit_lvalue *\ 562 gcc_jit_context_new_array_access (gcc_jit_context *ctxt,\ 563 gcc_jit_location *loc,\ 564 gcc_jit_rvalue *ptr,\ 565 gcc_jit_rvalue *index) 566 567 Given an rvalue of pointer type ``T *``, get at the element `T` at 568 the given index, using standard C array indexing rules i.e. each 569 increment of ``index`` corresponds to ``sizeof(T)`` bytes. 570 Analogous to: 571 572 .. code-block:: c 573 574 PTR[INDEX] 575 576 in C (or, indeed, to ``PTR + INDEX``). 577