gcc/jit/docs/topics/types.rst

   1 .. Copyright (C) 2014-2016 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 Types
  21 =====
  22
  23 .. c:type:: gcc_jit_type
  24
  25    gcc_jit_type represents a type within the library.
  26
  27 .. function:: gcc_jit_object *gcc_jit_type_as_object (gcc_jit_type *type)
  28
  29    Upcast a type to an object.
  30
  31 Types can be created in several ways:
  32
  33 * fundamental types can be accessed using
  34   :func:`gcc_jit_context_get_type`:
  35
  36   .. code-block:: c
  37
  38       gcc_jit_type *int_type = gcc_jit_context_get_type (GCC_JIT_TYPE_INT);
  39
  40   See :func:`gcc_jit_context_get_type` for the available types.
  41
  42 * derived types can be accessed by using functions such as
  43   :func:`gcc_jit_type_get_pointer` and :func:`gcc_jit_type_get_const`:
  44
  45   .. code-block:: c
  46
  47     gcc_jit_type *const_int_star = gcc_jit_type_get_pointer (gcc_jit_type_get_const (int_type));
  48     gcc_jit_type *int_const_star = gcc_jit_type_get_const (gcc_jit_type_get_pointer (int_type));
  49
  50 * by creating structures (see below).
  51
  52 Standard types
  53 --------------
  54
  55 .. function:: gcc_jit_type *gcc_jit_context_get_type (gcc_jit_context *ctxt, \
  56                                                       enum gcc_jit_types type_)
  57
  58    Access a specific type.  The available types are:
  59
  60    ==========================================  ================================
  61    `enum gcc_jit_types` value                  Meaning
  62    ==========================================  ================================
  63    :c:data:`GCC_JIT_TYPE_VOID`                 C's ``void`` type.
  64    :c:data:`GCC_JIT_TYPE_VOID_PTR`             C's ``void *``.
  65    :c:data:`GCC_JIT_TYPE_BOOL`                 C++'s ``bool`` type; also C99's
  66                                                ``_Bool`` type, aka ``bool`` if
  67                                                using stdbool.h.
  68    :c:data:`GCC_JIT_TYPE_CHAR`                 C's ``char`` (of some signedness)
  69    :c:data:`GCC_JIT_TYPE_SIGNED_CHAR`          C's ``signed char``
  70    :c:data:`GCC_JIT_TYPE_UNSIGNED_CHAR`        C's ``unsigned char``
  71    :c:data:`GCC_JIT_TYPE_SHORT`                C's ``short`` (signed)
  72    :c:data:`GCC_JIT_TYPE_UNSIGNED_SHORT`       C's ``unsigned short``
  73    :c:data:`GCC_JIT_TYPE_INT`                  C's ``int`` (signed)
  74    :c:data:`GCC_JIT_TYPE_UNSIGNED_INT`         C's ``unsigned int``
  75    :c:data:`GCC_JIT_TYPE_LONG`                 C's ``long`` (signed)
  76    :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG`        C's ``unsigned long``
  77    :c:data:`GCC_JIT_TYPE_LONG_LONG`            C99's ``long long`` (signed)
  78    :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG_LONG`   C99's ``unsigned long long``
  79    :c:data:`GCC_JIT_TYPE_FLOAT`
  80    :c:data:`GCC_JIT_TYPE_DOUBLE`
  81    :c:data:`GCC_JIT_TYPE_LONG_DOUBLE`
  82    :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`       C type: ``(const char *)``
  83    :c:data:`GCC_JIT_TYPE_SIZE_T`               C's ``size_t`` type
  84    :c:data:`GCC_JIT_TYPE_FILE_PTR`             C type: ``(FILE *)``
  85    :c:data:`GCC_JIT_TYPE_COMPLEX_FLOAT`        C99's ``_Complex float``
  86    :c:data:`GCC_JIT_TYPE_COMPLEX_DOUBLE`       C99's ``_Complex double``
  87    :c:data:`GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE`  C99's ``_Complex long double``
  88    ==========================================  ================================
  89
  90 .. function:: gcc_jit_type *\
  91               gcc_jit_context_get_int_type (gcc_jit_context *ctxt, \
  92                                             int num_bytes, int is_signed)
  93
  94    Access the integer type of the given size.
  95
  96
  97 Pointers, `const`, and `volatile`
  98 ---------------------------------
  99
 100 .. function::  gcc_jit_type *gcc_jit_type_get_pointer (gcc_jit_type *type)
 101
 102    Given type "T", get type "T*".
 103
 104 .. function::  gcc_jit_type *gcc_jit_type_get_const (gcc_jit_type *type)
 105
 106    Given type "T", get type "const T".
 107
 108 .. function::  gcc_jit_type *gcc_jit_type_get_volatile (gcc_jit_type *type)
 109
 110    Given type "T", get type "volatile T".
 111
 112 .. function::  gcc_jit_type *\
 113                gcc_jit_context_new_array_type (gcc_jit_context *ctxt, \
 114                                                gcc_jit_location *loc, \
 115                                                gcc_jit_type *element_type, \
 116                                                int num_elements)
 117
 118    Given type "T", get type "T[N]" (for a constant N).
 119
 120
 121 Structures and unions
 122 ---------------------
 123
 124 .. c:type:: gcc_jit_struct
 125
 126 A compound type analagous to a C `struct`.
 127
 128 .. c:type:: gcc_jit_field
 129
 130 A field within a :c:type:`gcc_jit_struct`.
 131
 132 You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and
 133 :c:type:`gcc_jit_field` instances, in either order:
 134
 135 * by creating the fields, then the structure.  For example, to model:
 136
 137   .. code-block:: c
 138
 139     struct coord {double x; double y; };
 140
 141   you could call:
 142
 143   .. code-block:: c
 144
 145     gcc_jit_field *field_x =
 146       gcc_jit_context_new_field (ctxt, NULL, double_type, "x");
 147     gcc_jit_field *field_y =
 148       gcc_jit_context_new_field (ctxt, NULL, double_type, "y");
 149     gcc_jit_field *fields[2] = {field_x, field_y};
 150     gcc_jit_struct *coord =
 151       gcc_jit_context_new_struct_type (ctxt, NULL, "coord", 2, fields);
 152
 153 * by creating the structure, then populating it with fields, typically
 154   to allow modelling self-referential structs such as:
 155
 156   .. code-block:: c
 157
 158     struct node { int m_hash; struct node *m_next; };
 159
 160   like this:
 161
 162   .. code-block:: c
 163
 164     gcc_jit_type *node =
 165       gcc_jit_context_new_opaque_struct (ctxt, NULL, "node");
 166     gcc_jit_type *node_ptr =
 167       gcc_jit_type_get_pointer (node);
 168     gcc_jit_field *field_hash =
 169       gcc_jit_context_new_field (ctxt, NULL, int_type, "m_hash");
 170     gcc_jit_field *field_next =
 171       gcc_jit_context_new_field (ctxt, NULL, node_ptr, "m_next");
 172     gcc_jit_field *fields[2] = {field_hash, field_next};
 173     gcc_jit_struct_set_fields (node, NULL, 2, fields);
 174
 175 .. function:: gcc_jit_field *\
 176               gcc_jit_context_new_field (gcc_jit_context *ctxt,\
 177                                          gcc_jit_location *loc,\
 178                                          gcc_jit_type *type,\
 179                                          const char *name)
 180
 181    Construct a new field, with the given type and name.
 182
 183    The parameter ``name`` must be non-NULL.  The call takes a copy of the
 184    underlying string, so it is valid to pass in a pointer to an on-stack
 185    buffer.
 186
 187 .. function:: gcc_jit_object *\
 188               gcc_jit_field_as_object (gcc_jit_field *field)
 189
 190    Upcast from field to object.
 191
 192 .. function:: gcc_jit_struct *\
 193    gcc_jit_context_new_struct_type (gcc_jit_context *ctxt,\
 194                                     gcc_jit_location *loc,\
 195                                     const char *name,\
 196                                     int num_fields,\
 197                                     gcc_jit_field **fields)
 198
 199      Construct a new struct type, with the given name and fields.
 200
 201      The parameter ``name`` must be non-NULL.  The call takes a copy of
 202      the underlying string, so it is valid to pass in a pointer to an
 203      on-stack buffer.
 204
 205 .. function:: gcc_jit_struct *\
 206               gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt,\
 207                                                  gcc_jit_location *loc,\
 208                                                  const char *name)
 209
 210      Construct a new struct type, with the given name, but without
 211      specifying the fields.   The fields can be omitted (in which case the
 212      size of the struct is not known), or later specified using
 213      :c:func:`gcc_jit_struct_set_fields`.
 214
 215      The parameter ``name`` must be non-NULL.  The call takes a copy of
 216      the underlying string, so it is valid to pass in a pointer to an
 217      on-stack buffer.
 218
 219 .. function:: gcc_jit_type *\
 220               gcc_jit_struct_as_type (gcc_jit_struct *struct_type)
 221
 222    Upcast from struct to type.
 223
 224 .. function:: void\
 225               gcc_jit_struct_set_fields (gcc_jit_struct *struct_type,\
 226                                          gcc_jit_location *loc,\
 227                                          int num_fields,\
 228                                          gcc_jit_field **fields)
 229
 230    Populate the fields of a formerly-opaque struct type.
 231
 232    This can only be called once on a given struct type.
 233
 234 .. function:: gcc_jit_type *\
 235               gcc_jit_context_new_union_type (gcc_jit_context *ctxt,\
 236                                               gcc_jit_location *loc,\
 237                                               const char *name,\
 238                                               int num_fields,\
 239                                               gcc_jit_field **fields)
 240
 241      Construct a new union type, with the given name and fields.
 242
 243      The parameter ``name`` must be non-NULL.  It is copied, so the input
 244      buffer does not need to outlive the call.
 245
 246      Example of use:
 247
 248      .. literalinclude:: ../../../testsuite/jit.dg/test-accessing-union.c
 249        :start-after: /* Quote from here in docs/topics/types.rst.  */
 250        :end-before: /* Quote up to here in docs/topics/types.rst.  */
 251        :language: c