STRUCT member types

Member declaration

Each member of a struct is identified by a member-declaration followed by an optional initialiser, and then a semi-colon.

The simplest form of member-declaration is to specify a type-name and a member-name only:

STRUCT TEST
 {
 WORD length;
 }

Type name

The type-name must be in upper case (WORD in this example).

These are the valid types:

BYTE	A single byte. Can be treated as a signed integer (–128 to +127) or unsigned integer (0 to 255).
WORD	Two bytes. Can be treated as a signed integer (–32,768 to +32,767) or unsigned integer (0 to 65,535).
LONG	Four bytes. Can be treated as a signed integer (–2,147,483,648 to 2147483647) or an unsigned integer (0 to 4,294,967,295).
DOUBLE	Eight byte real for double precision floating point numbers (approximately ±1.7E±308).
TEXT	A string, terminated by a null. This is deprecated: use LTEXT instead.
LTEXT	A Unicode string with a leading byte which holds the length of the string, and no terminating null.
BUF	A Unicode string with no terminating null and no leading byte.
BUF8	A string of 8-bit characters, with no terminating null and no leading byte. Used for putting 8-bit data into a resource.
BUF<n>	A Unicode string with no terminating null and no leading byte but which has a maximum length n. This type is an alternative to using the length-limit with BUF types.
LINK	The ID of another resource (16 bits), rather like a pointer to that resource.
LLINK	The ID of another resource (32 bits).
SRLINK	A self-referencing link. This is a 32 bit link which contains the resource ID of the resource it is defined in. An SRLINK member may not have an initialiser since it is self-referencing and, therefore, only takes the value of the resource ID the struct is declared in. This is assigned automatically by the resource compiler.
STRUCT	Any struct, rather like including that struct as a member in this struct. STRUCT members are useful because it means that once a struct has been defined it can be re-used for a variety of resources.

Note that:

• Numbers more than one byte long are stored little-endian: that is, their least significant byte is stored first.

• LINK and STRUCT are not type-safe: it is the responsibility of the user of a struct to ensure that the correct resource type is linked or included. The definer of a struct should give some idea, perhaps using a comment:

  STRUCT TEST
   {
   WORD length;
   STRUCT text; // should be a STRING 
   }

Length limits

A length limit may be specified for members of string type (BUF, TEXT and LTEXT). The length limit is enclosed in parentheses after the member name, for instance:

STRUCT TEST
 {
 TEXT string1(9);
 LTEXT string2(MAX);
 BUF string3;
 }

• string1 has a maximum of 9 characters, string2 a maximum of MAX characters (where MAX has been #defined elsewhere) and string3 has no maximum length. Note that this maximum applies only to the actual characters and does not take account of the terminating zero (for TEXT members) or leading byte (for LTEXT members).

• Note that from v5 onwards, TEXT is deprecated.

• An alternative method to using length-limit with a BUF type is to use the type BUF<n>. For example, see the definition of TEST and the resource definitions for test1, test2 and test3 in the examples below.

Member name

The member-name must be in lower case.

Examples

STRUCT TEST
 {
 BUF<4> string;
 }

RESOURCE TEST test1
 {
 string="abcd";
 }

RESOURCE TEST test2
 {
 string="ab";
 }

RESOURCE TEST test3
 {
 string="abcdef";
 }

• test1 generates 0x61 0x00 0x62 0x00 0x63 0x00 0x64 0x00

• test2 generates 0x61 0x00 0x62 0x00

• but test3 generates an error because the maximum length of string permitted by the definition of the STRUCT is 4.