`Struct` Statement

Declares the name of a structure and gives its implementation.

Syntax

[ modifiers ] _
Struct struct_name [ type_list ] [ Is base_type ] [ Does trait_list ]
    [ Where generic_constraints ]
    …
    [ data_members ]
    [ procedure_members ]
End [ Struct ]

Parts

modifiers

Optional modifiers:

@Deprecated – See @Deprecated.
@MustUse – Code that calls a procedure that returns the structure type must use the result. See @MustUse.

struct_name

Mandatory name for the structure.

type_list

Optional one or more type parameters, with a comma between each, all between brackets ([ ]). See Type List for more information.

Is

A keyword before base_type.

You can also use one of the non-reserved keywords Extends or Inherits as an alternative.

base_type

Optional value type: an elementary data type (Int32 for example) or the name of a different structure.

trait_list

Mandatory after Does, one or more traits, with a comma between each. See Does Clause (Traits) for more information.

Where

Optional keyword that you can use again and again. See Where Clause (Generics) for more information.

data_members

Mandatory one or more declaration statements. You can use Const, Dim, Enum, and Event.

procedure_members

Optional procedure declarations. You can use Constructor, Function, Method, Property, and Sub.

End

Completes the statement. You can also use End Struct.

You can change this part of the syntax. See @Option Directive for more information.

Instructions

Struct is short for “structure”.

You can put a structure only in some locations. These include modules (Program and Library), and declarations of Class, Object, and Trait. You cannot put a structure in a procedure. See Declaration Contexts and Default Access Levels for more information.

Bit fields

A bit field is an integer member with a width in bits specified in code. You use the data types SBits and UBits only in a structure. You must supply the width between parentheses after one of these keywords. The width must be an integer literal in the range 1 thru 128.

Optionally you can supply a value type between the keyword and the left parenthesis, written between brackets ([ ]). This is known as the storage boundary type. If supplied, the width must be in the range one thru the size of the type in bits.

UBits is short for “unsigned bit field”.

SBits is short for “signed bit field”. When you use SBits, the most significant bit is reserved as a sign bit.

If you supply a storage boundary, each field uses some number of bits from the storage. You typically try to use all of the bits in one or more field declarations. But if there are bits that are not used, these are known as padding.

If a structure mixes bit fields and named types, the named types will usually be put in boundaries. The type of CPU sets the boundaries, counted from the start of the Struct: Intel processors usually have 8-bit boundaries, while Motorola processors usually have 16-bit boundaries. A bit field must not go across a boundary.

Changes in syntax with `@Option`

There are two areas where you can change the syntax of the statement:

@Option Type Extends, @Option Type Inherits, @Option Type Is
@Option End Block and @Option End

See @Option Directive for more information.

Rules

Nested structures: You can put one structure in a different structure. The outer structure contains the inner (or nested) structure. But you cannot get access to the elements of an inner structure through the outer structure. You must declare a variable with the data type of the inner structure.
Member declaration: TODO
Initialization: TODO
Inheritance: TODO
Traits: Traits, supplied with the clause Does, must be abstract. You must supply implementations for all procedures declared by all the traits.

Behavior

Access level: Structures and their members are public by default. But the procedure types Function and sub are always private.
Scope: A structure is in scope all through its container element (namespace, module, class, or structure). The scope of all members of a structure is the full structure.
Lifetime: A structure, as a data type, does not have a lifetime. But each instance of a structure has a lifetime. You control the lifetime of an instance by how and where you declare it.
Qualification: Code that is not in the structure must qualify the name of a member with the name of that structure. If code in an inner structure refers to an un-qualified name, ViviFire tries to find it in the inner structure. If it does not find the element, it tries the next outer block in sequence.
Memory used: TODO

Examples

Struct point
    x As Real64
    y As Real64
End Struct

Struct Statement