The Inform 6 Programmer's Guide

Chapter 8: Arrays

This chapter describes arrays: how they are declared, the five array types and their distinct memory layouts, how entries are read and written, and the idioms used to work with arrays in practice.

8.1 Array Declarations

An array is declared at the top level of a source file using the Array directive. The general syntax is:

Array name [static] type initializer ;

where name is a new identifier, type is one of the five array type specifiers (->, -->, string, table, or buffer), and initializer provides the array's size or initial values (see §8.3).

Array inventory_flags -> 20;
Array room_exits --> 50;
Array title string "Zork";
Array scores table 0 0 0 0 0;
Array input_buffer buffer 120;

The Array directive creates a global constant whose value is the byte address of the start of the array's data area in memory. This address can be stored in variables, passed to routines, and used with the -> and --> operators to access individual entries.

[ PrintArrayAddress arr;
    print "Array starts at byte address ", arr, "^";
];

[ Main;
    PrintArrayAddress(inventory_flags);
];

Array names occupy the same namespace as other global identifiers. An array name must not duplicate the name of any global variable, constant, routine, object, or other array. The compiler reports an error if the name is already defined.

8.2 Array Types

There are five array types, differing in entry size and whether an automatic length field is stored at the front of the array.

8.2.1 Byte Arrays (->)

A byte array stores one byte (0-255) per entry. Entries are accessed with the -> operator:

Array flags -> 10;            ! 10 bytes, all initialised to 0

[ Main;
    flags->0 = 1;              ! set first entry
    flags->9 = 255;            ! set last entry
    print flags->0, "^";      ! prints 1
];

Byte arrays have no overhead - the array identifier points directly to the first data byte, and N entries occupy exactly N bytes.

8.2.2 Word Arrays (-->)

A word array stores one machine word per entry. The --> operator accesses entries by word index:

Array high_scores --> 5;       ! 5 words, all initialised to 0

[ Main;
    high_scores-->0 = 1000;
    high_scores-->4 = 500;
    print high_scores-->0, "^";  ! prints 1000
];

[Z-machine] Each word is 2 bytes. A word array of N entries occupies N * 2 bytes. Words are stored in big-endian order (most significant byte first).

[Glulx] Each word is 4 bytes. A word array of N entries occupies N * 4 bytes. Words are likewise stored in big-endian order.

8.2.3 String Arrays

A string array stores byte-sized entries with an automatic length byte at position 0. The length byte records the number of data entries (not including itself). Data entries begin at index 1:

Array greeting string "Hello";

[ Main;
    print greeting->0, "^";     ! prints 5 (the length)
    print (char) greeting->1;   ! prints 'H'
    print (char) greeting->5;   ! prints 'o'
];

Because the length is stored in a single byte (0-255), a string array can hold at most 255 data entries (indices 1-255). The compiler reports an error if a string array would exceed this limit. Total memory consumed is 1 + N bytes, where N is the number of entries.

8.2.4 Table Arrays

A table array stores word-sized entries with an automatic word-length count at position 0. The count records the number of data entries. Data entries begin at index 1:

Array primes table 2 3 5 7 11 13;

[ Main  i;
    print primes-->0, "^";      ! prints 6 (the count)
    for (i = 1 : i <= primes-->0 : i++)
        print primes-->i, " ";  ! prints 2 3 5 7 11 13
];

Table arrays have no practical limit on entry count (beyond available memory). Total memory consumed is (1 + N) * WORDSIZE bytes.

8.2.5 Buffer Arrays

A buffer array is a hybrid type: it stores a word-sized length count followed by byte-sized data entries. The length word occupies the first WORDSIZE bytes (2 on the Z-machine, 4 on Glulx). Data bytes begin at byte offset WORDSIZE:

Array input_buffer buffer 120;

[ Main;
    print input_buffer-->0, "^";             ! prints 120 (the count)
    print input_buffer->(WORDSIZE), "^";     ! first data byte
];

Buffer arrays combine word and byte access in a single structure. On Glulx, the standard library uses this layout for text input buffers (see §8.8), where buffer-->0 stores a character count and the data bytes begin at offset WORDSIZE.

Total memory consumed is WORDSIZE + N bytes, where N is the number of data entries.

8.2.6 Summary of Array Types

Type Entry size Length field Data starts at Access operator
-> (byte) 1 byte None index 0 arr->i
--> (word) 1 word None index 0 arr-->i
string 1 byte 1 byte at arr->0 index 1 arr->i
table 1 word 1 word at arr-->0 index 1 arr-->i
buffer 1 byte 1 word at arr-->0 byte offset WORDSIZE arr->i (for data)

