Version: Next

Constrained Lists

"At least one element" is the most common rule about a collection, but not the only one. A route needs at least two waypoints, a podium exactly three places, a recipient list distinct addresses, a schedule sorted dates. ConstrainedList<T, TConstraint> handles the whole family. The constraint is a type argument, it is checked once when the list is built, and the list never changes afterwards, so the constraint stays true for the lifetime of the value.

using Masterly.NonEmptyList;

// Waypoint is your own record; waypoints is an IEnumerable<Waypoint>
ConstrainedList<Waypoint, AtLeast<Two>> route = ConstrainedList<Waypoint, AtLeast<Two>>.From(waypoints);

Waypoint start = route.Head;
Waypoint next = route.Second();   // compiles only because AtLeast<Two> is in the type

A method that takes ConstrainedList<Waypoint, AtLeast<Two>> can read the second waypoint without a check. The caller has already proven it exists.

Constraints

Constraint	Holds when	Description
`NonEmpty`	the list has at least one element (always true)	`at least 1 element`
`AtLeast<N>`	`Count >= N`	`at least 2 elements`
`AtMost<N>`	`Count <= N`	`at most 10 elements`
`Exactly<N>`	`Count == N`	`exactly 3 elements`
`Distinct`	no two elements are equal, by `EqualityComparer<T>.Default`	`distinct elements`
`Sorted`	elements are in non-decreasing order, by `Comparer<T>.Default`	`elements in ascending order`
`SortedDescending`	elements are in non-increasing order, by `Comparer<T>.Default`	`elements in descending order`
`And<A, B>`	both `A` and `B` hold	`{A} and {B}`
`Or<A, B>`	`A`, `B` or both hold	`{A} or {B}`

Every constraint is checked on top of the non-empty guarantee, and null elements are always rejected. Sorted accepts equal neighbours: [1, 1, 2] is sorted.

The description column is what ConstrainedList<T, TConstraint>.Description returns, and what error messages use. And and Or join their operands' descriptions:

Console.WriteLine(ConstrainedList<int, And<AtLeast<Two>, Distinct>>.Description);
// at least 2 elements and distinct elements

Cardinalities

AtLeast, AtMost and Exactly take a cardinality type, a type that stands for a number:

Types	Values
`One`, `Two`, `Three`, `Four`, `Five`, `Six`, `Seven`, `Eight`, `Nine`, `Ten`	1 to 10
`Sixteen`, `ThirtyTwo`, `SixtyFour`	16, 32, 64
`Hundred`, `Thousand`	100, 1000

Each one implements ICardinality, so Two.Value is 2. Every cardinality from Two up also implements the marker interface IAtLeastTwo, and every one from Three up implements IAtLeastThree. The markers are what make Second() and Third() possible.

Creating a constrained list

Way	Example	On violation
Collection expression	`ConstrainedList<string, AtLeast<Three>> podium = ["gold", "silver", "bronze"];`	`ArgumentException`
From a sequence	`ConstrainedList<T, C>.From(source)` or `ConstrainedList.From<T, C>(source)`	`ArgumentException`
From a span	`ConstrainedList<T, C>.FromSpan(span)` or `ConstrainedList.Create<T, C>(span)`	`ArgumentException`
Extension on a sequence	`source.ToConstrainedList<T, C>()`	`ArgumentException`
Extension on a non-empty list	`list.Constrain<T, C>()`	`ArgumentException`
Without throwing	`ConstrainedList<T, C>.TryFrom(source, out var list)` or `ConstrainedList.TryFrom<T, C>(source, out var list)`	returns `false`
Just checking	`ConstrainedList<T, C>.Satisfies(source)`	returns `false`
As a validation result	`ConstrainedList<T, C>.Validate(source, path)`	an invalid `Validation`

