Dense arrays and buffers

A dense array represents a rectangular coordinate space. Use a list for a growing sequence and an array when dimensions and coordinate bounds matter, such as a board, image grid or numeric table.

Declare coordinates

DIM board(1 TO 2, 1 TO 3) AS INTEGER
board(1, 2) = 7
PRINT LEN(board)
PRINT LBOUND(board, 1)
PRINT UBOUND(board, 2)
PRINT board(1, 2)
REDIM PRESERVE board(0 TO 3, 1 TO 4)
PRINT board(1, 2)
PRINT board(0, 1)

DIM bounds are inclusive. DIM values(9) AS INTEGER allocates ten cells, from 0 through 9. By contrast, ARRAY(length) is a zero-based length constructor. LBOUND/UBOUND dimension numbers start at 1; coordinate values follow the declared bounds. LEN is the total cell count, rather than the length of one dimension.

Cells get valid defaults: numeric zero, FALSE, empty strings, NONE optionals, independent empty containers, and recursively valid record defaults. An enum without a zero member or a choice without an unambiguous default needs a valid initializer. Arrays cannot manufacture valid open files as default cells.

Resize deliberately

REDIM constructs a replacement shape. PRESERVE retains the intersection of the old and new coordinate spaces in every dimension. It does not simply preserve the first N physical cells. New coordinates receive valid defaults; removed cells are destroyed. Resource cells in the intersection move once into the new storage.

Bounds, rank and offset arithmetic are checked, with fatal errors for invalid array coordinates or shapes. Rank belongs to the value, while AS ARRAY OF T names its element type. A helper must use the actual bounds/rank it accepts. No borrowed element address may survive a resize. Indexed BYREF access protects the array owner for the call, so a later argument cannot resize that storage.

ToArray accepts a BYVAL list and returns a zero-based rank-one array. Copyable inputs remain independent; named resource lists require TAKE. Chapter 10 shows optional resource cells and initialized resource lists.

Capacity and initialized length

For high-throughput binary work, a packed LIST OF BYTE is often appropriate. Capacity is reserved storage; length counts initialized elements. Reserving room does not create bytes that can be read. Use Reserve to avoid repeated growth, Resize for initialized content, Truncate to reduce length, and CopyWithin for checked overlapping copies. Exact overloads and return values are in the buffer reference part.

DIM bytes AS LIST OF BYTE = [BYTE(65), BYTE(66), BYTE(67)]
PRINT LEN(bytes)
PRINT DecodeUtf8(bytes)
copy = bytes
copy[0] = BYTE(90)
PRINT DecodeUtf8(bytes)
PRINT DecodeUtf8(copy)

Binary bytes are not automatically text. DecodeUtf8 validates the sequence and can report StringError. Use ReadBinaryFile for packed BYTE data; the legacy ReadFileBytes returns a list of INTEGER byte values. Choosing packed data avoids the per-element storage cost of wide integer bytes.