docs/topics/expressions.rst

.. Copyright (C) 2014-2022 Free Software Foundation, Inc.
   Originally contributed by David Malcolm <dmalcolm (a] redhat.com>

   This is free software: you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see
   <https://www.gnu.org/licenses/>.

.. default-domain:: c

Expressions
===========

Rvalues
-------
.. type:: gcc_jit_rvalue

A :c:type:`gcc_jit_rvalue` is an expression that can be computed.

It can be simple, e.g.:

  * an integer value e.g. `0` or `42`
  * a string literal e.g. `"Hello world"`
  * a variable e.g. `i`.  These are also lvalues (see below).

or compound e.g.:

  * a unary expression e.g. `!cond`
  * a binary expression e.g. `(a + b)`
  * a function call e.g. `get_distance (&player_ship, &target)`
  * etc.

Every rvalue has an associated type, and the API will check to ensure
that types match up correctly (otherwise the context will emit an error).

.. function:: gcc_jit_type *gcc_jit_rvalue_get_type (gcc_jit_rvalue *rvalue)

  Get the type of this rvalue.

.. function:: gcc_jit_object *gcc_jit_rvalue_as_object (gcc_jit_rvalue *rvalue)

  Upcast the given rvalue to be an object.


Simple expressions
******************

.. function:: gcc_jit_rvalue *\
              gcc_jit_context_new_rvalue_from_int (gcc_jit_context *ctxt, \
                                                   gcc_jit_type *numeric_type, \
                                                   int value)

   Given a numeric type (integer or floating point), build an rvalue for
   the given constant :c:type:`int` value.

.. function:: gcc_jit_rvalue *\
              gcc_jit_context_new_rvalue_from_long (gcc_jit_context *ctxt, \
                                                    gcc_jit_type *numeric_type, \
                                                    long value)

   Given a numeric type (integer or floating point), build an rvalue for
   the given constant :c:type:`long` value.

.. function::  gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context *ctxt, \
                                                     gcc_jit_type *numeric_type)

   Given a numeric type (integer or floating point), get the rvalue for
   zero.  Essentially this is just a shortcut for:

   .. code-block:: c

      gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 0)

.. function::  gcc_jit_rvalue *gcc_jit_context_one (gcc_jit_context *ctxt, \
                                                    gcc_jit_type *numeric_type)

   Given a numeric type (integer or floating point), get the rvalue for
   one.  Essentially this is just a shortcut for:

   .. code-block:: c

      gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 1)

.. function::  gcc_jit_rvalue *\
               gcc_jit_context_new_rvalue_from_double (gcc_jit_context *ctxt, \
                                                       gcc_jit_type *numeric_type, \
                                                       double value)

   Given a numeric type (integer or floating point), build an rvalue for
   the given constant :c:type:`double` value.

.. function:: gcc_jit_rvalue *\
              gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context *ctxt, \
                                                   gcc_jit_type *pointer_type, \
                                                   void *value)

   Given a pointer type, build an rvalue for the given address.

.. function:: gcc_jit_rvalue *gcc_jit_context_null (gcc_jit_context *ctxt, \
                                                    gcc_jit_type *pointer_type)

   Given a pointer type, build an rvalue for ``NULL``.  Essentially this
   is just a shortcut for:

   .. code-block:: c

      gcc_jit_context_new_rvalue_from_ptr (ctxt, pointer_type, NULL)

