Arrays

An array is a managed reference to a fixed-length sequence of mutable elements. Write its type as T[].

int32[] values = [1, 2, 3];
values[1] = 4;
println(values[1]);
println(values::length);

The index must have type int32 (int is its alias). ::length is a read-only int32 query. Negative indices and indices at or beyond the length trap on both reads and writes.

Literals and element types

Elements are evaluated from left to right. Numeric literals can use an explicit array element type, as in int64[] values = [1, 2, 3];.

Elements infer a type from the first non-null element. Null or nullable elements make that element type nullable. Different managed-reference types join at object.

string?[] labels = ["first", null];
object[] mixed = ["text", [1, 2]];

Empty literals and null-only literals are unsupported, including with an explicit array type. Repeated [] suffixes, resizable arrays, slices, and multidimensional array syntax are also unsupported.

Runtime-sized construction

Use T[:length] when the fixed length is known only while the program is running:

int32 count = ReadCount();
int32[] values = int32[:count];
User?[] users = User?[:count];

The length expression is evaluated once and must be implicitly compatible with int32. Zero is valid. A negative constant is rejected by the compiler; a negative runtime value terminates with cloth runtime error: array length is negative.

Integer and floating elements start at zero, bool starts at false, and char starts at U+0000. Nullable elements start absent. Non-null references, enums, structs, and nested arrays cannot be constructed this way because Cloth does not invent a default object, enum case, or struct value.

The result is an ordinary non-null T[]. Its length never changes, while its elements retain normal checked reads and writes.

References and copying

Array assignment copies the reference. Equality compares array identity, not element contents. An indexed struct read copies the struct value; reference elements continue to refer to the same objects.

Arrays are invariant: User[] cannot be assigned to object[]. An entire array can widen to object, which does not permit writing arbitrary elements into it.

final protects an array binding but allows element updates:

final int32[] values = [1, 2];
values[0] = 3;

Nullability

Narrow a nullable array before indexing or iterating. Its length may be queried safely with values?::length. Primitive, enum, struct, and reference element types may all be nullable, so int32?[], Status?[], and Point?[] are valid.

Iteration

int32[] values = [1, 2, 3];
for (final var value in values) {
  println(value);
}

The array expression is evaluated once. The loop visits increasing indices and creates a local element copy for each iteration. Reassigning that binding does not replace the array element. break exits; continue advances to the next element. An explicit binding type uses ordinary assignment compatibility.

There is currently no general iterator protocol or string iteration. Runtime is and as checks targeting array types are unsupported.