Structure declaration
PUBLIC STRUCT Identifier
Field 1 AS Datatype
Field 2 AS Datatype
.
.
.
Field n AS Datatype
END STRUCT
This keyword declares a structure.
Internally, a structure is exactly like a class that would have only public variables ;
but you can declare them as embedded structures or embedded arrays of structures,
as explained below.
When using embedded structures, or embedded arrays of structure, the interpreter has to create
temporary objects so that you can manipulate them like real objects. And this is slower!
Consequently,
DON'T USE STRUCTURES, UNLESS YOU HAVE TO! For example, to
communicate with a shared C-library function that requires C structures.
Although structures must be declared
PUBLIC, being second-class citizens, they cannot be used outside of the class code.
If you declare the same structure in two different classes, they must have exactly the same fields,
otherwise the interpreter will raise an error.
Embedded Arrays
You can have embedded arrays in structures using
PUBLIC STRUCT Identifier
...
Field k [ Embedded array declaration ] AS Datatype
...
END STRUCT
Fields Alignment
Structures are never packed, i.e. fields are aligned to a memory
address that is a multiple of its memory length:
-
A Boolean or a Byte can be stored at any address.
-
A Short is stored at an even address.
-
An Integer is stored at an address that is a multiple of four.
-
...and so on.
As the declaration order is respected, you may have holes in your structure.
For example, if you declare a Byte field and just after an
Integer field, you will have a three bytes hole.
There is a problem then: when compiling the C source code, the C compiler may reorder structure fields.
And, as far as I know, that process is not standardized nor documented.
There may be a solution in the future with the libffi library used by Gambas.
Apparently, that library can send a structure to a C function by taking that problem into account. But that
library is far less documented than Gambas, so you see the difficulty!
Embedded Structures
A structure can be embedded inside a normal class or another structure, by declaring a variable with the following syntax:
[ PRIVATE | PUBLIC ] Identifier AS STRUCT Structure name
Example
' Gambas class file
PUBLIC STRUCT Arm
Length AS Float
NumberOfFingers AS Integer
HasGlove AS Boolean
END STRUCT
PUBLIC STRUCT Leg
Length AS Float
NumberOfFingers AS Integer
HasSock AS Boolean
HasShoe AS Boolean
END STRUCT
PUBLIC STRUCT Man
FirstName AS String
LastName AS String
Age AS Integer
Eyes AS String
LeftArm AS STRUCT Arm
RightArm AS STRUCT Arm
LeftLeg AS STRUCT Leg
RightLeg AS STRUCT Leg
END STRUCT
Arrays Of Structure
Identifier [ Dimensions ] AS STRUCT Structure name
The structures are embedded, i.e. their contents is directly allocated inside the array.
Such arrays are not real arrays, they have only a few methods of the original array class:
-
They can be accessed by index.
-
They can be enumerated.
-
You can get information about the array length and array dimensions.
That's all!
You can create only embedded array of structures.
See also