Gambas Documentation
Application Repository
Code Snippets
Compilation & Installation
Controls pictures
Deprecated components
Developer Documentation
Development Environment Documentation
Error Messages
Gambas Playground
How To's
Language Index
Language Overviews
Arithmetical Functions
Arithmetic Operators
Array Declaration
Assignment Operators
Binary Data Representation
Bits Manipulation Functions
Character Test Functions
Comparison methods
Complex numbers
Constant Declaration
Constant Expression
Conversion Functions
Datatype Functions
Date & Time Functions
Enumeration declaration
Error Management
Event Loop
Event Management
Events declaration
External Function Management
File & Directory Functions
File & Directory Paths
File mode syntax
Floating Point Numbers
Formatting functions
Gambas Object Model
Global Special Event Handlers
Integer numbers
Intrinsic Functions
Language Constants
Localization and Translation Functions
Local Variable Declaration
Logarithms & Exponentials Functions
Logical Operators
Loop Control Structures
Method Declaration
Miscellaneous Control Structures
Miscellaneous Functions
Native Arrays
Native Container Classes
Object & Class Management
Operator Evaluation Order
Predefined Constants
Process Management
Property Declaration
Random Numbers Functions
Special Methods
Stream & Input/Output functions
String Functions
String Operators
Structure declaration
Test Control Structures & Functions
Trigonometric Functions
User-defined formats
Using reserved keywords as identifiers
Variable Declaration
Last Changes
Search the wiki
To Do
Wiki License
Wiki Manual

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


' Gambas class file

  Length AS Float
  NumberOfFingers AS Integer
  HasGlove AS Boolean

  Length AS Float
  NumberOfFingers AS Integer
  HasSock AS Boolean
  HasShoe AS Boolean

  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

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