gcc/jit/docs/cp/topics/types.rst

   1 .. Copyright (C) 2014-2015 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
  20 Types
  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
  28 Types 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
  55 Standard 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
  78 Pointers, `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
 104 Structures and unions
 105 ---------------------
 106
 107 .. class:: gccjit::struct_
 108
 109 A compound type analagous to a C `struct`.
 110
 111 :class:`gccjit::struct_` is a subclass of :class:`gccjit::type` (and thus
 112 of :class:`gccjit::object` in turn).
 113
 114 .. class:: gccjit::field
 115
 116 A field within a :class:`gccjit::struct_`.
 117
 118 :class:`gccjit::field` is a subclass of :class:`gccjit::object`.
 119
 120 You 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`.