DataType # Structure --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Description 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. ## Properties

table-centered_columns_3_and_4

| Name | Type | Read-Only | Shared | |------------------------|------------------------------------|-----------|--------| | `Size` | `Integer` | ✓ | | ## Methods

table-centered_column_4

| Name | Parameters | Returns | Shared | |--------------------------------------|----------------------------------------------------|---------------------------------------------------|--------| | `ByteValue` | littleEndian As `Boolean` | `UInt8()` | | | `StringValue` | littleEndian As `Boolean` | `String` | | ## Property descriptions

forsearch

Structure.Size **Size** As `Integer` > The total size of the Structure in bytes. > > This property is read-only. > >

> >

> > Important > >

> > This property is not currently supported for Android. > >

## Method descriptions

forsearch

Structure.ByteValue **ByteValue**(littleEndian As `Boolean`) As `UInt8()` > Gets the Structure data using a byte array. > >

> >

> > Important > >

> > This method is not currently supported for Android. > >

forsearch

Structure.StringValue **StringValue**(littleEndian As `Boolean`) As `String` > Gets the StringValue of the Structure. > > The StringValue getter and setter methods let you treat the Structure as a String. This is useful for copying structures into and out of `MemoryBlock`, for reading and writing structures to files, and for transmitting structures through sockets. > >

> >

> > Important > >

> > This method is not currently supported for Android. > >

## 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.

Important

For Android, the following types are supported for use with \`Structures\`: `Integer`, `UInteger`, `Double`, `Single`, `Int64`, `UInt64`, `Int32`, `UInt32`, `Int16`, `UInt16`, `Int8`, `UInt8`, `Byte`, `Boolean`, `CGFloat`, `Color`, `String`, `CString`, `PString`, `WString` and `Ptr`.

Important

Properties of type Array are not currently supported for Android Structures.

--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Strings Strings also have a special syntax and behavior inside a \`Structure\`: ``` xojo 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. | 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: ``` xojo 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, ``` xojo 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., ``` xojo 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: ``` xojo 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. ``` xojo Var person As MyClass.Employee ``` ## Compatibility | | | |-----------------------|-----| | **Project Types** | All | | **Operating Systems** | All |

`Declare` command; `Variant` data type; `VarType` function; `BinaryStream`, `MemoryBlock` classes, `Advanced Language Features-Structures` topic