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] 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 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.
[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)
Now you can assign m 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)
