1.. Copyright (C) 2014-2018 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:: cpp
19
20Types
21=====
22
23.. class:: gccjit::type
24
25   gccjit::type represents a type within the library.  It is a subclass
26   of :class:`gccjit::object`.
27
28Types can be created in several ways:
29
30* fundamental types can be accessed using
31  :func:`gccjit::context::get_type`:
32
33  .. code-block:: c++
34
35      gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
36
37  or using the :func:`gccjit::context::get_int_type<T>` template:
38
39  .. code-block:: c++
40
41      gccjit::type t = ctxt.get_int_type <unsigned short> ();
42
43  See :c:func:`gcc_jit_context_get_type` for the available types.
44
45* derived types can be accessed by using functions such as
46  :func:`gccjit::type::get_pointer` and :func:`gccjit::type::get_const`:
47
48  .. code-block:: c++
49
50    gccjit::type const_int_star = int_type.get_const ().get_pointer ();
51    gccjit::type int_const_star = int_type.get_pointer ().get_const ();
52
53* by creating structures (see below).
54
55Standard types
56--------------
57
58.. function:: gccjit::type gccjit::context::get_type (enum gcc_jit_types)
59
60   Access a specific type.  This is a thin wrapper around
61   :c:func:`gcc_jit_context_get_type`; the parameter has the same meaning.
62
63.. function:: gccjit::type \
64              gccjit::context::get_int_type (size_t num_bytes, int is_signed)
65
66   Access the integer type of the given size.
67
68.. function:: gccjit::type \
69              gccjit::context::get_int_type <T> ()
70
71   Access the given integer type.  For example, you could map the
72   ``unsigned short`` type into a gccjit::type via:
73
74   .. code-block:: c++
75
76      gccjit::type t = ctxt.get_int_type <unsigned short> ();
77
78Pointers, `const`, and `volatile`
79---------------------------------
80
81.. function::  gccjit::type gccjit::type::get_pointer ()
82
83   Given type "T", get type "T*".
84
85.. function::  gccjit::type gccjit::type::get_const ()
86
87   Given type "T", get type "const T".
88
89.. function::  gccjit::type gccjit::type::get_volatile ()
90
91   Given type "T", get type "volatile T".
92
93.. function::  gccjit::type gccjit::type::get_aligned (size_t alignment_in_bytes)
94
95   Given type "T", get type:
96
97   .. code-block:: c
98
99      T __attribute__ ((aligned (ALIGNMENT_IN_BYTES)))
100
101   The alignment must be a power of two.
102
103.. function::  gccjit::type \
104               gccjit::context::new_array_type (gccjit::type element_type, \
105                                                int num_elements, \
106			                        gccjit::location loc)
107
108   Given type "T", get type "T[N]" (for a constant N).
109   Param "loc" is optional.
110
111
112Vector types
113------------
114
115.. function::  gccjit::type gccjit::type::get_vector (size_t num_units)
116
117   Given type "T", get type:
118
119   .. code-block:: c
120
121      T  __attribute__ ((vector_size (sizeof(T) * num_units))
122
123   T must be integral or floating point; num_units must be a power of two.
124
125
126Structures and unions
127---------------------
128
129.. class:: gccjit::struct_
130
131A compound type analagous to a C `struct`.
132
133:class:`gccjit::struct_` is a subclass of :class:`gccjit::type` (and thus
134of :class:`gccjit::object` in turn).
135
136.. class:: gccjit::field
137
138A field within a :class:`gccjit::struct_`.
139
140:class:`gccjit::field` is a subclass of :class:`gccjit::object`.
141
142You can model C `struct` types by creating :class:`gccjit::struct_` and
143:class:`gccjit::field` instances, in either order:
144
145* by creating the fields, then the structure.  For example, to model:
146
147  .. code-block:: c
148
149    struct coord {double x; double y; };
150
151  you could call:
152
153  .. code-block:: c++
154
155    gccjit::field field_x = ctxt.new_field (double_type, "x");
156    gccjit::field field_y = ctxt.new_field (double_type, "y");
157    std::vector fields;
158    fields.push_back (field_x);
159    fields.push_back (field_y);
160    gccjit::struct_ coord = ctxt.new_struct_type ("coord", fields);
161
162* by creating the structure, then populating it with fields, typically
163  to allow modelling self-referential structs such as:
164
165  .. code-block:: c
166
167    struct node { int m_hash; struct node *m_next; };
168
169  like this:
170
171  .. code-block:: c++
172
173    gccjit::struct_ node = ctxt.new_opaque_struct_type ("node");
174    gccjit::type node_ptr = node.get_pointer ();
175    gccjit::field field_hash = ctxt.new_field (int_type, "m_hash");
176    gccjit::field field_next = ctxt.new_field (node_ptr, "m_next");
177    std::vector fields;
178    fields.push_back (field_hash);
179    fields.push_back (field_next);
180    node.set_fields (fields);
181
182.. FIXME: the above API doesn't seem to exist yet
183
184.. function:: gccjit::field \
185              gccjit::context::new_field (gccjit::type type,\
186                                          const char *name, \
187                                          gccjit::location loc)
188
189   Construct a new field, with the given type and name.
190
191.. function:: gccjit::struct_ \
192   gccjit::context::new_struct_type (const std::string &name,\
193                                     std::vector<field> &fields,\
194                                     gccjit::location loc)
195
196     Construct a new struct type, with the given name and fields.
197
198.. function:: gccjit::struct_ \
199              gccjit::context::new_opaque_struct (const std::string &name, \
200                                                  gccjit::location loc)
201
202     Construct a new struct type, with the given name, but without
203     specifying the fields.   The fields can be omitted (in which case the
204     size of the struct is not known), or later specified using
205     :c:func:`gcc_jit_struct_set_fields`.
206