Type
Declares a user-defined type.
Type typename
End Type
Type typename [ Field = alignment ]
alignment
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.
This is an example of a QB-style type, not including procedure definitions
And this is an example of a type working as an object:
Syntax
Type typename
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[ 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 ]
...
Parameters
alignment
Specifies the byte alignment for data fields.
fieldnameName of the data field or member procedure.
external_nameName of field as seen when externally linked.
parametersThe parameters to be passed to a member procedure.
array subscriptsSubscripts to declare a fixed-length array.
bitsNumber of bits a data field occupies.
initializerDefault initializer for the data field.
operatornameThe name of the operator to be overloaded.
calling convention specifierDescription
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
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
'' 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 "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
