| Note | This command is only available in the VO and Vulcan dialects |
Purpose
Declare a union entity and its member names.
Syntax
[Modifiers] UNION <idUnion> [ALIGN 1|2|4|8]
MEMBER <idVarList> AS | IS <idType> [ ,…]
MEMBER DIM <ArraySpec> [ ,…] AS | IS <idType> [ ,…]
[END UNION]
Note: The MEMBER statement is shown using two syntax diagrams for convenience. You can declare variables and dimensioned arrays using a single MEMBER statement if each definition is separated by a comma.
Arguments
| Modifiers | An optional list of modifiers that specify the visibility or scope of the entity, such as PUBLIC, STATIC, INTERNAL, EXPORT and UNSAFE. |
| <idUnion> | A valid identifier name for the union. A union is an entity and shares the same name space as other entities. This means that it is not possible to have a union and a constant, for example, with the same name. |
| MEMBER | Declares one or more union member variables or dimensioned arrays. You can specify multiple MEMBER declarations on separate lines. |
| <idVarList> | A comma-separated list of identifier names for the union member variables. |
| DIM <ArraySpec> | The specification for a dimensioned array to use as a union member. <ArraySpec> is one of the following: |
| <idArray>[<nElements>, <nElements>, <nElements>] |
| <idArray>[<nElements>],[<nElements>], [<nElements>] |
| All dimensions except the first are optional. |
| <nElements> defines the number of elements in a particular dimension of an array. The number of dimensions is determined by how many <nElements> arguments you specify. |
| <nElements> can be a literal numeric representation or a simple numeric expression involving only operators, literals, and DEFINE constants; however, more complicated expressions (such as function calls) are not allowed. |
| AS <idType> | Specifies the data type of the variable you are declaring (called strong typing). For DIM arrays, declares the data type for all array elements. The AS <idType> is required for all union members. |
| Refer to the CLASS entry for a list of valid values for <idType>. Note that the following data types are not supported in unions because they are dynamic types that require garbage collection: |
oARRAY
oFLOAT
oOBJECT
o<idClass>
oSTRING
oUSUAL
o
| IS <idType> | Specifies a union data type in which the memory needed to hold the union is allocated on the stack (i.e., <idUnion> is the only <idType> allowed with the IS keyword). |
| ALIGN 1|2|4|8 | Specifies the memory alignment of the structure. The default is 4, which means that all members are aligned at DWORD boundaries, since that gives the best performance on a 32 bits platform and is also the default alignment for most C/C++ compilers. You may want to change this when you need to match a C/C++ structure that has been defined with a different alignment (the #pragma pack in a C/C++ header file). |
| Note: The default alignment for C/C++ compilers is 4 as well, unless the structure contains doubles (REAL8 in XSharp). In that case the C/C++ compiler uses an alignment of 8. XSharp does NOT automatically choose an alignment of 8, so you must add the ALIGN 8 to your structure in these circumstances. |
Description
UNIONs are like STRUCTUREs, but all members start at offset zero (0). In other words, assigning a value to a union member affects all other union members. As the size of the union is equal to the size of the biggest member, changing one member will change all of the others because they occupy the same memory.
You use the UNION statement to mark the beginning of the definition of a union entity, followed by one or more MEMBER statements that define what the union looks like.
Examples
The following is a conversion example:
UNION wb ALIGN 1
MEMBER w AS WORD
BYTE bLo AS BYTE
BYTE bHi AS BYTE
FUNCTION x
LOCAL u IS wb
u.w := 0x1234
? u.bLo // 52 (=0x34)
? u.bHi // 18 (=0x12)
See Also
