Type
Declares a user-defined type.
Syntax
`
Type typename
fieldname1 As DataType
fieldname2 As DataType
...
End Type
Type typename [ Field = alignment ]
[ Private: ]
[ Public: ]
[ Protected: ]
Declare Constructor [ ( [ parameters ] ) ]
Declare Destructor [ () ]
Declare [ Static | Const ] Sub fieldname [calling convention specifier] [ Alias external_name ] [ ( [ parameters ] ) ] [ Static ]
Declare [ Static | Const ] Function fieldname [calling convention specifier] [ Alias external_name ] [ ( [ parameters ] ) ] [ As datatype ] [ Static ]
fieldname [ ( array subscripts ) | : bits ] As DataType [ = initializer ]
As DataType fieldname [ ( array subscripts ) | : bits ] [ = initializer ], ...
Declare Operator operatorname[ ( [ parameters ] ) ]
Declare Property fieldname[ ( [ parameters ] ) ] [ As datatype ]
...
End Type
`
Parameters
`alignment`
Specifies the byte alignment for data fields.
`fieldname`
Name of the data field or member procedure.
`external_name`
Name of field as seen when externally linked.
`parameters`
The parameters to be passed to a member procedure.
`array subscripts`
Subscripts to declare a fixed-length array.
`bits`
Number of bits a data field occupies.
`initializer`
Default initializer for the data field.
`operatorname`
The name of the operator to be overloaded.
`calling convention specifier`
Can be `cdecl`, `stdcall` or `pascal`.
Description
`Type` is used to declare custom data types containing one or more bit, scalar, array or other `Type` fields.
Types support member functions including `Constructor`, `Destructor`, `Function`, `Operator`, `Property` and `Sub`.
Fields default to `Public:` member access unless, `Private:` or `Protected:` is specified.
An anonymous `Union` can be nested in a `Type` declaration.
The optional `Field=number` when given will change the default field alignment. `Field=1` will disable any alignment, making the `Type` contiguous in memory.
`Type` can be used to return a temporary type variable. See `Type()`.
`Type` can be used to declare a type definition ( i.e. an alias or alternative name ) for an already declared or yet to be declared type. See `Type (Alias)`
Data fields may have an optional default `initializer` value. This default value initializes the data field immediately before any constructor is called.
`Static` immediately preceding `Sub` or `Function` indicates that no hidden `This` parameter is to be passed to the member procedure.
`Const` immediately preceding `Sub` or `Function` indicates that the hidden `This` parameter is to be considered read-only.
Warning Special care must be taken when using a user defined type for file I/O. It is recommended to use `Field = 1` for such cases, and it may be required to read files created by other applications.
UDTs that contain pointers to data should not be written to file as-is: when the data is read later, the pointers will almost certainly be invalid, and the data they pointed to will no longer be available. Instead, custom input/output routines should be used, to save the allocated data in a different format in the file. This includes UDTs containing variable-length strings.
Additionally, reading fixed length strings in UDT's from files is problematic: at present, fixed-length strings contain an extra NULL character on the end. To preserve alignment the field would need to be declared with one char less than the actual size and accessing the field by its name makes the last character unavailable. It also means there may be potential problems passing the string to functions that expect the NULL character to be there.
A better solution is to use ubyte arrays, this requires a couple of auxiliary functions converting to/from string. See the example.
Example
This is an example of a QB-style type, not including procedure definitions
`
Type clr
red As UByte
green As UByte
blue As UByte
End Type
Dim c As clr
c.red = 255
c.green = 128
c.blue = 64
`
And this is an example of a type working as an object:
`
'' Example showing the problems with fixed length string fields in UDTs
'' Suppose we have read a GIF header from a file
'' signature width height
Dim As ZString*(10+1) z => "GIF89a" + MKShort(10) + MKShort(11)
Print "Using fixed-length string"
Type hdr1 Field = 1
As String*(6-1) sig /' We have to dimension the string with 1 char
' less to avoid misalignments '/
As UShort wid, hei
End Type
Dim As hdr1 Ptr h1 = CPtr(hdr1 Ptr, @z)
Print h1->sig, h1->wid, h1->hei '' Prints GIF89 (misses a char!) 10 11
'' We can do comparisons only with the 5 visible chars and creating a temporary string with LEFT
If Left(h1->sig, 5) = "GIF89" Then Print "ok" Else Print "error"
'' Using a ubyte array, we need an auxiliary function to convert it to a string
Function ub2str( ub() As UByte ) As String
Dim As Integer length = UBound(ub) + 1
Dim As String res = Space(length)
For i As Integer = 0 To length-1
res[i] = ub(i): Next
Function = res
End Function
Print
Print "Using an array of ubytes"
Type hdr2 Field = 1
sig(0 To 6-1) As UByte '' Dimension 6
As UShort wid, hei
End Type
Dim As hdr2 Ptr h2 = CPtr(hdr2 Ptr, @z)
'' Viewing and comparing is correct but a conversion to string is required
Print ub2str(h2->sig()), h2->wid, h2->hei '' Prints GIF89a 10 11 (ok)
If ub2str(h2->sig()) = "GIF89a" Then Print "ok" Else Print "error" '' Prints ok
`
Platform Differences

- The default field alignment is 4 bytes for DOS and Linux targets.
- The default field alignment is 8 bytes for Windows targets.

Dialect Differences

- Object-related features such as functions declared inside `Type` blocks are supported only with the -lang fb dialect since version 0.17b
- In the -lang fb and -lang fblite dialects, the default field alignment depends on the target platform.
- With the -lang qb dialect the fields are aligned to byte boundaries by default, unless otherwise specified.
- To force byte alignment use `FIELD=1`.

Differences from QB

- At present, fixed-length strings have an extra, redundant character on the end, which means they take up one more byte than they do in QB. For this reason, UDTs that use them are not compatible with QB when used for file I/O.

See also

- `Type (Alias)`
- `Type (Temporary)`
- `Union`
- `Enum`
- `TypeOf`
- `OffsetOf`
- `Field`