diff options
Diffstat (limited to 'docs/LangRef.html')
| -rw-r--r-- | docs/LangRef.html | 141 |
1 files changed, 109 insertions, 32 deletions
diff --git a/docs/LangRef.html b/docs/LangRef.html index 9590609..b337b6a 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -66,12 +66,17 @@ </li> <li><a href="#t_derived">Derived Types</a> <ol> - <li><a href="#t_array">Array Type</a></li> + <li><a href="#t_aggregate">Aggregate Types</a> + <ol> + <li><a href="#t_array">Array Type</a></li> + <li><a href="#t_struct">Structure Type</a></li> + <li><a href="#t_pstruct">Packed Structure Type</a></li> + <li><a href="#t_union">Union Type</a></li> + <li><a href="#t_vector">Vector Type</a></li> + </ol> + </li> <li><a href="#t_function">Function Type</a></li> <li><a href="#t_pointer">Pointer Type</a></li> - <li><a href="#t_struct">Structure Type</a></li> - <li><a href="#t_pstruct">Packed Structure Type</a></li> - <li><a href="#t_vector">Vector Type</a></li> <li><a href="#t_opaque">Opaque Type</a></li> </ol> </li> @@ -1404,6 +1409,7 @@ Classifications</a> </div> <a href="#t_pointer">pointer</a>, <a href="#t_vector">vector</a>, <a href="#t_struct">structure</a>, + <a href="#t_union">union</a>, <a href="#t_array">array</a>, <a href="#t_label">label</a>, <a href="#t_metadata">metadata</a>. @@ -1418,12 +1424,12 @@ Classifications</a> </div> </tr> <tr> <td><a href="#t_derived">derived</a></td> - <td><a href="#t_integer">integer</a>, - <a href="#t_array">array</a>, + <td><a href="#t_array">array</a>, <a href="#t_function">function</a>, <a href="#t_pointer">pointer</a>, <a href="#t_struct">structure</a>, <a href="#t_pstruct">packed structure</a>, + <a href="#t_union">union</a>, <a href="#t_vector">vector</a>, <a href="#t_opaque">opaque</a>. </td> @@ -1561,6 +1567,21 @@ Classifications</a> </div> possible to have a two dimensional array, using an array as the element type of another array.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> <a name="t_aggregate">Aggregate Types</a> </div> + +<div class="doc_text"> + +<p>Aggregate Types are a subset of derived types that can contain multiple + member types. <a href="#t_array">Arrays</a>, + <a href="#t_struct">structs</a>, <a href="#t_vector">vectors</a> and + <a href="#t_union">unions</a> are aggregate types.</p> + +</div> + </div> <!-- _______________________________________________________________________ --> @@ -1629,9 +1650,9 @@ Classifications</a> </div> <h5>Overview:</h5> <p>The function type can be thought of as a function signature. It consists of a return type and a list of formal parameter types. The return type of a - function type is a scalar type, a void type, or a struct type. If the return - type is a struct type then all struct elements must be of first class types, - and the struct must have at least one element.</p> + function type is a scalar type, a void type, a struct type, or a union + type. If the return type is a struct type then all struct elements must be + of first class types, and the struct must have at least one element.</p> <h5>Syntax:</h5> <pre> @@ -1754,6 +1775,53 @@ Classifications</a> </div> </div> <!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> <a name="t_union">Union Type</a> </div> + +<div class="doc_text"> + +<h5>Overview:</h5> +<p>A union type describes an object with size and alignment suitable for + an object of any one of a given set of types (also known as an "untagged" + union). It is similar in concept and usage to a + <a href="#t_struct">struct</a>, except that all members of the union + have an offset of zero. The elements of a union may be any type that has a + size. Unions must have at least one member - empty unions are not allowed. + </p> + +<p>The size of the union as a whole will be the size of its largest member, + and the alignment requirements of the union as a whole will be the largest + alignment requirement of any member.</p> + +<p>Unions members are accessed using '<tt><a href="#i_load">load</a></tt> and + '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with + the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction. + Since all members are at offset zero, the getelementptr instruction does + not affect the address, only the type of the resulting pointer.</p> + +<h5>Syntax:</h5> +<pre> + union { <type list> } +</pre> + +<h5>Examples:</h5> +<table class="layout"> + <tr class="layout"> + <td class="left"><tt>union { i32, i32*, float }</tt></td> + <td class="left">A union of three types: an <tt>i32</tt>, a pointer to + an <tt>i32</tt>, and a <tt>float</tt>.</td> + </tr><tr class="layout"> + <td class="left"> + <tt>union { float, i32 (i32) * }</tt></td> + <td class="left">A union, where the first element is a <tt>float</tt> and the + second element is a <a href="#t_pointer">pointer</a> to a + <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning + an <tt>i32</tt>.</td> + </tr> +</table> + +</div> + +<!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_pointer">Pointer Type</a> </div> <div class="doc_text"> @@ -1991,6 +2059,14 @@ Classifications</a> </div> the number and types of elements must match those specified by the type.</dd> + <dt><b>Union constants</b></dt> + <dd>Union constants are represented with notation similar to a structure with + a single element - that is, a single typed element surrounded + by braces (<tt>{}</tt>)). For example: "<tt>{ i32 4 }</tt>". The + <a href="#t_union">union type</a> can be initialized with a single-element + struct as long as the type of the struct element matches the type of + one of the union members.</dd> + <dt><b>Array constants</b></dt> <dd>Array constants are represented with notation similar to array type definitions (a comma separated list of elements, surrounded by square @@ -2009,7 +2085,8 @@ Classifications</a> </div> <dt><b>Zero initialization</b></dt> <dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a - value to zero of <em>any</em> type, including scalar and aggregate types. + value to zero of <em>any</em> type, including scalar and + <a href="#t_aggregate">aggregate</a> types. This is often used to avoid having to print large zero initializers (e.g. for large arrays) and is always exactly equivalent to using explicit zero initializers.</dd> @@ -3845,7 +3922,8 @@ Instruction</a> </div> <div class="doc_text"> -<p>LLVM supports several instructions for working with aggregate values.</p> +<p>LLVM supports several instructions for working with + <a href="#t_aggregate">aggregate</a> values.</p> </div> @@ -3862,14 +3940,14 @@ Instruction</a> </div> </pre> <h5>Overview:</h5> -<p>The '<tt>extractvalue</tt>' instruction extracts the value of a struct field - or array element from an aggregate value.</p> +<p>The '<tt>extractvalue</tt>' instruction extracts the value of a member field + from an <a href="#t_aggregate">aggregate</a> value.</p> <h5>Arguments:</h5> <p>The first operand of an '<tt>extractvalue</tt>' instruction is a value - of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> type. The - operands are constant indices to specify which value to extract in a similar - manner as indices in a + of <a href="#t_struct">struct</a>, <a href="#t_union">union</a> or + <a href="#t_array">array</a> type. The operands are constant indices to + specify which value to extract in a similar manner as indices in a '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p> <h5>Semantics:</h5> @@ -3896,16 +3974,15 @@ Instruction</a> </div> </pre> <h5>Overview:</h5> -<p>The '<tt>insertvalue</tt>' instruction inserts a value into a struct field or - array element in an aggregate.</p> - +<p>The '<tt>insertvalue</tt>' instruction inserts a value into a member field + in an <a href="#t_aggregate">aggregate</a> value.</p> <h5>Arguments:</h5> <p>The first operand of an '<tt>insertvalue</tt>' instruction is a value - of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> type. The - second operand is a first-class value to insert. The following operands are - constant indices indicating the position at which to insert the value in a - similar manner as indices in a + of <a href="#t_struct">struct</a>, <a href="#t_union">union</a> or + <a href="#t_array">array</a> type. The second operand is a first-class + value to insert. The following operands are constant indices indicating + the position at which to insert the value in a similar manner as indices in a '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction. The value to insert must have the same type as the value identified by the indices.</p> @@ -4107,8 +4184,8 @@ Instruction</a> </div> <h5>Overview:</h5> <p>The '<tt>getelementptr</tt>' instruction is used to get the address of a - subelement of an aggregate data structure. It performs address calculation - only and does not access memory.</p> + subelement of an <a href="#t_aggregate">aggregate</a> data structure. + It performs address calculation only and does not access memory.</p> <h5>Arguments:</h5> <p>The first argument is always a pointer, and forms the basis of the @@ -4118,15 +4195,15 @@ Instruction</a> </div> indexes the pointer value given as the first argument, the second index indexes a value of the type pointed to (not necessarily the value directly pointed to, since the first index can be non-zero), etc. The first type - indexed into must be a pointer value, subsequent types can be arrays, vectors - and structs. Note that subsequent types being indexed into can never be - pointers, since that would require loading the pointer before continuing - calculation.</p> + indexed into must be a pointer value, subsequent types can be arrays, + vectors, structs and unions. Note that subsequent types being indexed into + can never be pointers, since that would require loading the pointer before + continuing calculation.</p> <p>The type of each index argument depends on the type it is indexing into. - When indexing into a (optionally packed) structure, only <tt>i32</tt> integer - <b>constants</b> are allowed. When indexing into an array, pointer or - vector, integers of any width are allowed, and they are not required to be + When indexing into a (optionally packed) structure or union, only <tt>i32</tt> + integer <b>constants</b> are allowed. When indexing into an array, pointer + or vector, integers of any width are allowed, and they are not required to be constant.</p> <p>For example, let's consider a C code fragment and how it gets compiled to |