An empty sequence and a constraint violation throw ArgumentException. The message names the constraint: Sequence does not satisfy the constraint: expected at least 2 elements.
A null sequence or a null element throws ArgumentNullException.
TryFrom and Satisfies return false for null, empty, null elements and violations.
An empty collection expression [] is also reported at compile time by NEL001.
The list always copies the input, so changing the source afterwards has no effect.

// ranked is a NonEmptyList<Candidate> and emails an IEnumerable<string> from your application
ConstrainedList<Candidate, AtLeast<Two>> finalists = ranked.Constrain<Candidate, AtLeast<Two>>();

ConstrainedList<DateOnly, Sorted> schedule = [new(2026, 1, 5), new(2026, 2, 2), new(2026, 3, 2)];

bool ok = ConstrainedList<string, Distinct>.TryFrom(emails, out ConstrainedList<string, Distinct>? unique);

Validate instead of throwing. Validate returns a Validation<ConstrainedList<T, C>, ValidationError> with a single error, so it fits straight into Validation and error-accumulating request handling. The optional path is recorded on the error.

// input is an IEnumerable<int>? from a request
Validation<ConstrainedList<int, AtLeast<Two>>, ValidationError> ids =
    ConstrainedList<int, AtLeast<Two>>.Validate(input, path: "ids");

Input	Error code	Message
`null`	`required`	`A value is required`
empty	`nonEmpty`	`At least one element is required`
contains `null`	`noNulls`	`Elements cannot be null`
violates the constraint	`constraint`	`Expected at least 2 elements` (the description)

Second() and Third()

Second() and Third() compile only when the constraint proves the element exists. They are extension methods whose receiver type spells the constraint out, with a generic constraint on the cardinality:

public static T Second<T, TCount>(this ConstrainedList<T, AtLeast<TCount>> list)
    where TCount : ICardinality, IAtLeastTwo
    => list[1];

AtLeast<Two> matches, because Two implements IAtLeastTwo. AtLeast<One> does not, so Second() is a compile error rather than a run-time exception. The same pattern gives you Third() (with IAtLeastThree) and RestAfterSecond().

Receiver	`Second()`	`Third()`	`RestAfterSecond()`
`ConstrainedList<T, AtLeast<N>>`	N is 2 or more	N is 3 or more	N is 2 or more
`ConstrainedList<T, Exactly<N>>`	N is 2 or more	N is 3 or more	no
`ConstrainedList<T, And<AtLeast<N>, TOther>>`	N is 2 or more	N is 3 or more	no
anything else	no	no	no

ConstrainedList<string, AtLeast<Three>> podium = ["gold", "silver", "bronze"];
string silver = podium.Second();
string bronze = podium.Third();

ConstrainedList<string, And<AtLeast<Two>, Distinct>> recipients = ["ada@example.com", "grace@example.com"];
string cc = recipients.Second();

List<string> others = podium.RestAfterSecond();   // ["bronze"]; may be empty

note

In an And, the AtLeast must be the first operand. ConstrainedList<T, And<AtLeast<Two>, Distinct>> has Second(). ConstrainedList<T, And<Distinct, AtLeast<Two>>> holds the same lists but does not, because no extension method matches that shape. Or never proves an element exists. Exactly<N> inside an And is not matched either.

Immutability

A constrained list derives from NonEmptyList<T>, so it has the full read API: Head, Last, indexers, list patterns, the type-preserving LINQ in LINQ and generic math. You can pass it to any method that takes a NonEmptyList<T>, IReadOnlyList<T> or IEnumerable<T>.

It cannot change. Every mutating member throws NotSupportedException, including Add, AddRange, AddFirst, Insert, InsertRange, Remove, RemoveAt, RemoveRange, RemoveAll, Clear, the indexer setter, SetRange, Sort and the in-place Reverse(), and the calls through IList and IList<T>. ICollection<T>.IsReadOnly and IList.IsReadOnly report true.

To change one, use the With methods. Each returns a new constrained list with the constraint checked again; the original is unchanged.

