M2compiler-V3/docs/summary_ustring-files.md

Step: UString assignment + Files on IOChan

Tag v3-ustring-files. Suite 135/135; fixpoint OK (image 2,142,363 bytes).

UString assignment

a := U"…" (a 1-D ARRAY OF UCHAR) is now a content copy, like a := "…" for CHAR arrays:

• SymTab.IsUCharArray(t) (exported) recognises a 1-D ARRAY OF UCHAR; Assignable/VarParamOk already allowed a ClUStr literal for it.
• QbeGen.UAssign emits call $m2uassign(l dst, l src).
• shim.c m2uassign: copies min(count, capacity) codepoints followed by a 0 codepoint terminator. Note: the descriptor is { l count, w codepoints… }, so the body reads/writes 32-bit elements off a 64-bit header (a first cut using long* read past the data).
• UCHAR arrays now reserve a terminator slot, like CHAR arrays: ArrBodyItems emits z (n+1)*4 bytes, HeapSize/InitHeap reserve and zero it, and the fixed/open bounds checks allow index n (ArrayHi + 1, OpenHiChar).
• A U"…" literal and a UCHAR array both pass to an open VAR ARRAY OF UCHAR formal.

Files layered on IOChan

Files no longer binds the shim directly; it sits on IOChan:

• IOChan gained a bridge for layered libraries: Handle(cid) : ADDRESS and MakeChan(h : ADDRESS) : ChanId.
• Files.FileRec holds an IOChan.ChanId; OpenRead/OpenWrite NEW a record around the channel, Close closes and DISPOSEs. All I/O delegates to IOChan (ReadChar/ReadString/ReadInt, WriteChar/WriteString/WriteInt/WriteLn), with NIL guards.
• Files gained ReadString (one line), matching IOChan.

The public Files API is unchanged apart from the added ReadString.

Showcase

compiler/tests/showcase16.mod (Showcase16, exit 42) ties the session together: a Shape variant record (id + CASE k OF circle|square|rect), a U"ok✓" content copy into a UCHAR array, and a write/read round-trip through a Files handle (itself an IOChan channel). Output:

showcase16: id=3 total=42

Tests

• t_ustrassign.mod (63): content copy, truncation to capacity, terminator, non-ASCII round-trip.
• t_ustrformal.mod (3): array and literal to an open VAR ARRAY OF UCHAR.
• Showcase16 (42).
• Suite file lists for FilesProg/TBadFile/MixProg/Showcase11 now include SysShim + IOChan (the new Files base layer).

Files

compiler/src/{SymTab.def,SymTab.mod} (IsUCharArray), compiler/src/{QbeGen.def,QbeGen.mod} (UAssign, UCHAR terminator layout), compiler/src/M2.atg (UCHAR assignment branch, bounds), runtime/syslib/shim.c (m2uassign), stdlib/{iochan,files}.def/.mod, compiler/tests/{t_ustrassign,t_ustrformal,showcase16}.mod, compiler/run_tests.sh, docs/features.md.