types.rst revision 1.1.1.2
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 20Types 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 31Types 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 52Standard 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 97Pointers, `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 121Structures and unions 122--------------------- 123 124.. c:type:: gcc_jit_struct 125 126A compound type analagous to a C `struct`. 127 128.. c:type:: gcc_jit_field 129 130A field within a :c:type:`gcc_jit_struct`. 131 132You 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 252