Method	Returns	Throws
`WithAppended(item)`	the list with `item` at the end	`ArgumentException` on violation, `ArgumentNullException` for `null`
`WithPrepended(item)`	the list with `item` at the start	same
`WithItem(index, item)`	the list with one element replaced	same, and `ArgumentOutOfRangeException` for a bad index
`WithoutAt(index)`	the list without one element	`ArgumentException` when the result is empty or violates the constraint, `ArgumentOutOfRangeException` for a bad index

ConstrainedList<int, And<AtLeast<Two>, AtMost<Three>>> pair = [1, 2];

var three = pair.WithAppended(3);    // [1, 2, 3]
var four = three.WithAppended(4);    // ArgumentException: at most 3 elements
var one = pair.WithoutAt(0);         // ArgumentException: at least 2 elements

Leaving the constraint.

Relax() returns a mutable NonEmptyList<T> copy without the constraint.
As<TOther>() checks the same elements against another constraint and throws ArgumentException on violation. TryAs<TOther>(out var other) returns false instead.
LINQ operators return ordinary non-empty results: list.Select(f) is a NonEmptyList<TResult>, without the constraint, because the new elements may not satisfy it.

ConstrainedList<int, Sorted> sorted = [1, 2, 2];

NonEmptyList<int> editable = sorted.Relax();
editable.Add(0);                                  // fine, the copy has no constraint

ConstrainedList<int, AtLeast<Two>> big = sorted.As<AtLeast<Two>>();
bool unique = sorted.TryAs<Distinct>(out _);      // false: 2 appears twice

JSON

System.Text.Json support is built in. A constrained list is written as a JSON array, and reading checks the constraint: an array that is empty, contains null or violates the constraint throws JsonException. A JSON null reads as a null reference. This works for properties of your DTOs too.

using System.Text.Json;

// Waypoint is your own record with Lat and Lng properties
public sealed record RouteDto(ConstrainedList<Waypoint, AtLeast<Two>> Waypoints);

// Throws JsonException: expected at least 2 elements
JsonSerializer.Deserialize<RouteDto>("""{ "Waypoints": [ { "Lat": 0, "Lng": 0 } ] }""");

Writing your own constraint

A constraint is a type that implements IListConstraint, an interface with two static abstract members:

public interface IListConstraint
{
    static abstract bool Holds<T>(ReadOnlySpan<T> items);
    static abstract string Describe();
}

Holds receives the elements, already checked to be non-empty and free of null. Return true if they satisfy your rule.
Describe returns the short text used in Description, exception messages and Validate errors. Write it so it reads after "expected": "at least 2 elements", "unique SKUs".
Holds is generic over every element type, so you cannot add a generic constraint such as where T : INumber<T>. Test the type at run time instead.
The built-in constraints are readonly struct types. A struct with no fields is the natural choice.

NoBlankStrings.cs
public readonly struct NoBlankStrings : IListConstraint
{
    public static bool Holds<T>(ReadOnlySpan<T> items)
    {
        foreach (T item in items)
        {
            if (item is string text && string.IsNullOrWhiteSpace(text))
                return false;
        }

        return true;
    }

    public static string Describe() => "no blank strings";
}

// Compose it like any built-in constraint
ConstrainedList<string, And<AtLeast<Two>, NoBlankStrings>> names = ["Ada", "Grace"];

You can add a cardinality the same way. Implement ICardinality with a static Value, and add the markers when they are true, so Second() and Third() work for it:

Twelve.cs
public readonly struct Twelve : ICardinality, IAtLeastTwo, IAtLeastThree
{
    public static int Value => 12;
}

// Month is your own type; months is an IEnumerable<Month>
ConstrainedList<Month, Exactly<Twelve>> year = ConstrainedList<Month, Exactly<Twelve>>.From(months);

warning

The markers are a promise. If you put IAtLeastTwo on a cardinality whose Value is 1, Second() compiles and then fails at run time with an index out of range.

Constraints​

Cardinalities​

Creating a constrained list​

Second() and Third()​

Immutability​

JSON​

Writing your own constraint​