.. function:: gcc_jit_rvalue *\
              gcc_jit_context_new_string_literal (gcc_jit_context *ctxt, \
                                                  const char *value)

   Generate an rvalue for the given NIL-terminated string, of type
   :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`.

   The parameter ``value`` must be non-NULL.  The call takes a copy of the
   underlying string, so it is valid to pass in a pointer to an on-stack
   buffer.

Constructor expressions
***********************

   The following functions make constructors for array, struct and union
   types.

   The constructor rvalue can be used for assignment to locals.
   It can be used to initialize global variables with
   :func:`gcc_jit_global_set_initializer_rvalue`. It can also be used as a
   temporary value for function calls and return values, but its address
   can't be taken.

   Note that arrays in libgccjit do not collapse to pointers like in
   C. I.e. if an array constructor is used as e.g. a return value, the whole
   array would be returned by value - array constructors can be assigned to
   array variables.

   The constructor can contain nested constructors.

   Note that a string literal rvalue can't be used to construct a char array;
   the latter needs one rvalue for each char.

   These entrypoints were added in :ref:`LIBGCCJIT_ABI_19`; you can test for
   their presence using:

   .. code-block:: c

     #ifdef LIBGCCJIT_HAVE_CTORS

.. function:: gcc_jit_rvalue *\
	      gcc_jit_context_new_array_constructor (gcc_jit_context *ctxt,\
						     gcc_jit_location *loc,\
						     gcc_jit_type *type,\
						     size_t num_values,\
						     gcc_jit_rvalue **values)

   Create a constructor for an array as an rvalue.

   Returns NULL on error. ``values`` are copied and
   do not have to outlive the context.

   ``type`` specifies what the constructor will build and has to be
   an array.

   ``num_values`` specifies the number of elements in ``values`` and
   it can't have more elements than the array type.

   Each value in ``values`` sets the corresponding value in the array.
   If the array type itself has more elements than ``values``, the
   left-over elements will be zeroed.

   Each value in ``values`` need to be the same unqualified type as the
   array type's element type.

   If ``num_values`` is 0, the ``values`` parameter will be
   ignored and zero initialization will be used.

   This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its
   presence using:

   .. code-block:: c

     #ifdef LIBGCCJIT_HAVE_CTORS

.. function:: gcc_jit_rvalue *\
	      gcc_jit_context_new_struct_constructor (gcc_jit_context *ctxt,\
						      gcc_jit_location *loc,\
						      gcc_jit_type *type,\
						      size_t num_values,\
						      gcc_jit_field **fields,\
						      gcc_jit_rvalue **values)


   Create a constructor for a struct as an rvalue.

   Returns NULL on error. The two parameter arrays are copied and
   do not have to outlive the context.

   ``type`` specifies what the constructor will build and has to be
   a struct.

   ``num_values`` specifies the number of elements in ``values``.

   ``fields`` need to have the same length as ``values``, or be NULL.

   If ``fields`` is null, the values are applied in definition order.

   Otherwise, each field in ``fields`` specifies which field in the struct to
   set to the corresponding value in ``values``. ``fields`` and ``values``
   are paired by index.

   The fields in ``fields`` have to be in definition order, but there
   can be gaps. Any field in the struct that is not specified in
   ``fields`` will be zeroed.

   The fields in ``fields`` need to be the same objects that were used
   to create the struct.

   Each value has to have have the same unqualified type as the field
   it is applied to.

   A NULL value element  in ``values`` is a shorthand for zero initialization
   of the corresponding field.

   If ``num_values`` is 0, the array parameters will be
   ignored and zero initialization will be used.

   This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its
   presence using:

   .. code-block:: c

     #ifdef LIBGCCJIT_HAVE_CTORS

.. function:: gcc_jit_rvalue *\
	      gcc_jit_context_new_union_constructor (gcc_jit_context *ctxt,\
						     gcc_jit_location *loc,\
						     gcc_jit_type *type,\
						     gcc_jit_field *field,\
						     gcc_jit_rvalue *value)

   Create a constructor for a union as an rvalue.

   Returns NULL on error.

   ``type`` specifies what the constructor will build and has to be
   an union.

   ``field`` specifies which field to set. If it is NULL, the first
   field in the union will be set.``field`` need to be the same object
   that were used to create the union.

   ``value`` specifies what value to set the corresponding field to.
   If ``value`` is NULL, zero initialization will be used.

   Each value has to have have the same unqualified type as the field
   it is applied to.

   This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its
   presence using:

   .. code-block:: c

     #ifdef LIBGCCJIT_HAVE_CTORS

Vector expressions
******************

.. function:: gcc_jit_rvalue * \
              gcc_jit_context_new_rvalue_from_vector (gcc_jit_context *ctxt, \
                                                      gcc_jit_location *loc, \
                                                      gcc_jit_type *vec_type, \
                                                      size_t num_elements, \
                                                      gcc_jit_rvalue **elements)

   Build a vector rvalue from an array of elements.

   "vec_type" should be a vector type, created using
   :func:`gcc_jit_type_get_vector`.

   "num_elements" should match that of the vector type.

   This entrypoint was added in :ref:`LIBGCCJIT_ABI_10`; you can test for
   its presence using

   .. code-block:: c

      #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_rvalue_from_vector

Unary Operations
****************

.. function:: gcc_jit_rvalue * \
              gcc_jit_context_new_unary_op (gcc_jit_context *ctxt, \
                                            gcc_jit_location *loc, \
                                            enum gcc_jit_unary_op op, \
                                            gcc_jit_type *result_type, \
                                            gcc_jit_rvalue *rvalue)

   Build a unary operation out of an input rvalue.

   The parameter ``result_type`` must be a numeric type.

.. type:: enum gcc_jit_unary_op

The available unary operations are:

==========================================  ============
Unary Operation                             C equivalent
==========================================  ============
:c:macro:`GCC_JIT_UNARY_OP_MINUS`           `-(EXPR)`
:c:macro:`GCC_JIT_UNARY_OP_BITWISE_NEGATE`  `~(EXPR)`
:c:macro:`GCC_JIT_UNARY_OP_LOGICAL_NEGATE`  `!(EXPR)`
:c:macro:`GCC_JIT_UNARY_OP_ABS`             `abs (EXPR)`
==========================================  ============

.. c:macro:: GCC_JIT_UNARY_OP_MINUS

    Negate an arithmetic value; analogous to:

    .. code-block:: c

       -(EXPR)

    in C.

.. c:macro:: GCC_JIT_UNARY_OP_BITWISE_NEGATE

    Bitwise negation of an integer value (one's complement); analogous
    to:

    .. code-block:: c

       ~(EXPR)

    in C.

.. c:macro:: GCC_JIT_UNARY_OP_LOGICAL_NEGATE

    Logical negation of an arithmetic or pointer value; analogous to:

    .. code-block:: c

       !(EXPR)

    in C.

.. c:macro:: GCC_JIT_UNARY_OP_ABS

    Absolute value of an arithmetic expression; analogous to:

    .. code-block:: c

        abs (EXPR)

    in C.

Binary Operations
*****************

.. function:: gcc_jit_rvalue *gcc_jit_context_new_binary_op (gcc_jit_context *ctxt, \
                                                             gcc_jit_location *loc, \
                                                             enum gcc_jit_binary_op op, \
                                                             gcc_jit_type *result_type, \
                                                             gcc_jit_rvalue *a, gcc_jit_rvalue *b)

   Build a binary operation out of two constituent rvalues.

   The parameter ``result_type`` must be a numeric type.

.. type:: enum gcc_jit_binary_op

The available binary operations are:

========================================  ============
Binary Operation                          C equivalent
========================================  ============
:c:macro:`GCC_JIT_BINARY_OP_PLUS`         `x + y`
:c:macro:`GCC_JIT_BINARY_OP_MINUS`        `x - y`
:c:macro:`GCC_JIT_BINARY_OP_MULT`         `x * y`
:c:macro:`GCC_JIT_BINARY_OP_DIVIDE`       `x / y`
:c:macro:`GCC_JIT_BINARY_OP_MODULO`       `x % y`
:c:macro:`GCC_JIT_BINARY_OP_BITWISE_AND`  `x & y`
:c:macro:`GCC_JIT_BINARY_OP_BITWISE_XOR`  `x ^ y`
:c:macro:`GCC_JIT_BINARY_OP_BITWISE_OR`   `x | y`
:c:macro:`GCC_JIT_BINARY_OP_LOGICAL_AND`  `x && y`
:c:macro:`GCC_JIT_BINARY_OP_LOGICAL_OR`   `x || y`
:c:macro:`GCC_JIT_BINARY_OP_LSHIFT`       `x << y`
:c:macro:`GCC_JIT_BINARY_OP_RSHIFT`       `x >> y`
========================================  ============

.. c:macro:: GCC_JIT_BINARY_OP_PLUS

   Addition of arithmetic values; analogous to:

   .. code-block:: c

     (EXPR_A) + (EXPR_B)

   in C.

   For pointer addition, use :c:func:`gcc_jit_context_new_array_access`.

.. c:macro:: GCC_JIT_BINARY_OP_MINUS

   Subtraction of arithmetic values; analogous to:

   .. code-block:: c

     (EXPR_A) - (EXPR_B)

   in C.

.. c:macro:: GCC_JIT_BINARY_OP_MULT

   Multiplication of a pair of arithmetic values; analogous to:

   .. code-block:: c

     (EXPR_A) * (EXPR_B)

   in C.

.. c:macro:: GCC_JIT_BINARY_OP_DIVIDE

   Quotient of division of arithmetic values; analogous to:

   .. code-block:: c

     (EXPR_A) / (EXPR_B)

   in C.

   The result type affects the kind of division: if the result type is
   integer-based, then the result is truncated towards zero, whereas
   a floating-point result type indicates floating-point division.

.. c:macro:: GCC_JIT_BINARY_OP_MODULO

   Remainder of division of arithmetic values; analogous to:

   .. code-block:: c

     (EXPR_A) % (EXPR_B)

   in C.

.. c:macro:: GCC_JIT_BINARY_OP_BITWISE_AND

   Bitwise AND; analogous to:

   .. code-block:: c

     (EXPR_A) & (EXPR_B)

   in C.

.. c:macro:: GCC_JIT_BINARY_OP_BITWISE_XOR

   Bitwise exclusive OR; analogous to:

   .. code-block:: c

      (EXPR_A) ^ (EXPR_B)

   in C.

.. c:macro:: GCC_JIT_BINARY_OP_BITWISE_OR

   Bitwise inclusive OR; analogous to:

   .. code-block:: c

     (EXPR_A) | (EXPR_B)

   in C.

.. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_AND

   Logical AND; analogous to:

   .. code-block:: c

     (EXPR_A) && (EXPR_B)

   in C.

.. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_OR

   Logical OR; analogous to:

   .. code-block:: c

     (EXPR_A) || (EXPR_B)

   in C.

.. c:macro:: GCC_JIT_BINARY_OP_LSHIFT

   Left shift; analogous to:

   .. code-block:: c

     (EXPR_A) << (EXPR_B)

   in C.

.. c:macro:: GCC_JIT_BINARY_OP_RSHIFT

   Right shift; analogous to:

   .. code-block:: c

     (EXPR_A) >> (EXPR_B)

   in C.

Comparisons
***********

.. function:: gcc_jit_rvalue *\
              gcc_jit_context_new_comparison (gcc_jit_context *ctxt,\
                                              gcc_jit_location *loc,\
                                              enum gcc_jit_comparison op,\
                                              gcc_jit_rvalue *a, gcc_jit_rvalue *b)

   Build a boolean rvalue out of the comparison of two other rvalues.

.. type:: enum gcc_jit_comparison

=======================================  ============
Comparison                               C equivalent
=======================================  ============
:c:macro:`GCC_JIT_COMPARISON_EQ`         `x == y`
:c:macro:`GCC_JIT_COMPARISON_NE`         `x != y`
:c:macro:`GCC_JIT_COMPARISON_LT`         `x < y`
:c:macro:`GCC_JIT_COMPARISON_LE`         `x <= y`
:c:macro:`GCC_JIT_COMPARISON_GT`         `x > y`
:c:macro:`GCC_JIT_COMPARISON_GE`         `x >= y`
=======================================  ============


Function calls
**************
.. function:: gcc_jit_rvalue *\
              gcc_jit_context_new_call (gcc_jit_context *ctxt,\
                                        gcc_jit_location *loc,\
                                        gcc_jit_function *func,\
                                        int numargs , gcc_jit_rvalue **args)

   Given a function and the given table of argument rvalues, construct a
   call to the function, with the result as an rvalue.

   .. note::

      :c:func:`gcc_jit_context_new_call` merely builds a
      :c:type:`gcc_jit_rvalue` i.e. an expression that can be evaluated,
      perhaps as part of a more complicated expression.
      The call *won't* happen unless you add a statement to a function
      that evaluates the expression.

      For example, if you want to call a function and discard the result
      (or to call a function with ``void`` return type), use
      :c:func:`gcc_jit_block_add_eval`:

      .. code-block:: c

         /* Add "(void)printf (arg0, arg1);".  */
         gcc_jit_block_add_eval (
           block, NULL,
           gcc_jit_context_new_call (
             ctxt,
             NULL,
             printf_func,
             2, args));

.. function:: gcc_jit_rvalue *\
              gcc_jit_context_new_call_through_ptr (gcc_jit_context *ctxt,\
                                                    gcc_jit_location *loc,\
                                                    gcc_jit_rvalue *fn_ptr,\
                                                    int numargs, \
                                                    gcc_jit_rvalue **args)

   Given an rvalue of function pointer type (e.g. from
   :c:func:`gcc_jit_context_new_function_ptr_type`), and the given table of
   argument rvalues, construct a call to the function pointer, with the
   result as an rvalue.

   .. note::

      The same caveat as for :c:func:`gcc_jit_context_new_call` applies.

.. function:: void\
              gcc_jit_rvalue_set_bool_require_tail_call (gcc_jit_rvalue *call,\
                                                         int require_tail_call)

   Given an :c:type:`gcc_jit_rvalue` for a call created through
   :c:func:`gcc_jit_context_new_call` or
   :c:func:`gcc_jit_context_new_call_through_ptr`, mark/clear the
   call as needing tail-call optimization.  The optimizer will
   attempt to optimize the call into a jump instruction; if it is
   unable to do do, an error will be emitted.

   This may be useful when implementing functions that use the
   continuation-passing style (e.g. for functional programming
   languages), in which every function "returns" by calling a
   "continuation" function pointer.  This call must be
   guaranteed to be implemented as a jump, otherwise the program
   could consume an arbitrary amount of stack space as it executed.

   This entrypoint was added in :ref:`LIBGCCJIT_ABI_6`; you can test for
   its presence using

   .. code-block:: c

      #ifdef LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call

Function pointers
*****************

Function pointers can be obtained:

  * from a :c:type:`gcc_jit_function` using
    :c:func:`gcc_jit_function_get_address`, or

  * from an existing function using
    :c:func:`gcc_jit_context_new_rvalue_from_ptr`,
    using a function pointer type obtained using
    :c:func:`gcc_jit_context_new_function_ptr_type`.

Type-coercion
*************

.. function:: gcc_jit_rvalue *\
              gcc_jit_context_new_cast (gcc_jit_context *ctxt,\
                                        gcc_jit_location *loc,\
                                        gcc_jit_rvalue *rvalue,\
                                        gcc_jit_type *type)

   Given an rvalue of T, construct another rvalue of another type.

   Currently only a limited set of conversions are possible:

     * int <-> float
     * int <-> bool
     * P*  <-> Q*, for pointer types P and Q

.. function:: gcc_jit_rvalue *\
              gcc_jit_context_new_bitcast (gcc_jit_context *ctxt,\
                                           gcc_jit_location *loc,\
                                           gcc_jit_rvalue *rvalue,\
                                           gcc_jit_type *type)

   Given an rvalue of T, bitcast it to another type, meaning that this will
   generate a new rvalue by interpreting the bits of ``rvalue`` to the layout
   of ``type``.

   The type of rvalue must be the same size as the size of ``type``.

   This entrypoint was added in :ref:`LIBGCCJIT_ABI_21`; you can test for
   its presence using

   .. code-block:: c

      #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitcast

Lvalues
-------

.. type:: gcc_jit_lvalue

An lvalue is something that can of the *left*-hand side of an assignment:
a storage area (such as a variable).  It is also usable as an rvalue,
where the rvalue is computed by reading from the storage area.

.. function:: gcc_jit_object *\
              gcc_jit_lvalue_as_object (gcc_jit_lvalue *lvalue)

   Upcast an lvalue to be an object.

.. function:: gcc_jit_rvalue *\
              gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue *lvalue)

   Upcast an lvalue to be an rvalue.

.. function:: gcc_jit_rvalue *\
              gcc_jit_lvalue_get_address (gcc_jit_lvalue *lvalue,\
                                          gcc_jit_location *loc)

   Take the address of an lvalue; analogous to:

   .. code-block:: c

     &(EXPR)

   in C.

.. function:: void\
              gcc_jit_lvalue_set_tls_model (gcc_jit_lvalue *lvalue,\
                                            enum gcc_jit_tls_model model)

   Make a variable a thread-local variable.

   The "model" parameter determines the thread-local storage model of the "lvalue":

   .. type:: enum gcc_jit_tls_model

   .. c:macro:: GCC_JIT_TLS_MODEL_NONE

      Don't set the TLS model.

   .. c:macro:: GCC_JIT_TLS_MODEL_GLOBAL_DYNAMIC

   .. c:macro:: GCC_JIT_TLS_MODEL_LOCAL_DYNAMIC

   .. c:macro:: GCC_JIT_TLS_MODEL_INITIAL_EXEC

   .. c:macro:: GCC_JIT_TLS_MODEL_LOCAL_EXEC

   This is analogous to:

   .. code-block:: c

     _Thread_local int foo __attribute__ ((tls_model("MODEL")));

   in C.

   This entrypoint was added in :ref:`LIBGCCJIT_ABI_17`; you can test for
   its presence using

   .. code-block:: c

      #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_tls_model

.. function:: void\
              gcc_jit_lvalue_set_link_section (gcc_jit_lvalue *lvalue,\
                                               const char *section_name)

   Set the link section of a variable.
   The parameter ``section_name`` must be non-NULL and must contain the
   leading dot. Analogous to:

   .. code-block:: c

     int variable __attribute__((section(".section")));

   in C.

   This entrypoint was added in :ref:`LIBGCCJIT_ABI_18`; you can test for
   its presence using

   .. code-block:: c

      #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_link_section

.. function:: void\
              gcc_jit_lvalue_set_register_name (gcc_jit_lvalue *lvalue,\
                                                const char *reg_name);

   Set the register name of a variable.
   The parameter ``reg_name`` must be non-NULL. Analogous to:

   .. code-block:: c

     register int variable asm ("r12");

   in C.

   This entrypoint was added in :ref:`LIBGCCJIT_ABI_22`; you can test for
   its presence using

   .. code-block:: c

      #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_register_name

.. function:: void\
              gcc_jit_lvalue_set_alignment (gcc_jit_lvalue *lvalue,\
                                            unsigned bytes)

   Set the alignment of a variable, in bytes.
   Analogous to:

   .. code-block:: c

     int variable __attribute__((aligned (16)));

   in C.

   This entrypoint was added in :ref:`LIBGCCJIT_ABI_24`; you can test for
   its presence using

   .. code-block:: c

      #ifdef LIBGCCJIT_HAVE_ALIGNMENT

.. function:: unsigned\
              gcc_jit_lvalue_get_alignment (gcc_jit_lvalue *lvalue)

   Return the alignment of a variable set by ``gcc_jit_lvalue_set_alignment``.
   Return 0 if the alignment was not set. Analogous to:

   .. code-block:: c

     _Alignof (variable)

   in C.

   This entrypoint was added in :ref:`LIBGCCJIT_ABI_24`; you can test for
   its presence using

   .. code-block:: c

      #ifdef LIBGCCJIT_HAVE_ALIGNMENT

Global variables
****************

.. function:: gcc_jit_lvalue *\
              gcc_jit_context_new_global (gcc_jit_context *ctxt,\
                                          gcc_jit_location *loc,\
                                          enum gcc_jit_global_kind kind,\
                                          gcc_jit_type *type,\
                                          const char *name)

   Add a new global variable of the given type and name to the context.

   The parameter ``type`` must be non-`void`.

   The parameter ``name`` must be non-NULL.  The call takes a copy of the
   underlying string, so it is valid to pass in a pointer to an on-stack
   buffer.

   The "kind" parameter determines the visibility of the "global" outside
   of the :c:type:`gcc_jit_result`:

   .. type:: enum gcc_jit_global_kind

   .. c:macro:: GCC_JIT_GLOBAL_EXPORTED

      Global is defined by the client code and is visible
      by name outside of this JIT context via
      :c:func:`gcc_jit_result_get_global` (and this value is required for
      the global to be accessible via that entrypoint).

   .. c:macro:: GCC_JIT_GLOBAL_INTERNAL

      Global is defined by the client code, but is invisible
      outside of it.  Analogous to a "static" global within a .c file.
      Specifically, the variable will only be visible within this
      context and within child contexts.

   .. c:macro:: GCC_JIT_GLOBAL_IMPORTED

      Global is not defined by the client code; we're merely
      referring to it.  Analogous to using an "extern" global from a
      header file.

.. function:: gcc_jit_lvalue *\
              gcc_jit_global_set_initializer (gcc_jit_lvalue *global,\
                                              const void *blob,\
                                              size_t num_bytes)

   Set an initializer for ``global`` using the memory content pointed
   by ``blob`` for ``num_bytes``.  ``global`` must be an array of an
   integral type.  Return the global itself.

   The parameter ``blob`` must be non-NULL. The call copies the memory
   pointed by ``blob`` for ``num_bytes`` bytes, so it is valid to pass
   in a pointer to an on-stack buffer.  The content will be stored in
   the compilation unit and used as initialization value of the array.

   This entrypoint was added in :ref:`LIBGCCJIT_ABI_14`; you can test for
   its presence using

   .. code-block:: c

      #ifdef LIBGCCJIT_HAVE_gcc_jit_global_set_initializer

.. function:: gcc_jit_lvalue *\
	      gcc_jit_global_set_initializer_rvalue (gcc_jit_lvalue *global,\
	                                             gcc_jit_rvalue *init_value)

   Set the initial value of a global with an rvalue.

   The rvalue needs to be a constant expression, e.g. no function calls.

   The global can't have the ``kind`` :c:macro:`GCC_JIT_GLOBAL_IMPORTED`.

   As a non-comprehensive example it is OK to do the equivalent of:

   .. code-block:: c

       int foo = 3 * 2; /* rvalue from gcc_jit_context_new_binary_op.  */
       int arr[] = {1,2,3,4}; /* rvalue from gcc_jit_context_new_constructor.  */
       int *bar = &arr[2] + 1; /* rvalue from nested "get address" of "array access".  */
       const int baz = 3; /* rvalue from gcc_jit_context_rvalue_from_int.  */
       int boz = baz; /* rvalue from gcc_jit_lvalue_as_rvalue.  */

   Use together with :c:func:`gcc_jit_context_new_struct_constructor`,
   :c:func:`gcc_jit_context_new_union_constructor`, :c:func:`gcc_jit_context_new_array_constructor`
   to initialize structs, unions and arrays.

   On success, returns the ``global`` parameter unchanged. Otherwise, ``NULL``.

   This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its
   presence using:

   .. code-block:: c

      #ifdef LIBGCCJIT_HAVE_CTORS

Working with pointers, structs and unions
-----------------------------------------

.. function:: gcc_jit_lvalue *\
              gcc_jit_rvalue_dereference (gcc_jit_rvalue *rvalue,\
                                          gcc_jit_location *loc)

   Given an rvalue of pointer type ``T *``, dereferencing the pointer,
   getting an lvalue of type ``T``.  Analogous to:

   .. code-block:: c

     *(EXPR)

   in C.

Field access is provided separately for both lvalues and rvalues.

.. function:: gcc_jit_lvalue *\
              gcc_jit_lvalue_access_field (gcc_jit_lvalue *struct_,\
                                           gcc_jit_location *loc,\
                                           gcc_jit_field *field)

   Given an lvalue of struct or union type, access the given field,
   getting an lvalue of the field's type.  Analogous to:

   .. code-block:: c

      (EXPR).field = ...;

   in C.

.. function:: gcc_jit_rvalue *\
              gcc_jit_rvalue_access_field (gcc_jit_rvalue *struct_,\
                                           gcc_jit_location *loc,\
                                           gcc_jit_field *field)

   Given an rvalue of struct or union type, access the given field
   as an rvalue.  Analogous to:

   .. code-block:: c

      (EXPR).field

   in C.

.. function:: gcc_jit_lvalue *\
              gcc_jit_rvalue_dereference_field (gcc_jit_rvalue *ptr,\
                                                gcc_jit_location *loc,\
                                                gcc_jit_field *field)

   Given an rvalue of pointer type ``T *`` where T is of struct or union
   type, access the given field as an lvalue.  Analogous to:

   .. code-block:: c

      (EXPR)->field

   in C, itself equivalent to ``(*EXPR).FIELD``.

.. function:: gcc_jit_lvalue *\
              gcc_jit_context_new_array_access (gcc_jit_context *ctxt,\
                                                gcc_jit_location *loc,\
                                                gcc_jit_rvalue *ptr,\
                                                gcc_jit_rvalue *index)

   Given an rvalue of pointer type ``T *``, get at the element `T` at
   the given index, using standard C array indexing rules i.e. each
   increment of ``index`` corresponds to ``sizeof(T)`` bytes.
   Analogous to:

   .. code-block:: c

      PTR[INDEX]

   in C (or, indeed, to ``PTR + INDEX``).