Structure
From REALbasicWiki
| Overall article skill |  ✭ |
Structures are user-defined REALbasic datatypes, analogous to structs in C. A structure consists of a collection of fields, each of which has a datatype; different fields may have different datatypes.
Contents |
[edit] Defining a Structure
Structure declarations live in modules. To add a structure declaration to a module, open its code editor, and choose the menu item 
Project ▶ Add ▶ Structure .
[edit] Structure Fields
A structure field declaration has one of the following forms.
name as Type
name(UBound) as Type
name as String*size
The type of a field can be any of the REALbasic value types, including user-defined structures and enumerations. Reference types, such as objects, strings, resizeable arrays, and CFStringRef are not allowed. Structures have their own, non-reference-based string and array types.
The second form allows you to define a field to be a fixed-size array of Type. Structure arrays can only have one dimension, and do not offer any of the resizing methods on the normal array type.
The third form defines a fixed-length string field. You can assign a normal string value to this field. If the new string is longer than the destination field, it will be truncated; if it is shorter, it will be null-padded. You can use a string field in a string expression; trailing nulls will be truncated, and the string will have an unknown encoding. The String data is copied to/from the field, since string fields are mutable and REALbasic string values are not. Here is an example:
Structure Foo Value as String*4
Now in REALbasic code, we can do things like the following.
dim f as Foo
f.Value = "moof"
dim s as String = f.Value
Setting the type to CString, PString, or WString creates a field of pointer size that should point to a string of the declared format. You can also create fixed-length string fields using these types; if you specify a length, then you get a fixed-size buffer instead of a pointer.
[edit] Initialization
Like all other datatypes, structure variables and properties are initialized for you by REALbasic. Thus the code
dim f as Foo
results in a valid structure, zero-initialized.
[edit] Visibility
Structures can be declared as public, protected, or private.
[edit] Properties
All structure types come equipped with some properties. For each structure type, its fields are properties. They should autocomplete in the IDE. And all structures come with the following.
[edit] Size as Integer
This shared constant returns the size of the structure in bytes. You can access this constant using either a structure variable or property, or as a property of the datatype itself. For example, suppose your project has a structure called HIOParam; then either of the following would be legal:
dim N as Integer = HIOParam.Size
dim paramBlock as HIOParam
dim N as Integer = paramBlock.Size
[edit] StringValue(littleEndian as Boolean) as String
StringValue allows you to get or set the contents of the structure as a String.
[edit] Assignment and Parameter Passing
Assignment of structures is by value. That is, assignment of a structure variable means that the structure is copied. Here is an example.
Let Foo be a structure with a single field, value as Int32.
dim f as Foo
f.value = 3
dim g as Foo = f
g.Value = 2
After this code executes, you can check to see that f.Value = 3, but g.Value = 2; f and g hold two different Foo.
Structures can be passed to and returned from methods. By default, structures are passed to methods by value; that is, a copy is made of the structure, and it is the copy that is passed. Structures can also be passed by reference, which means that a pointer to the structure is passed to the method.
Currently, delegates cannot return a structure.
[edit] External Methods
Structures can be passed to and returned from external methods. When declaring an external method, you can declare parameters and return types as structure types. For external methods that return a pointer to a structure, you must declare the return type as Ptr and dereference the return value yourself, for which, see below.
[edit] Pointers to Structures
REALbasic does not provide a way to get a pointer to a structure. But sometimes you need one when working with external libraries. What you must do is to create a MemoryBlock, and copy the structure to it.
dim f as Foo
dim m as MemoryBlock = f.StringValue(not targetBigEndian)
Here is another way to do it; note that this code also creates a copy of the original structure.
dim f as Foo
dim m as new MemoryBlock(Foo.Size)
dim p as Ptr = m
p.Foo(0) = f
Now you can assign m (or p) to a Ptr field of another structure, for example.
REALbasic does support defererencing pointers to structures (see also the discussion for Ptr).
dim f as Foo = p.Foo
//or
dim f as Foo = p.Foo(offset)
