Development documentation · Some APIs may be unreleased Published release →

Guides

Reference types and value types

Choose a type by what copying it should mean. A class gives an object a shared identity. A struct represents a value whose fields are copied when the value is assigned or passed by value. neoCLR follows the .NET reference/value model, with Raven providing the declarations and compiler-generated record members.

Operation Reference type, such as a class Value type, such as a struct
Assignment or by-value argument Copies a reference to the same object Copies the value's fields
Mutation through one copy Other aliases see the same object's changes The other value's own fields are independent
Reference fields inside it Refer to other objects Still refer to the same objects after copying
Default equality Object identity for ordinary classes Same runtime type and equal instance fields
Conversion to Object Retains object identity Boxes a copy in managed storage

Neither kind of assignment performs a deep clone. Copying a struct containing an array reference does not copy the array's elements. Readonly access prevents writes through that access path; it does not make every referenced object immutable.

A small value, with an optional Object view

This struct represents two numbers:

struct Plain {
    val Number: int
    val Stamp: long
    init(number: int, stamp: long) {
        Number = number
        Stamp = stamp
    }
}

Two independently constructed values can have the same contents:

let first = Plain(42, 4294967297L)
let second = Plain(42, 4294967297L)
let boxed: Object = first
let another: Object = second

first.Equals(second) and boxed.Equals(another) compare the fields. The two separate boxes have different identities, so Object.ReferenceEquals(boxed, another) is false. Equal values have equal hash codes, but a matching hash does not prove equality. Never persist hash codes or use them as unique identifiers.

Ordinary structs use runtime-provided default equality and hashing. A custom Equals(Object) override takes precedence; pair it with a matching GetHashCode(). Reference fields use their own equality contracts: a class without an override compares by identity, while a class with an override can compare its contents.

EquatableTo<T> is an explicit, user-implemented typed contract. It allows a comparison to accept T directly instead of requiring an Object argument. It does not make conversion of a struct into an interface object allocation-free. Typed and supported constrained calls can avoid boxing; an Object or interface conversion can still need a box.

Records express compiler-generated behavior

A record class is still a reference type; a record struct is still a value type. Raven generates their equality and other supported record members. That generated behavior is separate from the runtime's ordinary struct fallback. Default struct value equality does not automatically declare EquatableTo<T> or add == and != operators to every ordinary struct.

Development native record-struct display supports the qualified scalar, nested-record and closed-union shapes. Imported value components can use their declared public ToString() contract; Index and Range are covered by built-in tests. Generated calls avoid component boxing, although returned strings and builder storage allocate. Int32-backed enum components reuse ordinary enum display for names, flags and numeric fallback; that path currently allocates a temporary enum box. Single and Double components use primitive value equality and display: NaNs compare equal, and signed zeros share equality and hashes. Their generated hashing currently boxes through Object. Generic record formatting and record-class formatting remain gaps in native support.

String is a reference type with content equality. neoCLR deliberately uses canonical Unicode equality over preserved UTF-8 storage, so string fields follow that text contract rather than .NET's default ordinal String equality. See strings and UTF-8 for explicit ordinal operations.

Allocation follows storage and lifetime

“Value type” does not mean “always on the stack.” A value can live in a local, a register, an array element, a class field or a managed box. A value embedded in an existing object does not require its own object allocation. References inside values still keep their targets reachable by the GC.

Small values can avoid temporary wrapper objects, but copying large values has a cost. Boxing also allocates storage and copies the value. Choose classes when shared identity and ownership fit the problem, and structs when independent copied values fit it. Allocation for a useful result or owner is appropriate; repeated temporary boxes and copied buffers deserve attention.

Slice<T> and ReadOnlySlice<T> are borrowed value views with additional lifetime rules. Memory<T> and ReadOnlyMemory<T> retain an owner and can cross asynchronous suspension. Copying any of these views shares the underlying storage rather than copying its contents. See slices and memory.

Development coverage

Ordinary struct defaults are development functionality. The example and nested, generic, empty and reference-field cases pass interpreter, JIT and AOT checks. Floating fields also pass these checks, including NaN and signed-zero equality. Int32-backed enum fields use exact enum type and underlying-value equality. Enum display now supports names, flags and unnamed numeric values. Development Enum.Parse<TEnum> returns a typed Result; TryParse<TEnum> writes an output value and returns Boolean. Both accept names, signed decimal values and comma-separated names, with explicit optional case folding. Int32 storage and ASCII member names remain the current boundary. Enum type arguments are checked at runtime; compile-time enum constraints remain a gap. See the Enum reference and parsing contract. Numeric primitives now support Formattable and boxed floating-point display. This does not yet cover every .NET field shape or dispatch path. The Object API guide records the supported contracts and implementation evidence tracks execution-mode validation.

Object API · Garbage collection · .NET comparison

Development qualification now covers signed, unsigned and native-width integer equality, hashes and decimal display through Object, including narrow sign/zero extension and UInt64 boundaries. These use existing scalar boxes and formatting services; Object conversion still allocates a box. Floating boxed display uses the shared numeric formatting implementation; custom formats and providers remain gaps.

Development primitive interface support preserves each scalar value type's declared interfaces when boxed. Interface calls borrow that box's payload and invoke the same value method used by direct calls; converting to an interface does not create a second box. This includes narrow/unsigned/native-width integers, floating values, Boolean and Character. Exact generic arguments remain significant, and the runtime does not invent undeclared equality interfaces. Int32 and Int64 also implement Formattable for bounded culture-aware D/F/N formatting; other numeric format coverage remains a gap.

The development primitive library explicitly implements EquatableTo<T> for all signed, unsigned and native-width integers, Single, Double, Boolean and Character. Typed Equals calls do not require boxing; storing a value in an interface does. Floating Equals treats NaNs as equal and positive/negative zero as equal, matching Object equality and hashing; IEEE == retains its NaN behavior. Character equality keeps canonical grapheme semantics. This does not synthesize the interface for user structs.

Numeric primitives implement Formattable: integers support bounded G/D/F/N; Single and Double support G/R/F/N/E, shortest round-trip output and explicit precision. Parse(text, culture) accepts the corresponding decimal/group conventions and validates grouping; ordinary Parse(text) stays invariant. See formatting and culture for the supported profiles and limitations.

Development Single and Double expose NaN, PositiveInfinity, and NegativeInfinity as constant fields, plus IsNaN, IsInfinity, IsPositiveInfinity, IsNegativeInfinity, and IsFinite. Use IsNaN rather than comparing a value with NaN. These constants and classification calls do not allocate. See the numeric API guide.

Development Decimal adds finite base-ten arithmetic with a 96-bit coefficient and scale 0–28. It uses ordinary value-type semantics and the existing Number, EquatableTo<Decimal> and Formattable contracts. Equality and hashing ignore scale differences; general formatting preserves them. Arithmetic uses value-type scratch storage rather than temporary arrays. See the Decimal API and current limits.

Generic capabilities

See Generics for type parameters, function constraints, return-type projection and methods whose whole signature materializes from a function-constrained generic argument. These are development capabilities.