gcc/jit/docs/topics/expressions.rst

   1 .. Copyright (C) 2014 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 value.
  64
  65 .. function::  gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context *ctxt, \
  66                                                      gcc_jit_type *numeric_type)
  67
  68    Given a numeric type (integer or floating point), get the rvalue for
  69    zero.  Essentially this is just a shortcut for:
  70
  71    .. code-block:: c
  72
  73       gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 0)
  74
  75 .. function::  gcc_jit_rvalue *gcc_jit_context_one (gcc_jit_context *ctxt, \
  76                                                     gcc_jit_type *numeric_type)
  77
  78    Given a numeric type (integer or floating point), get the rvalue for
  79    zero.  Essentially this is just a shortcut for:
  80
  81    .. code-block:: c
  82
  83       gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 1)
  84
  85 .. function::  gcc_jit_rvalue *\
  86                gcc_jit_context_new_rvalue_from_double (gcc_jit_context *ctxt, \
  87                                                        gcc_jit_type *numeric_type, \
  88                                                        double value)
  89
  90    Given a numeric type (integer or floating point), build an rvalue for
  91    the given constant value.
  92
  93 .. function:: gcc_jit_rvalue *\
  94               gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context *ctxt, \
  95                                                    gcc_jit_type *pointer_type, \
  96                                                    void *value)
  97
  98    Given a pointer type, build an rvalue for the given address.
  99
 100 .. function:: gcc_jit_rvalue *gcc_jit_context_null (gcc_jit_context *ctxt, \
 101                                                     gcc_jit_type *pointer_type)
 102
 103    Given a pointer type, build an rvalue for ``NULL``.  Essentially this
 104    is just a shortcut for:
 105
 106    .. code-block:: c
 107
 108       gcc_jit_context_new_rvalue_from_ptr (ctxt, pointer_type, NULL)
 109
 110 .. function:: gcc_jit_rvalue *\
 111               gcc_jit_context_new_string_literal (gcc_jit_context *ctxt, \
 112                                                   const char *value)
 113
 114    Generate an rvalue for the given NIL-terminated string, of type
 115    :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`.
 116
 117
 118 Unary Operations
 119 ****************
 120
 121 .. function:: gcc_jit_rvalue * \
 122               gcc_jit_context_new_unary_op (gcc_jit_context *ctxt, \
 123                                             gcc_jit_location *loc, \
 124                                             enum gcc_jit_unary_op op, \
 125                                             gcc_jit_type *result_type, \
 126                                             gcc_jit_rvalue *rvalue)
 127
 128    Build a unary operation out of an input rvalue.
 129
 130 .. type:: enum gcc_jit_unary_op
 131
 132 The available unary operations are:
 133
 134 ==========================================  ============
 135 Unary Operation                             C equivalent
 136 ==========================================  ============
 137 :c:macro:`GCC_JIT_UNARY_OP_MINUS`           `-(EXPR)`
 138 :c:macro:`GCC_JIT_UNARY_OP_BITWISE_NEGATE`  `~(EXPR)`
 139 :c:macro:`GCC_JIT_UNARY_OP_LOGICAL_NEGATE`  `!(EXPR)`
 140 ==========================================  ============
 141
 142 .. c:macro:: GCC_JIT_UNARY_OP_MINUS
 143
 144     Negate an arithmetic value; analogous to:
 145
 146     .. code-block:: c
 147
 148        -(EXPR)
 149
 150     in C.
 151
 152 .. c:macro:: GCC_JIT_UNARY_OP_BITWISE_NEGATE
 153
 154     Bitwise negation of an integer value (one's complement); analogous
 155     to:
 156
 157     .. code-block:: c
 158
 159        ~(EXPR)
 160
 161     in C.
 162
 163 .. c:macro:: GCC_JIT_UNARY_OP_LOGICAL_NEGATE
 164
 165     Logical negation of an arithmetic or pointer value; analogous to:
 166
 167     .. code-block:: c
 168
 169        !(EXPR)
 170
 171     in C.
 172
 173 Binary Operations
 174 *****************
 175
 176 .. function:: gcc_jit_rvalue *gcc_jit_context_new_binary_op (gcc_jit_context *ctxt, \
 177                                                              gcc_jit_location *loc, \
 178                                                              enum gcc_jit_binary_op op, \
 179                                                              gcc_jit_type *result_type, \
 180                                                              gcc_jit_rvalue *a, gcc_jit_rvalue *b)
 181
 182    Build a binary operation out of two constituent rvalues.
 183
 184 .. type:: enum gcc_jit_binary_op
 185
 186 The available binary operations are:
 187
 188 ========================================  ============
 189 Binary Operation                          C equivalent
 190 ========================================  ============
 191 :c:macro:`GCC_JIT_BINARY_OP_PLUS`         `x + y`
 192 :c:macro:`GCC_JIT_BINARY_OP_MINUS`        `x - y`
 193 :c:macro:`GCC_JIT_BINARY_OP_MULT`         `x * y`
 194 :c:macro:`GCC_JIT_BINARY_OP_DIVIDE`       `x / y`
 195 :c:macro:`GCC_JIT_BINARY_OP_MODULO`       `x % y`
 196 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_AND`  `x & y`
 197 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_XOR`  `x ^ y`
 198 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_OR`   `x | y`
 199 :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_AND`  `x && y`
 200 :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_OR`   `x || y`
 201 :c:macro:`GCC_JIT_BINARY_OP_LSHIFT`       `x << y`
 202 :c:macro:`GCC_JIT_BINARY_OP_RSHIFT`       `x >> y`
 203 ========================================  ============
 204
 205 .. c:macro:: GCC_JIT_BINARY_OP_PLUS
 206
 207    Addition of arithmetic values; analogous to:
 208
 209    .. code-block:: c
 210
 211      (EXPR_A) + (EXPR_B)
 212
 213    in C.
 214
 215    For pointer addition, use :c:func:`gcc_jit_context_new_array_access`.
 216
 217 .. c:macro:: GCC_JIT_BINARY_OP_MINUS`
 218
 219    Subtraction of arithmetic values; analogous to:
 220
 221    .. code-block:: c
 222
 223      (EXPR_A) - (EXPR_B)
 224
 225    in C.
 226
 227 .. c:macro:: GCC_JIT_BINARY_OP_MULT
 228
 229    Multiplication of a pair of arithmetic values; analogous to:
 230
 231    .. code-block:: c
 232
 233      (EXPR_A) * (EXPR_B)
 234
 235    in C.
 236
 237 .. c:macro:: GCC_JIT_BINARY_OP_DIVIDE
 238
 239    Quotient of division of arithmetic values; analogous to:
 240
 241    .. code-block:: c
 242
 243      (EXPR_A) / (EXPR_B)
 244
 245    in C.
 246
 247    The result type affects the kind of division: if the result type is
 248    integer-based, then the result is truncated towards zero, whereas
 249    a floating-point result type indicates floating-point division.
 250
 251 .. c:macro:: GCC_JIT_BINARY_OP_MODULO
 252
 253    Remainder of division of arithmetic values; analogous to:
 254
 255    .. code-block:: c
 256
 257      (EXPR_A) % (EXPR_B)
 258
 259    in C.
 260
 261 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_AND
 262
 263    Bitwise AND; analogous to:
 264
 265    .. code-block:: c
 266
 267      (EXPR_A) & (EXPR_B)
 268
 269    in C.
 270
 271 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_XOR
 272
 273    Bitwise exclusive OR; analogous to:
 274
 275    .. code-block:: c
 276
 277       (EXPR_A) ^ (EXPR_B)
 278
 279    in C.
 280
 281 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_OR
 282
 283    Bitwise inclusive OR; analogous to:
 284
 285    .. code-block:: c
 286
 287      (EXPR_A) | (EXPR_B)
 288
 289    in C.
 290
 291 .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_AND
 292
 293    Logical AND; analogous to:
 294
 295    .. code-block:: c
 296
 297      (EXPR_A) && (EXPR_B)
 298
 299    in C.
 300
 301 .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_OR
 302
 303    Logical OR; analogous to:
 304
 305    .. code-block:: c
 306
 307      (EXPR_A) || (EXPR_B)
 308
 309    in C.
 310
 311 .. c:macro:: GCC_JIT_BINARY_OP_LSHIFT
 312
 313    Left shift; analogous to:
 314
 315    .. code-block:: c
 316
 317      (EXPR_A) << (EXPR_B)
 318
 319    in C.
 320
 321 .. c:macro:: GCC_JIT_BINARY_OP_RSHIFT
 322
 323    Right shift; analogous to:
 324
 325    .. code-block:: c
 326
 327      (EXPR_A) >> (EXPR_B)
 328
 329    in C.
 330
 331 Comparisons
 332 ***********
 333
 334 .. function:: gcc_jit_rvalue *\
 335               gcc_jit_context_new_comparison (gcc_jit_context *ctxt,\
 336                                               gcc_jit_location *loc,\
 337                                               enum gcc_jit_comparison op,\
 338                                               gcc_jit_rvalue *a, gcc_jit_rvalue *b)
 339
 340    Build a boolean rvalue out of the comparison of two other rvalues.
 341
 342 .. type:: enum gcc_jit_comparison
 343
 344 =======================================  ============
 345 Comparison                               C equivalent
 346 =======================================  ============
 347 :c:macro:`GCC_JIT_COMPARISON_EQ`         `x == y`
 348 :c:macro:`GCC_JIT_COMPARISON_NE`         `x != y`
 349 :c:macro:`GCC_JIT_COMPARISON_LT`         `x < y`
 350 :c:macro:`GCC_JIT_COMPARISON_LE`         `x <= y`
 351 :c:macro:`GCC_JIT_COMPARISON_GT`         `x > y`
 352 :c:macro:`GCC_JIT_COMPARISON_GE`         `x >= y`
 353 =======================================  ============
 354
 355
 356 Function calls
 357 **************
 358 .. function:: gcc_jit_rvalue *\
 359               gcc_jit_context_new_call (gcc_jit_context *ctxt,\
 360                                         gcc_jit_location *loc,\
 361                                         gcc_jit_function *func,\
 362                                         int numargs , gcc_jit_rvalue **args)
 363
 364    Given a function and the given table of argument rvalues, construct a
 365    call to the function, with the result as an rvalue.
 366
 367    .. note::
 368
 369       :c:func:`gcc_jit_context_new_call` merely builds a
 370       :c:type:`gcc_jit_rvalue` i.e. an expression that can be evaluated,
 371       perhaps as part of a more complicated expression.
 372       The call *won't* happen unless you add a statement to a function
 373       that evaluates the expression.
 374
 375       For example, if you want to call a function and discard the result
 376       (or to call a function with ``void`` return type), use
 377       :c:func:`gcc_jit_block_add_eval`:
 378
 379       .. code-block:: c
 380
 381          /* Add "(void)printf (arg0, arg1);".  */
 382          gcc_jit_block_add_eval (
 383            block, NULL,
 384            gcc_jit_context_new_call (
 385              ctxt,
 386              NULL,
 387              printf_func,
 388              2, args));
 389
 390 Type-coercion
 391 *************
 392
 393 .. function:: gcc_jit_rvalue *\
 394               gcc_jit_context_new_cast (gcc_jit_context *ctxt,\
 395                                         gcc_jit_location *loc,\
 396                                         gcc_jit_rvalue *rvalue,\
 397                                         gcc_jit_type *type)
 398
 399    Given an rvalue of T, construct another rvalue of another type.
 400
 401    Currently only a limited set of conversions are possible:
 402
 403      * int <-> float
 404      * int <-> bool
 405      * P*  <-> Q*, for pointer types P and Q
 406
 407 Lvalues
 408 -------
 409
 410 .. type:: gcc_jit_lvalue
 411
 412 An lvalue is something that can of the *left*-hand side of an assignment:
 413 a storage area (such as a variable).  It is also usable as an rvalue,
 414 where the rvalue is computed by reading from the storage area.
 415
 416 .. function:: gcc_jit_object *\
 417               gcc_jit_lvalue_as_object (gcc_jit_lvalue *lvalue)
 418
 419    Upcast an lvalue to be an object.
 420
 421 .. function:: gcc_jit_rvalue *\
 422               gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue *lvalue)
 423
 424    Upcast an lvalue to be an rvalue.
 425
 426 .. function:: gcc_jit_rvalue *\
 427               gcc_jit_lvalue_get_address (gcc_jit_lvalue *lvalue,\
 428                                           gcc_jit_location *loc)
 429
 430    Take the address of an lvalue; analogous to:
 431
 432    .. code-block:: c
 433
 434      &(EXPR)
 435
 436    in C.
 437
 438 Global variables
 439 ****************
 440
 441 .. function:: gcc_jit_lvalue *\
 442               gcc_jit_context_new_global (gcc_jit_context *ctxt,\
 443                                           gcc_jit_location *loc,\
 444                                           gcc_jit_type *type,\
 445                                           const char *name)
 446
 447    Add a new global variable of the given type and name to the context.
 448
 449
 450 Working with pointers, structs and unions
 451 -----------------------------------------
 452
 453 .. function:: gcc_jit_lvalue *\
 454               gcc_jit_rvalue_dereference (gcc_jit_rvalue *rvalue,\
 455                                           gcc_jit_location *loc)
 456
 457    Given an rvalue of pointer type ``T *``, dereferencing the pointer,
 458    getting an lvalue of type ``T``.  Analogous to:
 459
 460    .. code-block:: c
 461
 462      *(EXPR)
 463
 464    in C.
 465
 466 Field access is provided separately for both lvalues and rvalues.
 467
 468 .. function:: gcc_jit_lvalue *\
 469               gcc_jit_lvalue_access_field (gcc_jit_lvalue *struct_,\
 470                                            gcc_jit_location *loc,\
 471                                            gcc_jit_field *field)
 472
 473    Given an lvalue of struct or union type, access the given field,
 474    getting an lvalue of the field's type.  Analogous to:
 475
 476    .. code-block:: c
 477
 478       (EXPR).field = ...;
 479
 480    in C.
 481
 482 .. function:: gcc_jit_rvalue *\
 483               gcc_jit_rvalue_access_field (gcc_jit_rvalue *struct_,\
 484                                            gcc_jit_location *loc,\
 485                                            gcc_jit_field *field)
 486
 487    Given an rvalue of struct or union type, access the given field
 488    as an rvalue.  Analogous to:
 489
 490    .. code-block:: c
 491
 492       (EXPR).field
 493
 494    in C.
 495
 496 .. function:: gcc_jit_lvalue *\
 497               gcc_jit_rvalue_dereference_field (gcc_jit_rvalue *ptr,\
 498                                                 gcc_jit_location *loc,\
 499                                                 gcc_jit_field *field)
 500
 501    Given an rvalue of pointer type ``T *`` where T is of struct or union
 502    type, access the given field as an lvalue.  Analogous to:
 503
 504    .. code-block:: c
 505
 506       (EXPR)->field
 507
 508    in C, itself equivalent to ``(*EXPR).FIELD``.
 509
 510 .. function:: gcc_jit_lvalue *\
 511               gcc_jit_context_new_array_access (gcc_jit_context *ctxt,\
 512                                                 gcc_jit_location *loc,\
 513                                                 gcc_jit_rvalue *ptr,\
 514                                                 gcc_jit_rvalue *index)
 515
 516    Given an rvalue of pointer type ``T *``, get at the element `T` at
 517    the given index, using standard C array indexing rules i.e. each
 518    increment of ``index`` corresponds to ``sizeof(T)`` bytes.
 519    Analogous to:
 520
 521    .. code-block:: c
 522
 523       PTR[INDEX]
 524
 525    in C (or, indeed, to ``PTR + INDEX``).