8.3 Initializers and Sizing

Every array declaration must specify either a size (number of entries) or a list of initial values. The compiler supports four forms of initializer.

8.3.1 Numeric Size (Zero-Filled)

A single numeric expression after the type keyword creates an array of that many entries, all initialized to zero:

Array buffer -> 100;           ! 100 zero-initialised bytes
Array rooms --> 20;            ! 20 zero-initialised words
Array text_buf buffer 80;      ! 80-byte buffer with length word

The size expression must be a compile-time constant. The compiler reports an error if the value is zero or negative.

[Z-machine] The maximum array size is 32767 entries.

8.3.2 Value List

A sequence of two or more expressions after the type keyword creates an array with one entry per expression, initialized to the given values:

Array directions --> 1 2 3 4 5 6 7 8;
Array vowels -> 'a' 'e' 'i' 'o' 'u';

Each expression is evaluated as a compile-time constant. Constants, literal values, previously defined symbols, and expressions involving these are all permitted:

Constant BASE = 100;
Array thresholds --> BASE BASE*2 BASE*3 BASE+50;

For byte arrays (->, string, buffer), each value must fit in the range 0-255. If a value of 256 or greater is given, the compiler issues a warning and truncates the value to its low byte. Negative values are likewise reduced to their low byte (so -1 becomes 255). On the Z-machine - the default target - a negative initializer is treated as its unsigned 16-bit value (-1 becomes 65535), which exceeds 255, so the same out-of-range warning is emitted (under Glulx it is not); supply the unsigned equivalent (255) explicitly to avoid it.

8.3.3 String Initializer

A double-quoted string after the type keyword initialises the array from the character codes of the string:

Array greeting -> "Hello, world!";
Array encoded string "xyzzy";

Each character in the string becomes one array entry. On the Z-machine, characters are converted to ZSCII values; characters that have no ZSCII representation (or that map to ZSCII 5, which is reserved) produce a compiler error and are replaced with ? in the stored data. On Glulx, characters are stored as Unicode code points: in a byte array (->, string, buffer) any character with code point 256 or higher produces a compiler error ("Unicode characters beyond Latin-1 cannot be used in a byte array"); in a word array (-->, table) the full 32-bit code point is stored verbatim and no range check is performed.

String initialisers are valid for all five array types, though they are most natural with byte arrays and string arrays.

Note - two distinct uses of strings in array declarations. The form above (a single quoted string immediately after the type keyword) stores the character codes of the string as successive array entries - one byte (or word) per character. By contrast, a value list made up of multiple string literals - e.g. Array names table "red" "green" "blue"; - does not store characters: each element is the packed address of a separate compiled string, so the array holds three printable-string values. See §8.8.2 for that pattern.

8.3.4 Bracketed Value List

A list of expressions enclosed in square brackets provides the same semantics as an unbracketed value list, but allows the values to span multiple source lines. Semicolons between entries are optional:

Array colour_table -->
    [   $FF0000     ! red
        $00FF00     ! green
        $0000FF     ! blue
        $FFFF00     ! yellow
    ];

The bracket form is also the only way to declare a one-entry array with an initial value, since a single expression without brackets is interpreted as a size:

Array single --> [ 42 ];       ! one-entry array holding 42
Array forty_two --> 42;        ! 42-entry array of zeroes (NOT the same)

Zero-entry arrays are never permitted; the compiler requires at least one entry regardless of the initializer form.

8.4 Static Arrays

By default, arrays are placed in writable (dynamic) memory and can be modified at runtime. The static keyword places an array in read-only memory instead:

Array sine_table static --> 0 174 342 500 643 766 866 940 985 1000;
Array help_text static string "Type HELP for instructions.";

The static keyword must appear between the array name and the type keyword. A static array should always provide initial values, since its contents cannot be changed after compilation.

Array lookup static -> 10;     ! legal but pointless: 10 zeroes, read-only

[Z-machine] Static arrays are placed in readable memory above the static memory boundary (after the dictionary, before code storage). They can be read at runtime but writes are undefined - the virtual machine may silently ignore the write or may halt with an error, depending on the interpreter.

[Glulx] Static arrays are placed in the ROM area (after string storage). Attempting to write to ROM is a memory access violation and will produce a runtime error in conforming interpreters.

The compiler additionally rejects, at compile time, any assignment whose left-hand side is a direct reference to a static array's name:

