Fluentsoft.Ref.Demo 5.0.2

Fluentsoft.Ref

High-performance, zero-allocation ref struct collections, source abstractions, and query operators for .NET.

Fluentsoft.Ref provides fixed-storage collections and LINQ-like pipelines built around Span<T>, ref returns, cursor drivers, and strongly typed providers. The goal is to keep data access predictable, allocation-free, and suitable for performance-critical code paths where copying, boxing, or heap allocation is not acceptable.

Features

• Fixed-storage collections -- RefArray, RefList, RefQueue, RefStack, and RefSortedList
• Provider-based access -- IRefProvider<T, TCursor>, IRefReadOnlyProvider<T, TCursor>, and IValueProvider<T, TCursor>
• Source abstraction -- RefSource, RefReadOnlySource, and ValueSource combine provider + projection; RefBoundedSource adds cursor bounds
• Reference-based mutation -- indexers and enumerators can return ref T for in-place updates
• Composable queries -- allocation-free Select, Where, Count, Any, All, FirstRef, and related operators
• Strongly typed mapper support -- TypeToken<T> enables struct mapper chains when C# cannot infer projected types from constraints
• Driver-based traversal -- cursor drivers define iteration order independently from storage layout
• Source algorithms -- SwapAt, Copy, CompareAt, driver-based copy/fill/swap/compare, BinarySearch, and Sort
• Span splitting -- zero-allocation SpanSplitter<T> and ReadOnlySpanSplitter<T>
• Structured byte spans -- type-safe access to packed byte data through span-backed views
• Custom delegates -- RefAction<T>, RefPredicate<T>, RefSelect<T, TResult>, ValueSelect<T, TResult>, and related adapters

Requirements

• .NET 10.0 or later
• C# with LangVersion set to preview
• Required for allows ref struct generic constraints

Installation

Add the Fluentsoft NuGet source and install the package:

dotnet nuget add source https://git.dries.info/fluentsoft/-/packages/nuget/index.json \
  --name fluentsoft

dotnet add package Fluentsoft.Ref

Or add the source in your nuget.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="fluentsoft" value="https://git.dries.info/fluentsoft/-/packages/nuget/index.json" />
  </packageSources>
</configuration>

Then add the package reference to your .csproj:

<PackageReference Include="Fluentsoft.Ref" Version="5.0.0" />

Usage

All types live in the Fluentsoft.System.Ref namespace:

using Fluentsoft.System.Ref;

Core model

The library is built around low-level, composable concepts:

Provider   -> knows how to access data
Projection -> maps public cursor to provider cursor
Source     -> provider + projection
Bounds     -> valid cursor range
Driver     -> traversal order

There are three source families:

RefSource         -> mutable references
RefReadOnlySource -> read-only references
ValueSource       -> copied values

A RefSource combines a mutable ref provider and projection:

var data = new[] { 10, 20, 30 };

var source = new RefSource<
    int,
    int,
    ArrayRefProvider<int>,
    int,
    IdentityProjection<int>>(
        new ArrayRefProvider<int>(data),
        new IdentityProjection<int>());

A RefBoundedSource adds bounds:

var bounded = new RefBoundedSource<
    int,
    int,
    ArrayRefProvider<int>,
    int,
    IdentityProjection<int>,
    LinearCursorBounds>(
        new ArrayRefProvider<int>(data),
        new IdentityProjection<int>(),
        new LinearCursorBounds(0, data.Length));

Usually, use extension methods:

var source = data.AsSource();

Providers

Providers expose data access by cursor.

public interface IRefProvider<T, TCursor>
    where T : struct
    where TCursor : struct, allows ref struct
{
    ref T GetReference(scoped in TCursor cursor);
}

Common providers include:

ArrayRefProvider<T>
SpanRefProvider<T>
RefReadOnlySpanProvider<T>
Array2DRefProvider<T>
Array3DRefProvider<T>

Mutable providers expose ref T.

Read-only providers expose ref readonly T.

Value providers return values by copy and are the foundation of ValueSource and ValueEnumerable.

ValueSource

ValueSource is the value-oriented counterpart of RefSource.

It combines:

provider + projection

but exposes copied values instead of references.

Unlike RefSource, a ValueSource works with any IValueProvider<T, TCursor> and does not require mutable or read-only reference access.

public readonly struct IntValueProvider : IValueProvider<int, int>
{
    public int GetValue(scoped in int cursor)
    {
        return cursor * 10;
    }
}

var source = new ValueSource<
    int,
    int,
    IntValueProvider,
    int,
    IdentityProjection<int>>(
        new IntValueProvider(),
        new IdentityProjection<int>());

ValueSource supports the same projection composition model as RefSource:

var projected = source.ComposeProjection(
    new IdentityProjection<int>());

It also supports direct allocation-free enumeration:

var values = source
    .AsEnumerable(new LinearIndexDriver(3))
    .ToArray();

// [0, 10, 20]

ValueEnumerable

ValueEnumerable is the value-oriented query pipeline.

Unlike RefEnumerable and RefReadOnlyEnumerable, ValueEnumerable operates on copied values instead of references.

A ValueEnumerable can be created from:

IValueProvider<T, TCursor>
ValueSource
RefSource
RefReadOnlySource
SelectValue(...)

This makes it possible to build fully allocation-free LINQ-like pipelines even for sources that do not expose references.

var data = new[] { 1f, 2f, 3f };

var squares = data.AsValueEnumerable()
    .SelectFunc(static (scoped in float value) => value * value)
    .WhereFunc(static (scoped in float value) => value >= 4f);

var result = squares.ToArray(); // [4, 9]

Value enumeration does not allow in-place mutation of the source.

Error handling and ref structs in tests

Because many library types are ref struct, they cannot be captured by delegates or lambdas. In tests, avoid patterns like:

Assert.Throws<InvalidOperationException>(() => array.FirstRef());

Use direct try/catch instead:

try
{
    array.FirstRef();
    Assert.Fail("Expected InvalidOperationException.");
}
catch (InvalidOperationException)
{
}

Building from source

dotnet build
dotnet test

To produce a NuGet package:

dotnet build -c Package

The .nupkg will be written to the Packages/ directory relative to the repository root.

License

This software is licensed under the Fluentsoft Proprietary License (FPL) v1.0. See LICENSE for the full terms. Use requires license acceptance.