Managed arrays
An array is fixed-size managed storage. Assigning it shares the same array; changing an element is visible through its aliases. neoCLR keeps these familiar .NET behaviors while giving arrays a generic API shape and invariant element types.
Arrays have a structural runtime shape and a nominal Array<T> representation.
Both describe the same intrinsic array; Array<T> does not wrap or copy it.
Structural type families explain how this differs
from tuples, unions, intersections and functions.
Array aliasing and copying
The array holds three readings. A second name changes the same storage, and a Sequence view sees that correction. ToList then copies the integer elements into a separate collection, preserving those readings while the original array changes.
import System.*
import System.Console.*
import System.Collections.*
import System.Linq.*
func Main() {
// Correct a reading through another name for the same fixed-size array.
let readings: int[] = [18, 20, 21]
let same: Array<int> = readings
let view: Sequence<int> = readings
same[1] = 22
WriteLine("Number of readings:")
WriteLine(readings.Length)
WriteLine("Read-only view sees the correction:")
WriteLine(view[1])
// Materializing the integer values creates independent collection storage.
let snapshot = readings.ToList()
readings[0] = 19
WriteLine("Snapshot then current reading:")
WriteLine(snapshot[0])
WriteLine(view[0])
WriteLine("Current readings:")
readings.ForEach(value => WriteLine(value))
WriteLine("Empty array length:")
WriteLine(Array<int>.Empty.Length)
WriteLine("Array element type:")
WriteLine(typeof(Array<int>).GetGenericArguments()[0].DisplayName)
}
let prevents rebinding the local name; it does not freeze the array. A Sequence exposes reading, but other aliases can still replace elements. The snapshot here contains integers: copying references into a new collection would still share the referenced objects.
Expected output
Number of readings:
3
Read-only view sees the correction:
22
Snapshot then current reading:
18
19
Current readings:
19
22
21
Empty array length:
0
Array element type:
System.Int32
Download the complete sample → · Expected output → · Run with the preview toolchain →
Compared with .NET arrays
| Concern | .NET / C# | neoCLR / Raven target |
|---|---|---|
| Storage and assignment | Arrays are reference types. Assignment shares storage; each instance has fixed dimensions. | Ordinary T[] is a managed reference. Assignment aliases the same fixed-size array. |
| Element access | Zero-based vectors have checked indices. Invalid indexing throws IndexOutOfRangeException. |
Zero-based vectors have runtime bounds checks. Invalid indexing causes a terminal Fault, not a catchable guest exception. |
| API shape | T[] derives from nongeneric System.Array; vector arrays also expose generic collection interfaces. | T[] and System.Array<T> resolve to the same intrinsic array. The generic spelling does not wrap or copy it. |
| Element-type conversion | Reference arrays allow covariance, with runtime store checks. Value-element arrays do not have that covariance. | Mutable arrays are invariant. An array of derived elements cannot become an array of base elements. |
| Replacement versus growth | Vectors implement IList<T>, although fixed-size arrays reject growth operations. | MutableSequence<T> permits replacement. Arrays do not implement the growable List<T> contract. |
| Helpers | Array.Empty<T>() and static Array.ForEach(array, action). | Array<T>.Empty and instance array.ForEach(action). Empty-array identity caching is not promised. |
| Dimensions | Vectors, rectangular multidimensional arrays and jagged arrays. | The documented Raven subset is vectors and nested arrays; rectangular multidimensional arrays are outside this subset. |
The generic shape makes the element type and ordinary members available together. Invariance avoids covariant array-store failures, but programs relying on .NET reference-array conversions need adaptation. Separating replacement from growth gives a more precise contract, at the cost of a different interface vocabulary. These are deliberate tradeoffs, not a performance claim or full .NET compatibility.
Comparison references: Microsoft’s C# array guide and .NET 10 System.Array reference. See the neoCLR implementation contract for metadata and compiler details.
Managed storage, checked by the runtime
The runtime owns array storage and traces live references through the managed heap. Keeping an array reachable keeps its reference elements reachable too. Byte and integer elements are values; object elements retain references. The ordinary reference-array path supports default null reference slots; dispatch through a null element faults. This does not settle the broader nullability proposal.
Bounds and element compatibility are runtime responsibilities, not just source-language diagnostics. Direct IL tests exercise invalid indices, incompatible elements and references surviving collection. The generic array shape reuses those checks. There is no separate user-allocated object behind Array<T>.
A byte array is a useful I/O buffer, but being managed does not make it safe for a native operation to retain an untracked address. Pending I/O still needs explicit rooting, mutation and cancellation rules. A read-only view does not prove exclusive ownership.
Supported operations and limits
The API includes Length, Count, indexed access, iteration, Empty and ForEach, with the runtime’s supported element types. The generic shape is not a promise that every possible element signature or .NET Array helper is admitted. Direct array loops use indexed access; Iterable consumers use the declared interface contract.
Development slicing returns Slice<T>: both array[range] and
array.Slice(range) borrow the same storage. Writes through the slice affect the
array. Request an independent shallow copy with array[range].ToArray().
Valid empty windows succeed and invalid bounds fault without clamping. Array
no longer implements Sliceable<T[]>; array-specific and owned-result APIs still
use arrays. This deliberately replaces the former copy-based range contract.
See the slice API. Array-backed byte slices also run in native JIT/AOT, including indexing,
updates, readonly borrowing and nested windows. Memory/ReadOnlyMemory retain
windows across asynchronous use in the interpreter and native JIT/AOT, including
collection, socket and TLS completion checks. Borrowed readonly UTF-8 byte views
also run natively. Other native element specializations remain unqualified. Array size and allocation remain constrained by runtime budgets.
Read-only interface views support reference variance; mutable array storage remains invariant.
Buffer experiments and planned work
Socket, TLS and HTTP operations now use byte memory windows with explicit aliasing, completion and cancellation contracts. The slices and memory guide explains the distinction between immediate borrowed access and retained asynchronous buffers. Shared stream interfaces remain the next integration boundary.
Platform roadmap → · Collection capabilities →
Questions and contributions
Include the required access and lifetime when reporting an array issue. This distinguishes a missing library operation from a missing runtime guarantee.
Questions, sample programs and documentation corrections are welcome. See how to contribute for ways to participate.
Index and Range
The matching development compiler and native libraries support values[^1],
from-end assignment and half-open slices such as values[1..^1] and values[..].
Each array slice shares storage. ToArray makes an independent shallow copy.
^0 describes the end boundary, so it can end a slice but cannot select an element.
Indexing and slicing syntax are convenience APIs that may fault on invalid bounds;
callers must establish valid input. values.Get(index) returns an Optional<T> for
an integer or Index. values.Slice(range) returns Slice<T>.
Index and Range describe positions and boundaries; applying them determines validity.
Raven uses .. for an exclusive end and ..= for an inclusive end in slices,
range patterns and integer iteration. Inclusive Range construction checks endpoint
conversion before arithmetic; the library Range contract remains half-open.
String slices use grapheme boundaries. Sequences and lists also
support indexing and slicing. Native byte views are qualified; other native element specializations remain unqualified.
Signed int/long range patterns follow the same endpoints. A long subject currently
requires long literal bounds, such as 1L..=3L. Signed int/long loops and
comprehensions stop before advancing would overflow, including an inclusive maximum
endpoint. Other numeric stepping domains are not covered by this guarantee.
Explicit Interval progressions remain design work.