Array sine_table static --> 0 174 342 500 643 766 866 940 985 1000;

[ Main;
    sine_table-->0 = 99;       ! compile-time error: "Cannot write to a static array"
];

This static check applies whenever the compiler can recognise the array through its identifier. Writes that arrive indirectly (for example, via a variable that has been assigned the array's address) cannot be detected at compile time and fall under the platform-specific runtime behaviour described above.

Static arrays are useful for lookup tables, constant data, and any array whose values are known at compile time and should not be altered during play. Using static arrays where possible reduces the amount of writable memory consumed, which can be important on the Z-machine where dynamic memory is limited.

8.5 Reading and Writing Array Elements

8.5.1 Byte Access (->)

The -> operator reads or writes a single byte at a given byte offset from the array's base address:

Array data -> 5;

[ Main;
    data->0 = 10;              ! write byte at offset 0
    data->4 = 20;              ! write byte at offset 4
    print data->0;             ! read byte at offset 0 → prints 10
];

The expression arr->index computes the byte address arr + index and loads or stores one byte at that address. The index is zero-based.

8.5.2 Word Access (-->)

The --> operator reads or writes a machine word at a given word offset from the array's base address:

Array data --> 5;

[ Main;
    data-->0 = 1000;           ! write word at index 0
    data-->4 = 2000;           ! write word at index 4
    print data-->0;            ! read word at index 0 → prints 1000
];

The expression arr-->index computes the byte address arr + index * WORDSIZE and loads or stores one word at that address.

8.5.3 Accessing String, Table, and Buffer Arrays

For string and table arrays, index 0 holds the count of data entries. Data entries begin at index 1:

Array names table 'a' 'b' 'c';

[ Main  i;
    for (i = 1 : i <= names-->0 : i++)
        print (char) names-->i, " ";
    ! prints: a b c
];

For buffer arrays, the count is a word at byte offset 0 (accessed as arr-->0), and data bytes begin at byte offset WORDSIZE (accessed as arr->WORDSIZE, arr->(WORDSIZE+1), etc.):

Array buf buffer 10;

[ Main  i;
    ! Manually fill buffer data
    buf->WORDSIZE     = 'X';
    buf->(WORDSIZE+1) = 'Y';
    for (i = 0 : i < 2 : i++)
        print (char) buf->(WORDSIZE + i);
    ! prints: XY
];

8.5.4 Assignment Forms

Array element references are valid on the left-hand side of any assignment operator:

Array counters --> 4;

[ Main;
    counters-->0 = 100;        ! simple assignment
    counters-->0++;             ! post-increment
    ++counters-->1;             ! pre-increment
    counters-->2 = counters-->2 + 5;   ! compound update
];

8.5.5 Bounds Checking

By default, the compiler emits runtime bounds checks on array accesses when compiling for Z-machine version 5 or later, or for Glulx. When the compiler can identify the array statically (the left-hand side of -> or --> is the array's own name), it inserts an explicit comparison of the index against the declared size, calling the runtime error veneer if the index is negative or beyond the last valid entry. When the array reference is indirect (for example, an address held in a variable), the compiler instead routes the access through the veneer routines RT__ChLDB, RT__ChLDW, RT__ChSTB, and RT__ChSTW, which verify that the proposed read or write falls within the legal memory region.

This behaviour is controlled by the -S ("Strict mode") compiler switch:

Setting Z-machine v3 / v4 Z-machine v5+ / Glulx
Default off on
-S on on
-~S off off

When strict checking is disabled - either explicitly with -~S, or by default in Z-machine v3/v4 - the compiler performs no bounds checking at all. Reading or writing beyond the declared extent of an array accesses whatever bytes happen to lie at that memory address - potentially other arrays, global variables, or object data. The behavior is undefined and can cause subtle, hard-to-diagnose bugs:

Array small -> 3;

[ Main;
    small->3 = 99;             ! out of bounds - undefined behaviour
                               !   without -S; runtime error with -S
    small->100 = 1;            ! far out of bounds - may corrupt anything
];

Even with strict checking enabled, it is the programmer's responsibility to ensure that all array indices are within the valid range: a runtime error halts the story, which is rarely what the player wants. Keeping the array size in a separate constant (or using a table/string/buffer array whose length field tracks the count) is strongly recommended.

8.6 Array Memory Layout

Understanding how arrays are laid out in memory is important for interoperability with assembly code, for debugging, and for writing platform-portable programs.

8.6.1 Byte Arrays (->)

A byte array of N entries occupies N contiguous bytes. The array identifier holds the address of the first byte. No header or padding is added.

Offset:   0     1     2         N-1
        +-----+-----+-----+...+-----+
        | b0  | b1  | b2  |   |bN-1 |
        +-----+-----+-----+...+-----+

8.6.2 Word Arrays (-->)

A word array of N entries occupies N * WORDSIZE contiguous bytes. Each word is stored in big-endian order.

[Z-machine] WORDSIZE is 2. A word array of 4 entries occupies 8 bytes. Each entry is a 2-byte big-endian value.

[Glulx] WORDSIZE is 4. A word array of 4 entries occupies 16 bytes. Each entry is a 4-byte big-endian value.

                  Z-machine (WORDSIZE = 2)
Offset:    0     1     2     3     4     5     6     7
        +-----+-----+-----+-----+-----+-----+-----+-----+
        |w0_hi|w0_lo|w1_hi|w1_lo|w2_hi|w2_lo|w3_hi|w3_lo|
        +-----+-----+-----+-----+-----+-----+-----+-----+

                  Glulx (WORDSIZE = 4)
Offset:    0     1     2     3     4     5     6     7
        +-----+-----+-----+-----+-----+-----+-----+-----+
        |        word 0         |        word 1         |
        +-----+-----+-----+-----+-----+-----+-----+-----+

8.6.3 String Arrays

A string array has a one-byte length prefix at offset 0, followed by N data bytes at offsets 1 through N. The length byte holds N (the count of data entries, not the total allocation). Because the length byte is one byte, N may not exceed 255.

Offset:   0     1     2         N
        +-----+-----+-----+...+-----+
        | len | d1  | d2  |   | dN  |
        +-----+-----+-----+...+-----+

Total size: 1 + N bytes.

8.6.4 Table Arrays

A table array has a one-word length prefix at word index 0, followed by N data words at word indices 1 through N:

Word index:   0       1       2           N
            +-------+-------+-------+...+-------+
            | count | d1    | d2    |   | dN    |
            +-------+-------+-------+...+-------+

Total size: (1 + N) * WORDSIZE bytes.

8.6.5 Buffer Arrays

A buffer array has a one-word length prefix (occupying WORDSIZE bytes) followed by N data bytes:

Byte offset:  0 .. WORDSIZE-1   WORDSIZE   WORDSIZE+1       WORDSIZE+N-1
            +-----------------+----------+----------+...+----------+
            |    count (word) |    d1    |    d2    |   |    dN    |
            +-----------------+----------+----------+...+----------+

The count word is accessed as arr-->0. Data bytes are accessed as arr->WORDSIZE, arr->(WORDSIZE+1), and so on.

Total size: WORDSIZE + N bytes.

8.7 Multi-Dimensional Arrays

There is no built-in syntax for multi-dimensional arrays. All arrays are one-dimensional sequences of bytes or words. However, two-dimensional (and higher) arrays can be simulated with index arithmetic.

8.7.1 Simulating a 2D Array

The standard convention is to store a two-dimensional grid in row-major order in a word array, and compute the linear index as row * COLS + col:

Constant ROWS = 4;
Constant COLS = 5;
Array grid --> ROWS * COLS;    ! 20-entry word array

[ GridGet row col;
    return grid-->(row * COLS + col);
];

[ GridSet row col value;
    grid-->(row * COLS + col) = value;
];

[ Main  r c;
    ! Fill the grid with r*10 + c
    for (r = 0 : r < ROWS : r++)
        for (c = 0 : c < COLS : c++)
            GridSet(r, c, r * 10 + c);

    ! Read back a value
    print GridGet(2, 3), "^";  ! prints 23
];

8.7.2 Array of Arrays

An alternative approach uses a word array of pointers to other arrays:

Array row0 --> 10 20 30;
Array row1 --> 40 50 60;
Array row2 --> 70 80 90;

Array matrix --> row0 row1 row2;

[ MatrixGet row col;
    return (matrix-->row)-->col;
];

[ Main;
    print MatrixGet(1, 2), "^";  ! prints 60
];

This approach uses more memory (one pointer per row plus the row arrays themselves) but allows rows of different lengths.

8.8 Common Patterns

8.8.1 Text Input with Buffer Arrays

The text-input mechanism differs between platforms. On the Z-machine, the read statement handles keyboard input. On Glulx, input is performed through Glk calls (typically wrapped by the standard library). Both platforms expect a text buffer and a parse buffer, but the required array layouts differ.

[Z-machine] The Z-machine read opcode expects a byte array for text input: byte 0 holds the maximum number of characters allowed, and after reading, byte 1 holds the number of characters typed, with characters stored from byte 2 onwards. The standard library declares this as a simple byte array:

Constant INPUT_BUFFER_LEN = WORDSIZE + 120;
Array  buffer  -> INPUT_BUFFER_LEN + 1;

[Glulx] The Glulx standard library uses a buffer array for text input: buffer-->0 holds the character count (written back after input), and the data bytes begin at offset WORDSIZE.

Constant INPUT_BUFFER_LEN = WORDSIZE + 256;
Array  buffer  buffer (INPUT_BUFFER_LEN - WORDSIZE);

Here is a minimal Z-machine example using the read statement with the correct byte-array layout:

Array text_buffer -> 123;          ! byte 0 = max chars (120)
Array parse_buffer -> 65;          ! parse buffer

[ Main;
    text_buffer->0 = 120;          ! set max characters allowed
    print "What now? ";
    read text_buffer parse_buffer;
    ! text_buffer->1 now holds the number of characters typed.
    ! Characters are in text_buffer->2 onwards.
];

8.8.2 Lookup Tables

Table arrays are natural for lookup tables where the code iterates over a known set of entries:

Array colour_names table
    "red" "green" "blue" "yellow" "white" "black";

[ PrintColour n;
    if (n >= 1 && n <= colour_names-->0)
        print (string) colour_names-->n;
    else
        print "unknown";
];

Because colour_names-->0 holds the entry count, adding or removing entries from the source declaration automatically updates the loop bound - no separate constant is needed.

Note. Although the entries are written as quoted strings, this is a value list of string constants, not a string initialiser. Each array element holds a packed string address, which is why the loop body uses (string) colour_names-->n to print the referenced string. Contrast with Array msg -> "red" (see §8.3.3), where the three character codes 'r', 'e', 'd' are stored as bytes directly in the array.

8.8.3 Parallel Arrays

When multiple pieces of data are associated with each logical record, parallel arrays provide a simple solution:

Constant MAX_ENEMIES = 10;
Array enemy_health -> MAX_ENEMIES;
Array enemy_damage -> MAX_ENEMIES;
Array enemy_x --> MAX_ENEMIES;
Array enemy_y --> MAX_ENEMIES;

[ HurtEnemy i amount;
    if (enemy_health->i <= amount)
        enemy_health->i = 0;
    else
        enemy_health->i = enemy_health->i - amount;
];

8.8.4 Tracking Array Bounds

Disciplined size tracking is essential to avoid out-of-bounds errors. The three main strategies are:

  1. Use a constant for byte and word arrays:

    Constant BUF_SIZE = 64;
    Array buf -> BUF_SIZE;
    
    [ SafeWrite index value;
        if (index >= 0 && index < BUF_SIZE)
            buf->index = value;
    ];
    
  2. Use the built-in length field for table, string, and buffer arrays:

    Array items table 'a' 'b' 'c';
    
    [ PrintAll  i;
        for (i = 1 : i <= items-->0 : i++)
            print (char) items-->i, " ";
    ];
    
  3. Use a sentinel value to mark the end of data:

    Array names --> "alpha" "beta" "gamma" 0;
    
    [ CountNames  i;
        for (i = 0 : names-->i ~= 0 : i++) ;
        return i;
    ];
    

8.8.5 Static Lookup Tables

Constant data that never changes at runtime should use the static keyword to conserve writable memory:

Array directions static table
    "north" "south" "east" "west"
    "northeast" "northwest" "southeast" "southwest"
    "up" "down" "in" "out";

[ DirectionName n;
    if (n >= 1 && n <= directions-->0)
        return directions-->n;
    return "nowhere";
];

8.8.6 String Arrays for Character Data

String arrays provide a compact way to store short, fixed character sequences where the length is needed at runtime:

Array vowels static string "aeiou";

[ IsVowel ch  i;
    for (i = 1 : i <= vowels->0 : i++)
        if (vowels->i == ch) rtrue;
    rfalse;
];

8.8.7 Copying Arrays

There is no built-in array copy operation. Copying must be done element by element:

Constant SIZE = 10;
Array source --> SIZE;
Array dest --> SIZE;

[ CopyWordArray src dst n  i;
    for (i = 0 : i < n : i++)
        dst-->i = src-->i;
];

[ Main;
    source-->0 = 42;
    source-->1 = 99;
    CopyWordArray(source, dest, SIZE);
    print dest-->0, " ", dest-->1, "^";   ! prints 42 99
];