[thirdparty/gcc.git] / gcc / jit / docs / topics / types.rst

.. Copyright (C) 2014-2020 Free Software Foundation, Inc.
   Originally contributed by David Malcolm <dmalcolm@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
   <http://www.gnu.org/licenses/>.

.. default-domain:: c

Types
=====

.. c:type:: gcc_jit_type

   gcc_jit_type represents a type within the library.

.. function:: gcc_jit_object *gcc_jit_type_as_object (gcc_jit_type *type)

   Upcast a type to an object.

Types can be created in several ways:

* fundamental types can be accessed using
  :func:`gcc_jit_context_get_type`:

  .. code-block:: c

      gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);

  See :func:`gcc_jit_context_get_type` for the available types.

* derived types can be accessed by using functions such as
  :func:`gcc_jit_type_get_pointer` and :func:`gcc_jit_type_get_const`:

  .. code-block:: c

    gcc_jit_type *const_int_star = gcc_jit_type_get_pointer (gcc_jit_type_get_const (int_type));
    gcc_jit_type *int_const_star = gcc_jit_type_get_const (gcc_jit_type_get_pointer (int_type));

* by creating structures (see below).

Standard types
--------------

.. function:: gcc_jit_type *gcc_jit_context_get_type (gcc_jit_context *ctxt, \
                                                      enum gcc_jit_types type_)

   Access a specific type.  The available types are:

   ==========================================  ================================
   `enum gcc_jit_types` value                  Meaning
   ==========================================  ================================
   :c:data:`GCC_JIT_TYPE_VOID`                 C's ``void`` type.
   :c:data:`GCC_JIT_TYPE_VOID_PTR`             C's ``void *``.
   :c:data:`GCC_JIT_TYPE_BOOL`                 C++'s ``bool`` type; also C99's
                                               ``_Bool`` type, aka ``bool`` if
                                               using stdbool.h.
   :c:data:`GCC_JIT_TYPE_CHAR`                 C's ``char`` (of some signedness)
   :c:data:`GCC_JIT_TYPE_SIGNED_CHAR`          C's ``signed char``
   :c:data:`GCC_JIT_TYPE_UNSIGNED_CHAR`        C's ``unsigned char``
   :c:data:`GCC_JIT_TYPE_SHORT`                C's ``short`` (signed)
   :c:data:`GCC_JIT_TYPE_UNSIGNED_SHORT`       C's ``unsigned short``
   :c:data:`GCC_JIT_TYPE_INT`                  C's ``int`` (signed)
   :c:data:`GCC_JIT_TYPE_UNSIGNED_INT`         C's ``unsigned int``
   :c:data:`GCC_JIT_TYPE_LONG`                 C's ``long`` (signed)
   :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG`        C's ``unsigned long``
   :c:data:`GCC_JIT_TYPE_LONG_LONG`            C99's ``long long`` (signed)
   :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG_LONG`   C99's ``unsigned long long``
   :c:data:`GCC_JIT_TYPE_FLOAT`
   :c:data:`GCC_JIT_TYPE_DOUBLE`
   :c:data:`GCC_JIT_TYPE_LONG_DOUBLE`
   :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`       C type: ``(const char *)``
   :c:data:`GCC_JIT_TYPE_SIZE_T`               C's ``size_t`` type
   :c:data:`GCC_JIT_TYPE_FILE_PTR`             C type: ``(FILE *)``
   :c:data:`GCC_JIT_TYPE_COMPLEX_FLOAT`        C99's ``_Complex float``
   :c:data:`GCC_JIT_TYPE_COMPLEX_DOUBLE`       C99's ``_Complex double``
   :c:data:`GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE`  C99's ``_Complex long double``
   ==========================================  ================================

.. function:: gcc_jit_type *\
              gcc_jit_context_get_int_type (gcc_jit_context *ctxt, \
                                            int num_bytes, int is_signed)

   Access the integer type of the given size.


Pointers, `const`, and `volatile`
---------------------------------

.. function::  gcc_jit_type *gcc_jit_type_get_pointer (gcc_jit_type *type)

   Given type "T", get type "T*".

.. function::  gcc_jit_type *gcc_jit_type_get_const (gcc_jit_type *type)

   Given type "T", get type "const T".

.. function::  gcc_jit_type *gcc_jit_type_get_volatile (gcc_jit_type *type)

   Given type "T", get type "volatile T".

.. function::  gcc_jit_type *\
               gcc_jit_context_new_array_type (gcc_jit_context *ctxt, \
                                               gcc_jit_location *loc, \
                                               gcc_jit_type *element_type, \
                                               int num_elements)

   Given type "T", get type "T[N]" (for a constant N).

.. function::  gcc_jit_type *\
               gcc_jit_type_get_aligned (gcc_jit_type *type, \
                                         size_t alignment_in_bytes)

   Given type "T", get type:

   .. code-block:: c

      T __attribute__ ((aligned (ALIGNMENT_IN_BYTES)))

   The alignment must be a power of two.

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

   .. code-block:: c

      #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_aligned

Vector types
------------

.. function::  gcc_jit_type *\
               gcc_jit_type_get_vector (gcc_jit_type *type, \
                                        size_t num_units)

   Given type "T", get type:

   .. code-block:: c

      T  __attribute__ ((vector_size (sizeof(T) * num_units))

   T must be integral or floating point; num_units must be a power of two.

   This can be used to construct a vector type in which operations
   are applied element-wise.  The compiler will automatically
   use SIMD instructions where possible.  See:
   https://gcc.gnu.org/onlinedocs/gcc/Vector-Extensions.html

   For example, assuming 4-byte ``ints``, then:

   .. code-block:: c

      typedef int v4si __attribute__ ((vector_size (16)));

   can be obtained using:

   .. code-block:: c

      gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt,
                                                         GCC_JIT_TYPE_INT);
      gcc_jit_type *v4si_type = gcc_jit_type_get_vector (int_type, 4);

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

   .. code-block:: c

      #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_vector

   Vector rvalues can be generated using
   :func:`gcc_jit_context_new_rvalue_from_vector`.


Structures and unions
---------------------

.. c:type:: gcc_jit_struct

A compound type analagous to a C `struct`.

.. c:type:: gcc_jit_field

A field within a :c:type:`gcc_jit_struct`.

You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and
:c:type:`gcc_jit_field` instances, in either order:

* by creating the fields, then the structure.  For example, to model:

  .. code-block:: c

    struct coord {double x; double y; };

  you could call:

  .. code-block:: c

    gcc_jit_field *field_x =
      gcc_jit_context_new_field (ctxt, NULL, double_type, "x");
    gcc_jit_field *field_y =
      gcc_jit_context_new_field (ctxt, NULL, double_type, "y");
    gcc_jit_field *fields[2] = {field_x, field_y};
    gcc_jit_struct *coord =
      gcc_jit_context_new_struct_type (ctxt, NULL, "coord", 2, fields);

* by creating the structure, then populating it with fields, typically
  to allow modelling self-referential structs such as:

  .. code-block:: c

    struct node { int m_hash; struct node *m_next; };

  like this:

  .. code-block:: c

    gcc_jit_type *node =
      gcc_jit_context_new_opaque_struct (ctxt, NULL, "node");
    gcc_jit_type *node_ptr =
      gcc_jit_type_get_pointer (node);
    gcc_jit_field *field_hash =
      gcc_jit_context_new_field (ctxt, NULL, int_type, "m_hash");
    gcc_jit_field *field_next =
      gcc_jit_context_new_field (ctxt, NULL, node_ptr, "m_next");
    gcc_jit_field *fields[2] = {field_hash, field_next};
    gcc_jit_struct_set_fields (node, NULL, 2, fields);

.. function:: gcc_jit_field *\
              gcc_jit_context_new_field (gcc_jit_context *ctxt,\
                                         gcc_jit_location *loc,\
                                         gcc_jit_type *type,\
                                         const char *name)

   Construct a new field, with the given type and name.

   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.

.. function:: gcc_jit_field *\
              gcc_jit_context_new_bitfield (gcc_jit_context *ctxt,\
                                            gcc_jit_location *loc,\
                                            gcc_jit_type *type,\
                                            int width,\
                                            const char *name)

   Construct a new bit field, with the given type width and name.

   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 parameter ``type`` must be an integer type.

   The parameter ``width`` must be a positive integer that does not exceed the
   size of ``type``.

   This API entrypoint was added in :ref:`LIBGCCJIT_ABI_12`; you can test
   for its presence using
   .. code-block:: c

      #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitfield

.. function:: gcc_jit_object *\
              gcc_jit_field_as_object (gcc_jit_field *field)

   Upcast from field to object.

.. function:: gcc_jit_struct *\
   gcc_jit_context_new_struct_type (gcc_jit_context *ctxt,\
                                    gcc_jit_location *loc,\
                                    const char *name,\
                                    int num_fields,\
                                    gcc_jit_field **fields)

     Construct a new struct type, with the given name and fields.

     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.

.. function:: gcc_jit_struct *\
              gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt,\
                                                 gcc_jit_location *loc,\
                                                 const char *name)

     Construct a new struct type, with the given name, but without
     specifying the fields.   The fields can be omitted (in which case the
     size of the struct is not known), or later specified using
     :c:func:`gcc_jit_struct_set_fields`.

     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.

.. function:: gcc_jit_type *\
              gcc_jit_struct_as_type (gcc_jit_struct *struct_type)

   Upcast from struct to type.

.. function:: void\
              gcc_jit_struct_set_fields (gcc_jit_struct *struct_type,\
                                         gcc_jit_location *loc,\
                                         int num_fields,\
                                         gcc_jit_field **fields)

   Populate the fields of a formerly-opaque struct type.

   This can only be called once on a given struct type.

.. function:: gcc_jit_type *\
              gcc_jit_context_new_union_type (gcc_jit_context *ctxt,\
                                              gcc_jit_location *loc,\
                                              const char *name,\
                                              int num_fields,\
                                              gcc_jit_field **fields)

     Construct a new union type, with the given name and fields.

     The parameter ``name`` must be non-NULL.  It is copied, so the input
     buffer does not need to outlive the call.

     Example of use:

     .. literalinclude:: ../../../testsuite/jit.dg/test-accessing-union.c
       :start-after: /* Quote from here in docs/topics/types.rst.  */
       :end-before: /* Quote up to here in docs/topics/types.rst.  */
       :language: c

Function pointer types
----------------------

Function pointer types can be created using
:c:func:`gcc_jit_context_new_function_ptr_type`.
Commit	Line	Data
8d9254fc	1	.. Copyright (C) 2014-2020 Free Software Foundation, Inc.
35485da9 DM	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
47ee1b7c	38	gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
35485da9 DM	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
eeafb319 DM	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``
35485da9 DM	79	:c:data:`GCC_JIT_TYPE_FLOAT`
	80	:c:data:`GCC_JIT_TYPE_DOUBLE`
	81	:c:data:`GCC_JIT_TYPE_LONG_DOUBLE`
eeafb319 DM	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	========================================== ================================
35485da9 DM	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
0ebd1f00 DM	120	.. function:: gcc_jit_type *\
	121	gcc_jit_type_get_aligned (gcc_jit_type *type, \
	122	size_t alignment_in_bytes)
	123
	124	Given type "T", get type:
	125
	126	.. code-block:: c
	127
	128	T __attribute__ ((aligned (ALIGNMENT_IN_BYTES)))
	129
	130	The alignment must be a power of two.
	131
	132	This entrypoint was added in :ref:`LIBGCCJIT_ABI_7`; you can test for
	133	its presence using
	134
	135	.. code-block:: c
	136
	137	#ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_aligned
	138
47ee1b7c DM	139	Vector types
	140	------------
	141
	142	.. function:: gcc_jit_type *\
	143	gcc_jit_type_get_vector (gcc_jit_type *type, \
	144	size_t num_units)
	145
	146	Given type "T", get type:
	147
	148	.. code-block:: c
	149
	150	T __attribute__ ((vector_size (sizeof(T) * num_units))
	151
	152	T must be integral or floating point; num_units must be a power of two.
	153
	154	This can be used to construct a vector type in which operations
	155	are applied element-wise. The compiler will automatically
	156	use SIMD instructions where possible. See:
	157	https://gcc.gnu.org/onlinedocs/gcc/Vector-Extensions.html
	158
	159	For example, assuming 4-byte ``ints``, then:
	160
	161	.. code-block:: c
	162
	163	typedef int v4si __attribute__ ((vector_size (16)));
	164
	165	can be obtained using:
	166
	167	.. code-block:: c
	168
	169	gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt,
	170	GCC_JIT_TYPE_INT);
	171	gcc_jit_type *v4si_type = gcc_jit_type_get_vector (int_type, 4);
	172
	173	This API entrypoint was added in :ref:`LIBGCCJIT_ABI_8`; you can test
	174	for its presence using
	175
	176	.. code-block:: c
	177
	178	#ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_vector
	179
6069fe72 DM	180	Vector rvalues can be generated using
	181	:func:`gcc_jit_context_new_rvalue_from_vector`.
	182
35485da9 DM	183
	184	Structures and unions
	185	---------------------
	186
	187	.. c:type:: gcc_jit_struct
	188
	189	A compound type analagous to a C `struct`.
	190
	191	.. c:type:: gcc_jit_field
	192
	193	A field within a :c:type:`gcc_jit_struct`.
	194
	195	You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and
	196	:c:type:`gcc_jit_field` instances, in either order:
	197
	198	* by creating the fields, then the structure. For example, to model:
	199
	200	.. code-block:: c
	201
	202	struct coord {double x; double y; };
	203
	204	you could call:
	205
	206	.. code-block:: c
	207
	208	gcc_jit_field *field_x =
	209	gcc_jit_context_new_field (ctxt, NULL, double_type, "x");
	210	gcc_jit_field *field_y =
	211	gcc_jit_context_new_field (ctxt, NULL, double_type, "y");
	212	gcc_jit_field *fields[2] = {field_x, field_y};
	213	gcc_jit_struct *coord =
	214	gcc_jit_context_new_struct_type (ctxt, NULL, "coord", 2, fields);
	215
	216	* by creating the structure, then populating it with fields, typically
	217	to allow modelling self-referential structs such as:
	218
	219	.. code-block:: c
	220
	221	struct node { int m_hash; struct node *m_next; };
	222
	223	like this:
	224
	225	.. code-block:: c
	226
	227	gcc_jit_type *node =
	228	gcc_jit_context_new_opaque_struct (ctxt, NULL, "node");
	229	gcc_jit_type *node_ptr =
	230	gcc_jit_type_get_pointer (node);
	231	gcc_jit_field *field_hash =
	232	gcc_jit_context_new_field (ctxt, NULL, int_type, "m_hash");
	233	gcc_jit_field *field_next =
	234	gcc_jit_context_new_field (ctxt, NULL, node_ptr, "m_next");
	235	gcc_jit_field *fields[2] = {field_hash, field_next};
	236	gcc_jit_struct_set_fields (node, NULL, 2, fields);
	237
	238	.. function:: gcc_jit_field *\
	239	gcc_jit_context_new_field (gcc_jit_context *ctxt,\
	240	gcc_jit_location *loc,\
	241	gcc_jit_type *type,\
	242	const char *name)
	243
	244	Construct a new field, with the given type and name.
	245
c575221a DM	246	The parameter ``name`` must be non-NULL. The call takes a copy of the
	247	underlying string, so it is valid to pass in a pointer to an on-stack
	248	buffer.
	249
ee118c14 AC	250	.. function:: gcc_jit_field *\
	251	gcc_jit_context_new_bitfield (gcc_jit_context *ctxt,\
	252	gcc_jit_location *loc,\
	253	gcc_jit_type *type,\
	254	int width,\
	255	const char *name)
	256
	257	Construct a new bit field, with the given type width and name.
	258
	259	The parameter ``name`` must be non-NULL. The call takes a copy of the
	260	underlying string, so it is valid to pass in a pointer to an on-stack
	261	buffer.
	262
	263	The parameter ``type`` must be an integer type.
	264
	265	The parameter ``width`` must be a positive integer that does not exceed the
	266	size of ``type``.
	267
	268	This API entrypoint was added in :ref:`LIBGCCJIT_ABI_12`; you can test
	269	for its presence using
	270	.. code-block:: c
	271
	272	#ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitfield
	273
35485da9 DM	274	.. function:: gcc_jit_object *\
	275	gcc_jit_field_as_object (gcc_jit_field *field)
	276
	277	Upcast from field to object.
	278
	279	.. function:: gcc_jit_struct *\
	280	gcc_jit_context_new_struct_type (gcc_jit_context *ctxt,\
	281	gcc_jit_location *loc,\
	282	const char *name,\
	283	int num_fields,\
	284	gcc_jit_field **fields)
	285
	286	Construct a new struct type, with the given name and fields.
	287
c575221a DM	288	The parameter ``name`` must be non-NULL. The call takes a copy of
	289	the underlying string, so it is valid to pass in a pointer to an
	290	on-stack buffer.
	291
35485da9 DM	292	.. function:: gcc_jit_struct *\
	293	gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt,\
	294	gcc_jit_location *loc,\
	295	const char *name)
	296
	297	Construct a new struct type, with the given name, but without
	298	specifying the fields. The fields can be omitted (in which case the
	299	size of the struct is not known), or later specified using
	300	:c:func:`gcc_jit_struct_set_fields`.
	301
c575221a DM	302	The parameter ``name`` must be non-NULL. The call takes a copy of
	303	the underlying string, so it is valid to pass in a pointer to an
	304	on-stack buffer.
	305
35485da9 DM	306	.. function:: gcc_jit_type *\
	307	gcc_jit_struct_as_type (gcc_jit_struct *struct_type)
	308
	309	Upcast from struct to type.
	310
	311	.. function:: void\
	312	gcc_jit_struct_set_fields (gcc_jit_struct *struct_type,\
	313	gcc_jit_location *loc,\
	314	int num_fields,\
	315	gcc_jit_field **fields)
	316
	317	Populate the fields of a formerly-opaque struct type.
	318
	319	This can only be called once on a given struct type.
e807aeaa DM	320
	321	.. function:: gcc_jit_type *\
	322	gcc_jit_context_new_union_type (gcc_jit_context *ctxt,\
	323	gcc_jit_location *loc,\
	324	const char *name,\
	325	int num_fields,\
	326	gcc_jit_field **fields)
	327
	328	Construct a new union type, with the given name and fields.
	329
	330	The parameter ``name`` must be non-NULL. It is copied, so the input
	331	buffer does not need to outlive the call.
	332
	333	Example of use:
	334
	335	.. literalinclude:: ../../../testsuite/jit.dg/test-accessing-union.c
	336	:start-after: /* Quote from here in docs/topics/types.rst. */
	337	:end-before: /* Quote up to here in docs/topics/types.rst. */
	338	:language: c
ecd5156d DM	339
	340	Function pointer types
	341	----------------------
	342
	343	Function pointer types can be created using
	344	:c:func:`gcc_jit_context_new_function_ptr_type`.