Create a new User-Defined Type definition whose member elements overlap in memory.
MemberName [(subscripts)] AS TypeName
[MemberName [(subscripts)] AS TypeName]
A union is a type - very similar to a User-Defined Type - except that its elements overlap in memory. While this may seem strange at first, it has enormous potential.
For example, say you are designing an accounting program. You want to make it general purpose so it has widespread appeal. But everyone does their accounting differently; for example, some people use account numbers that are plain integral values, while others may use alphanumeric account names. Using a Union makes this easy. Another common use of a Union is variable type conversion. The is best described by way of an example:
iLong AS LONG
iDword AS DWORD
sStr AS STRING * 4
DIM x AS VarConvert, y AS DWORD, z AS STRING
x.iLong = 123456&
y = x.iDword
z = x.sStr
Like a User-Defined Type, a Union may also contain arrays, and these follow the same rules as User-Defined Type member arrays (see Type Members for syntax rules and additional examples). The following example demonstrates the use of a Union member array:
a1(1 TO 1024) AS BYTE
st AS ASCIIZ * 10
DIM a AS Arrs
a.a1(1) = 72
a.a1(2) = 101
a.a1(3) = 108
a.a1(4) = 108
a.a1(5) = 111
a.a1(6) = 33
' At this point, a.st contains "Hello!"
UNION structures may contain bit variables, which are named BIT (unsigned values) or SBIT (signed values). Each bit variable may occupy from 1 to 31 bits, and they may be packed one after another up to a total of 32 bits per bit field. The size of a bit variable is defined as follows:
var AS BIT * nlit [IN BYTE|WORD|DWORD]
…where the term "* nlit" defines the number of bits (1 to 31), and the optional term "IN BYTE|WORD|DWORD", if present, defines the start of a new bit field of 1, 2, or 4 bytes. For example:
Odd1 AS BIT * 1 IN DWORD
Value1 AS LONG
The example UNION structure above is 4 bytes in size, containing a 1-byte bit field and a 4-byte LONG.
Part1 AS BIT * 8 IN DWORD
Part2 AS BIT * 16
The example union above is 4 bytes in size, containing an 8-bit field and an overlapping 16-bit field.
Structures within structures
Structures (TYPE/UNION) may be embedded within another structure, for simplification in referencing deeply nested items, by simply stating the structure name alone at the appropriate position. The internal alignment of the member structure is precisely maintained regardless of other alignment specifications, to foster inheritance issues. For example:
In this case, you could access the lone Single-precision float member of this structure very simply. Assuming DIM X AS ABCD3, you could reference the Single-precision Union member with the variable name X.H, instead of the extended syntax X.ABCD2.ABCD1.H
A Union can contain elements of dissimilar sizes. The size of a Union structure is always determined by the longest member element. This is usually an important consideration when using a Union within another Union or UDT structure, in order to determine the size of the final structure.
Field strings cannot be used in UDT or UNION structures. Attempting to do so results in a compile-time Error 485 ("Dynamic/Field strings not allowed").
AccountNumber AS LONG
AccountName AS STRING * 16
Account AS AccountUnion
Amount AS CUR
DIM JournalEntry AS JournalEntryType
JournalEntry.Account.AccountName = "Smith"
JournalEntry.Amount = 123.01@
' process journal entry here
JournalEntry.Account.AccountNumber = 1001
JournalEntry.Amount = -1.99@