Structure

Data Type

A Structure is a compound value type. It consists of a series of fields that are grouped together as a single block. You can control the size and order of the fields. A structure can provide a convenient alternative to the MemoryBlock.

You will typically only use structures when you have very specific memory or performance requirements or when you need to interface with an outside API that requires a structure. Instead of structures, you will usually want to use a Class with the appropriate properties for most of your data management.

Methods

ByteValue

Size

StringValue

Notes

Structures cannot be created in code. You must create them in the IDE by adding a Structure to your project item.

Once you have defined a structure, you can use it in almost any context where you would use any other data type. You use the same dot syntax to access structure fields as you would use to access object properties, but when you use dot syntax with a structure, you are manipulating the structure variable itself, not a reference to data somewhere else.

ByRef works the same with Structure as it does with other non-intrinsic data types: a ByRef Structure passes the pointer to the Structure. This can be useful with Declares.

Arrays

Structure fields can be defined as arrays, using the usual array syntax:

fieldName(UBound) As DataType

Arrays in structure fields can't be manipulated in the same ways as normal arrays; they represent a fixed chunk of storage inside the structure, not a dynamic object that can be resized and manipulated. Structure field arrays cannot be resized, cannot be assigned, and do not support any of the array methods.

Strings

Strings also have a special syntax and behavior inside a structure:

fieldName As String * size

When you create fields in a structure, you indicate the number of bytes it will use. A string in a structure is a simple array of bytes. Unlike String variables, a string field has a fixed size and does not store text encoding information. If a string value contains fewer bytes than the declared size, unassigned bytes are assigned null bytes. If you use the Len function to get the length of the field, it will return the length of the string.

Just as you convert text to a specific encoding when writing it to a file or a socket, and assign the correct encoding to it when reading it back in, you must convert strings to a specific encoding when you assign them to a structure and define them to the correct encoding when reading them back out.

Using Structures

Once you've defined a structure, you can use it in almost any context where you would use any other data type. Use the dot syntax to access the fields. You can define an object or module property as a structure; you can declare a method parameter as a structure; you can even embed one structure as a field in another.

In addition to the fields you define, structures contain three built-in items:

Name	Parameters	Description
Size		This constant returns the total size of the Structure in bytes.
ByteValue	littleEndian As Boolean	Gets or sets the structure data using a byte array.
StringValue	littleEndian as Boolean	Gets the StringValue of the structure. You must pass the desired endianness, which should match the LittleEndian property on the MemoryBlock on BinaryStream. StringValue will convert the structure's fields to or from the appropriate endianness as necessary.
StringValue	littleEndian as Boolean	Sets the StringValue of the structure. You must pass the desired endianness, which should match the LittleEndian property on the MemoryBlock on BinaryStream. StringValue will convert the structure's fields to or from the appropriate endianness as necessary.

The StringValue getter and setter methods let you treat the structure as a String. This is useful for copying structures into and out of MemoryBlocks, for reading and writing structures to files, and for transmitting structures through sockets.

Structure Alignment

Introduced 2008r5

Structure alignment refers to aligning the data at a memory offset equal to some multiple of the word size. Data alignment can increase the computer's performance.

Structures can be aligned using Attributes. You add the attribute "StructureAlignment" to a structure and use one of the legal values: 0, 1, 2, 4, 8, 16, 32, 64, and 128 as the value. A value of 0 indicates that the compiler should perform a natural alignment, which ensures that the structure will be laid out correctly for a given OS platform's ABI (app binary interface) rules.

To specify a structure alignment, add an attribute to the Attribute List in the Inspector. Specify "StructureAlignment" in the Name field and enter the desired alignment value.

Sample Code

Suppose you have created a structure called Employee that is defined as follows:

EmpNumber As Integer
EmpOffice As String*50
EmpPhone As String*20

To work with the structure, you can declare a variable or property as a structure and get and set the fields that you declared. For example,

Var person As Employee
person.EmpNumber = 5
person.EmpOffice = "Tyler Hall"
person.EmpPhone = "555-1212"

Then you can get any of the values in the structure, i.e.,

MessageBox(person.EmpOffice)

You can also assign a structure to a variant. The vartype of a structure is 36. and get the value as a string or another structure. For example:

Var v As Variant

v = person // entire structure
v = person.EmpOffice // one field
v = person.StringValue(False) // Gets the entire structure as a string

If you create a public structure in a class, then you would declare an instance outside the class with the syntax ClassName.StructureName, e.g.

Var person As MyClass.Employee