types.rst revision 1.3 
1.. Copyright (C) 2014-2017 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.. FIXME: get_const doesn't seem to exist
86
87.. function::  gccjit::type gccjit::type::get_const ()
88
89   Given type "T", get type "const T".
90
91.. function::  gccjit::type gccjit::type::get_volatile ()
92
93   Given type "T", get type "volatile T".
94
95.. function::  gccjit::type \
96               gccjit::context::new_array_type (gccjit::type element_type, \
97                                                int num_elements, \
98			                        gccjit::location loc)
99
100   Given type "T", get type "T[N]" (for a constant N).
101   Param "loc" is optional.
102
103
104Structures and unions
105---------------------
106
107.. class:: gccjit::struct_
108
109A compound type analagous to a C `struct`.
110
111:class:`gccjit::struct_` is a subclass of :class:`gccjit::type` (and thus
112of :class:`gccjit::object` in turn).
113
114.. class:: gccjit::field
115
116A field within a :class:`gccjit::struct_`.
117
118:class:`gccjit::field` is a subclass of :class:`gccjit::object`.
119
120You can model C `struct` types by creating :class:`gccjit::struct_` and
121:class:`gccjit::field` instances, in either order:
122
123* by creating the fields, then the structure.  For example, to model:
124
125  .. code-block:: c
126
127    struct coord {double x; double y; };
128
129  you could call:
130
131  .. code-block:: c++
132
133    gccjit::field field_x = ctxt.new_field (double_type, "x");
134    gccjit::field field_y = ctxt.new_field (double_type, "y");
135    std::vector fields;
136    fields.push_back (field_x);
137    fields.push_back (field_y);
138    gccjit::struct_ coord = ctxt.new_struct_type ("coord", fields);
139
140* by creating the structure, then populating it with fields, typically
141  to allow modelling self-referential structs such as:
142
143  .. code-block:: c
144
145    struct node { int m_hash; struct node *m_next; };
146
147  like this:
148
149  .. code-block:: c++
150
151    gccjit::struct_ node = ctxt.new_opaque_struct_type ("node");
152    gccjit::type node_ptr = node.get_pointer ();
153    gccjit::field field_hash = ctxt.new_field (int_type, "m_hash");
154    gccjit::field field_next = ctxt.new_field (node_ptr, "m_next");
155    std::vector fields;
156    fields.push_back (field_hash);
157    fields.push_back (field_next);
158    node.set_fields (fields);
159
160.. FIXME: the above API doesn't seem to exist yet
161
162.. function:: gccjit::field \
163              gccjit::context::new_field (gccjit::type type,\
164                                          const char *name, \
165                                          gccjit::location loc)
166
167   Construct a new field, with the given type and name.
168
169.. function:: gccjit::struct_ \
170   gccjit::context::new_struct_type (const std::string &name,\
171                                     std::vector<field> &fields,\
172                                     gccjit::location loc)
173
174     Construct a new struct type, with the given name and fields.
175
176.. function:: gccjit::struct_ \
177              gccjit::context::new_opaque_struct (const std::string &name, \
178                                                  gccjit::location loc)
179
180     Construct a new struct type, with the given name, but without
181     specifying the fields.   The fields can be omitted (in which case the
182     size of the struct is not known), or later specified using
183     :c:func:`gcc_jit_struct_set_fields`.
184