gcc/jit/docs/topics/expressions.rst

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