CodoMetis.ValueRanges

https://github.com/caffeinatedcoder/codometis.valueranges
Admin
CodoMetis.ValueRanges provides fully functional, in-memory range types for .NET, offering a complete...
Tokens:381,138
Snippets:2,140
Trust Score:7.5
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Create and apply EF Core migrations

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/getting-started.md

Generate and apply the initial migration to create the database schema.

```sh
dotnet ef migrations add InitialCreate
dotnet ef database update
```

--------------------------------

### Add CodoMetis.ValueRanges.EFCore.PostgreSQL package

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/getting-started.md

Install the EF Core PostgreSQL package and the design package to enable migrations.

```sh
dotnet add package CodoMetis.ValueRanges.EFCore.PostgreSQL
dotnet add package Microsoft.EntityFrameworkCore.Design
```

--------------------------------

### Create a new console project and add the CodoMetis.ValueRanges package

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/getting-started.md

Run these commands in a terminal to create a new .NET console project and add the CodoMetis.ValueRanges NuGet package. This is the first step of Part 1, which runs entirely in memory without a database.

```sh
dotnet new console -o RangeDemo && cd RangeDemo
dotnet add package CodoMetis.ValueRanges
```

--------------------------------

### Configure DbContext with UseValueRanges

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/getting-started.md

Enable the mapping by calling UseValueRanges() in the Npgsql options.

```csharp
using Microsoft.EntityFrameworkCore;

public class BookingContext : DbContext
{
    public DbSet<Booking> Bookings => Set<Booking>();

    protected override void OnConfiguring(DbContextOptionsBuilder options)
        => options.UseNpgsql(
            "Host=localhost;Database=bookings;Username=postgres;Password=postgres",
            npgsql => npgsql.UseValueRanges());
}
```

--------------------------------

### Find gaps between ranges with Gap and Gaps

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/getting-started.md

Use the Gap method to find the range between two stays, and the Gaps method to get every free stretch inside a set or inside a window. The comments show the expected results for each call.

```csharp
june.Gap(july);                             // [2025-06-09,2025-06-30]
blocked.Gaps();                             // {[2025-06-09,2025-06-30]}

var summer = DateRange.CreateFinite(new DateOnly(2025, 6, 1), new DateOnly(2025, 8, 31));
blocked.Gaps(summer);                       // {[2025-06-09,2025-06-30],[2025-07-06,2025-08-31]}
```

--------------------------------

### postgres-surface.json entry example

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/oracles.md

Example entry from postgres-surface.json describing a PostgreSQL operator or function gap. Fields: signature, kind, since, member, translation, waiver, issue. Used to track which PostgreSQL range/multirange/array operators are mirrored, translated, or omitted.

```json
{
  "signature": "anyrange &< anymultirange",
  "kind": "operator",
  "since": 14,
  "member": null,
  "translation": null,
  "waiver": null,
  "issue": 92
}
```

--------------------------------

### Run the booking service with Docker and dotnet run

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/walkthrough.md

Starts a PostgreSQL 16 container, waits for it to be ready, then runs the Bookings sample app with the connection string. The app applies its migration, adds three rooms, and listens on http://localhost:5000. Bookings persist between runs; remove the container with docker rm -f bookings-db to start from an empty database.

```sh
docker run -d --name bookings-db -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16-alpine
until docker exec bookings-db pg_isready -h 127.0.0.1 -U postgres; do sleep 1; done
cd samples/Bookings
ConnectionStrings__Bookings="Host=localhost;Database=bookings;Username=postgres;Password=postgres" dotnet run
```

--------------------------------

### Query range and set properties with LINQ

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/getting-started.md

Use Contains, Overlaps, and LowerBound methods that translate to PostgreSQL operators.

```csharp
var day = new DateOnly(2025, 6, 3);
var request = DateRange.CreateFinite(new DateOnly(2025, 6, 1), new DateOnly(2025, 6, 8));

// WHERE b."Period" @> @day
var onThatDay = context.Bookings.Where(b => b.Period.Contains(day)).ToList();

// WHERE b."Period" && @request
var colliding = context.Bookings.Where(b => b.Period.Overlaps(request)).ToList();

// WHERE b."Tags" @> ARRAY[@tag]::text[]        — a plain GIN index serves this
var tagged = context.Bookings.Where(b => b.Tags.Contains("vip")).ToList();

// ORDER BY lower(b."Period"); a booking with no start, or an empty period, sorts last
var chronological = context.Bookings.OrderBy(b => b.Period.LowerBound()).ToList();
```

--------------------------------

### CreateFinite

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Creates a finite InstantRange with specified start and end. Inclusivity of both bounds can be controlled.

```APIDOC
## CreateFinite

### Description
Creates a finite InstantRange with specified start and end. Inclusivity of both bounds can be controlled.

### Method
static factory method

### Signature
public static InstantRange CreateFinite(Instant start, Instant end, bool startInclusive = true, bool endInclusive = false)

### Parameters
- **start** (Instant) - Required - The start of the range.
- **end** (Instant) - Required - The end of the range.
- **startInclusive** (bool) - Optional - Whether the start is inclusive. Default is true.
- **endInclusive** (bool) - Optional - Whether the end is inclusive. Default is false.

### Returns
InstantRange - A new InstantRange instance.
```

--------------------------------

### Define entity with range and set properties

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/getting-started.md

Use DateRange, RangeSet, and StringSet as ordinary properties without converters or column type configuration.

```csharp
using CodoMetis.ValueRanges;

public class Booking
{
    public int Id { get; set; }
    public int RoomId { get; set; }

    public DateRange Period { get; set; } = DateRange.Empty;

    public RangeSet<DateRange, DateOnly> BlockedDays { get; set; }
        = RangeSet<DateRange, DateOnly>.Empty;

    public StringSet Tags { get; set; } = StringSet.Empty;
}
```

--------------------------------

### CreateUnboundedEnd

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Creates an InstantRange with an unbounded end and a specified start. The start inclusivity can be controlled via the startInclusive parameter.

```APIDOC
## CreateUnboundedEnd

### Description
Creates an InstantRange with an unbounded end and a specified start. The start inclusivity can be controlled via the startInclusive parameter.

### Method
static factory method

### Signature
public static InstantRange CreateUnboundedEnd(Instant start, bool startInclusive = true)

### Parameters
- **start** (Instant) - Required - The start of the range.
- **startInclusive** (bool) - Optional - Whether the start is inclusive. Default is true.

### Returns
InstantRange - A new InstantRange instance.
```

--------------------------------

### Install CodoMetis.ValueRanges.NodaTime via dotnet CLI

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/src/CodoMetis.ValueRanges.NodaTime/README.md

Adds the CodoMetis.ValueRanges.NodaTime package. Requires .NET 11 or later; the 10.x line stays on .NET 10.

```sh
dotnet add package CodoMetis.ValueRanges.NodaTime
```

--------------------------------

### CreateFinite

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Creates a finite range with specified start and end. Inclusiveness of both bounds can be controlled.

```APIDOC
## CreateFinite

### Description
Creates a finite range with specified start and end. Inclusiveness of both bounds can be controlled.

### Method
Static factory method

### Signature
public static LocalDateTimeRange CreateFinite(LocalDateTime start, LocalDateTime end, bool startInclusive = true, bool endInclusive = false)

### Parameters
- **start** (LocalDateTime) - Required - The start of the range.
- **end** (LocalDateTime) - Required - The end of the range.
- **startInclusive** (bool) - Optional - Whether the start is inclusive. Default is true.
- **endInclusive** (bool) - Optional - Whether the end is inclusive. Default is false.

### Returns
- **LocalDateTimeRange** - A new finite range.
```

--------------------------------

### CreateUnboundedStart

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Creates an InstantRange with an unbounded start and a specified end. The end inclusivity can be controlled via the endInclusive parameter.

```APIDOC
## CreateUnboundedStart

### Description
Creates an InstantRange with an unbounded start and a specified end. The end inclusivity can be controlled via the endInclusive parameter.

### Method
static factory method

### Signature
public static InstantRange CreateUnboundedStart(Instant end, bool endInclusive = false)

### Parameters
- **end** (Instant) - Required - The end of the range.
- **endInclusive** (bool) - Optional - Whether the end is inclusive. Default is false.

### Returns
InstantRange - A new InstantRange instance.
```

--------------------------------

### Seed patch example for IsStrictlyLeftOf

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/oracles.md

A seed is a revert of a fix, kept as a patch file, to prove an oracle can fail. This example shows the seed for the IsStrictlyLeftOf defect, which fails for pairs with an UnboundedStart receiver strictly left of its operand. The patch modifies src/CodoMetis.ValueRanges/RangeExtensions.cs and names the oracles it fails.

```diff
Seed: IsStrictlyLeftOf decides by the receiver's shape: an UnboundedStart receiver answers false
Oracles: SmallModelOracleTests, DomainParityOracleTests, ShapeMatrixParityTests
Fails: every pair with an UnboundedStart receiver strictly left of its operand
History: shipped in 6.x, fixed in 7.0.0

diff --git a/src/CodoMetis.ValueRanges/RangeExtensions.cs b/src/CodoMetis.ValueRanges/RangeExtensions.cs
…
```

--------------------------------

### Empty

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Gets an empty range.

```APIDOC
## Empty

### Description
Gets an empty range.

### Property
public static LocalDateTimeRange Empty { get; }

### Returns
- **LocalDateTimeRange** - An empty range.
```

--------------------------------

### StringSet.Empty

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/value-sets.md

Gets the empty StringSet instance.

```APIDOC
## StringSet.Empty

### Description
Gets the empty StringSet instance.

### Property
`public static StringSet Empty { get; }`

### Returns
- **StringSet** - The empty StringSet.
```

--------------------------------

### Install CodoMetis.ValueRanges with dotnet add package

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/README.md

Adds the CodoMetis.ValueRanges NuGet package to the project. Version 11 requires .NET 11; version 10 requires .NET 10. Until 11.0.0 is released, this installs 10.x; use --prerelease for 11 previews.

```sh
dotnet add package CodoMetis.ValueRanges
```

--------------------------------

### CreateFinite

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Creates a finite YearMonthRange between the specified start and end months, with configurable inclusivity.

```APIDOC
## CreateFinite

### Description
Creates a finite YearMonthRange between the specified start and end months, with configurable inclusivity.

### Method
CreateFinite

### Parameters
- **start** (YearMonth) - Required - The start month of the range.
- **end** (YearMonth) - Required - The end month of the range.
- **startInclusive** (bool) - Optional - Whether the start month is included. Default is true.
- **endInclusive** (bool) - Optional - Whether the end month is included. Default is true.

### Returns
YearMonthRange - A finite range.
```

--------------------------------

### Empty

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Gets an InstantRange that represents an empty range (no values).

```APIDOC
## Empty

### Description
Gets an InstantRange that represents an empty range (no values).

### Property
public static InstantRange Empty { get; }

### Returns
InstantRange - An empty range.
```

--------------------------------

### Infinite

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Gets a static instance representing an infinite range (no bounds).

```APIDOC
## Infinite

### Description
Gets a static instance representing an infinite range (no bounds).

### Method
Infinite

### Signature
public static LocalDateRange Infinite { get; }

### Returns
LocalDateRange - An infinite range.
```

--------------------------------

### Infinite

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Gets an infinite YearMonthRange that covers all possible months.

```APIDOC
## Infinite

### Description
Gets an infinite YearMonthRange that covers all possible months.

### Method
Infinite

### Returns
YearMonthRange - An infinite range.
```

--------------------------------

### CreateUnboundedStart

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Creates a range with an unbounded start and a specified end. The end inclusiveness can be controlled via the endInclusive parameter.

```APIDOC
## CreateUnboundedStart

### Description
Creates a range with an unbounded start and a specified end. The end inclusiveness can be controlled via the endInclusive parameter.

### Method
Static factory method

### Signature
public static LocalDateTimeRange CreateUnboundedStart(LocalDateTime end, bool endInclusive = false)

### Parameters
- **end** (LocalDateTime) - Required - The end of the range.
- **endInclusive** (bool) - Optional - Whether the end is inclusive. Default is false.

### Returns
- **LocalDateTimeRange** - A new range with unbounded start.
```

--------------------------------

### Empty

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Gets a static instance representing an empty range (no values).

```APIDOC
## Empty

### Description
Gets a static instance representing an empty range (no values).

### Method
Empty

### Signature
public static LocalDateRange Empty { get; }

### Returns
LocalDateRange - An empty range.
```

--------------------------------

### Build and test the solution

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/CONTRIBUTING.md

Run the build and test commands from the repository root. Requires a .NET 11 SDK as pinned by global.json; a newer major is refused.

```bash
dotnet build CodoMetis.ValueRanges.slnx
dotnet test
```

--------------------------------

### Union two non-overlapping ranges into a RangeSet

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/getting-started.md

Combine two non-overlapping date ranges with the Union method to get a RangeSet. The RangeSet supports Count, Contains, and Complement operations, and the comments show the expected results.

```csharp
var blocked = june.Union(july);        // {[2025-06-01,2025-06-08],[2025-07-01,2025-07-05]}

blocked.Count;                              // 2
blocked.Contains(new DateOnly(2025, 6, 20));    // False — falls in the gap
blocked.Complement();                       // everything else, as a RangeSet
```

--------------------------------

### Build the 10.x documentation line locally

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/CONTRIBUTING.md

Run this from a main checkout to build the release/10.x line locally before merging a PR into that branch. The first argument is the release/10.x worktree path, the second is the output folder, and the third is the version label.

```bash
site/build.sh <release/10.x worktree> <output folder> 10.x
```

--------------------------------

### Build and Test Commands

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/AGENTS.md

Commands for building, testing, and packing the project. Tests are method-level parallel; use filters to target specific test classes or methods.

```bash
dotnet build                          # Build everything
```

```bash
dotnet test                           # Run all tests
```

```bash
dotnet test --filter "ClassName=RangeContainsTests"   # Single test class
```

```bash
dotnet test --filter "FullyQualifiedName~Contains_FiniteRange"  # Single method
```

```bash
dotnet pack -c Release                # Pack NuGet packages (builds first)
```

--------------------------------

### RangeSet<TRange, T>.LowerBoundComparer

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/rangeset.md

Gets the singleton comparer that orders ranges by lower bound, with unbounded start ranges first and inclusive bounds before exclusive at the same value.

```APIDOC
## RangeSet<TRange, T>.LowerBoundComparer

### Description
Gets the singleton comparer that orders ranges by lower bound, with unbounded start ranges first and inclusive bounds before exclusive at the same value.

### Property
`static IComparer<TRange> LowerBoundComparer`

### Returns
- **IComparer<TRange>** - The singleton `RangeLowerBoundComparer<TRange, T>.Instance`.
```

--------------------------------

### Split(Func<LocalDate, LocalDateRange>)

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Splits the range using a function that determines the sub-range for each start date.

```APIDOC
## Split(Func<LocalDate, LocalDateRange>)

### Description
Splits the range using a function that determines the sub-range for each start date.

### Method
Split

### Signature
public IEnumerable<LocalDateRange> Split(Func<LocalDate, LocalDateRange> period)

### Parameters
- **period** (Func<LocalDate, LocalDateRange>) - Required - A function that takes a start date and returns the corresponding sub-range.

### Returns
IEnumerable<LocalDateRange> - An enumeration of sub-ranges.
```

--------------------------------

### Seed an oracle: create patch and run seeds

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/oracles.md

Creates a patch file with a seed description and the diff of src/, then reverts src/ and runs the seeds command. The oracle must fail for the defect, not with a compile error or unrelated exception.

```bash
{ printf 'Seed: <what is broken>\nOracles: <Class, Class>\nFails: <what fails>\n\n'; git diff -- src/; } \
  > test/oracles/seeds/<defect>.patch
git checkout -- src/
dotnet run tools/oracles.cs seeds <defect>
```

--------------------------------

### Create and query an immutable StringSet

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/getting-started.md

Create a StringSet from a list of strings and use collection expressions. The set is deduplicated, sorted, and immutable. The IsSubsetOf and Overlaps methods show the expected results.

```csharp
var tags = StringSet.From("beta", "alpha", "beta");   // {alpha,beta}
StringSet required = ["alpha", "gamma"];              // collection expressions work

tags.IsSubsetOf(required);   // False
tags.Overlaps(required);     // True — they share "alpha"
```

--------------------------------

### Check overlap and containment with DateRange

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/getting-started.md

Create two finite date ranges and use the Overlaps and Contains methods to check for collisions and membership. The output shows False for the overlap, True for containment, and the string representation of the range.

```csharp
using CodoMetis.ValueRanges;

var june = DateRange.CreateFinite(new DateOnly(2025, 6, 1), new DateOnly(2025, 6, 8));
var july = DateRange.CreateFinite(new DateOnly(2025, 7, 1), new DateOnly(2025, 7, 5));

Console.WriteLine(june.Overlaps(july));                  // False
Console.WriteLine(june.Contains(new DateOnly(2025, 6, 3)));  // True
Console.WriteLine(june);                                 // [2025-06-01,2025-06-08]
```

--------------------------------

### DateRange basic usage and calendar windows

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/date-range.md

Shows how to create finite ranges, check containment, get length, format as PostgreSQL literal, and use Month, Quarter, IsoWeek, Year factories. Also demonstrates enumeration and splitting into weeks or months.

```csharp
using CodoMetis.ValueRanges;

var stay = DateRange.CreateFinite(new DateOnly(2025, 6, 1), new DateOnly(2025, 6, 8));

stay.Contains(new DateOnly(2025, 6, 3));     // true
stay.Length;                                 // 8 — days, counted inclusively
stay.ToString();                             // "[2025-06-01,2025-06-08]" — the PostgreSQL literal

// Calendar windows:
var feb = DateRange.Month(2026, 2);          // [2026-02-01,2026-02-28]
var q4  = DateRange.Quarter(2026, 4);        // [2026-10-01,2026-12-31]
var wk  = DateRange.IsoWeek(2026, 1);        // [2025-12-29,2026-01-04]

// Enumerate and split:
foreach (var day in DateRange.Year(2024).Values()) { /* 366 iterations */ }
var weeks = DateRange.Month(2026, 6).Split(7);   // 4 weeks + [2026-06-29,2026-06-30]
var months = DateRange.Year(2026).Split(DateRange.Month);  // one piece per calendar month
```

--------------------------------

### Build command to list missing doc comments (CS1591)

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/architecture.md

Run first to surface every public member whose doc comment was not brought over; the shipped .xml is what IntelliSense shows, so comments are not optional.

```bash
dotnet build
```

--------------------------------

### RangeSet.Overlaps behavior change on continuous types

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/migration.md

Before 10.0.0, Overlaps returned false when the passed range stopped exactly where a later element started with one side exclusive. Now it returns true, matching PostgreSQL's && operator. Discrete types are unaffected.

```csharp
var set = RangeSet<DecimalRange, decimal>.From([DecimalRange.CreateFinite(1, 4), DecimalRange.CreateFinite(5, 8)]);
// {[1,4),[5,8)}

set.Overlaps(DecimalRange.CreateFinite(3, 5));              // v9: false   v10: true — shares [3,4)
set.Overlaps(DecimalRange.CreateUnboundedStart(5, false));  // v9: false   v10: true — (,5) covers [1,4)
set.Intersect(DecimalRange.CreateFinite(3, 5));             // {[3,4)} in both, which is why true is right
```

--------------------------------

### UseValueRanges usage example

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/efcore-postgresql.md

Configures Npgsql options with the ValueRanges plugin using a connection string.

```csharp
options.UseNpgsql(connectionString, npgsql => npgsql.UseValueRanges());
```

--------------------------------

### Create an open-ended range and pattern match on its shape

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/getting-started.md

Create an UnboundedEnd range and use a switch expression to handle all five possible shapes. The discard arm must throw an UnreachableException to avoid the CS8509 warning, which becomes a build error when warnings are treated as errors.

```csharp
DateRange openEnded = DateRange.CreateUnboundedEnd(new DateOnly(2025, 6, 1));   // [2025-06-01,)

// The five shapes are the only ones that can exist, so these arms are complete in fact.
// C# still cannot prove that, so a switch expression needs a discard — make it throw.
var description = openEnded switch
{
    DateRange.Finite f          => $"{f.Start} to {f.End}",
    DateRange.UnboundedEnd u    => $"from {u.Start}, open-ended",
    DateRange.UnboundedStart u  => $"until {u.End}",
    DateRange.EmptyRange        => "no dates",
    DateRange.Infinity          => "always",
    _                           => throw new UnreachableException(),   // System.Diagnostics
};
```

--------------------------------

### StringSet and SkuSet usage with collection expressions

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/value-sets.md

Shows basic operations on StringSet and SkuSet, including deduplication, sorting, indexing, containment, subset checks, union, and ToString. Also demonstrates collection expressions and a validated wrapper arity for SkuSet.

```csharp
using CodoMetis.ValueRanges;

var tags = StringSet.From("beta", "alpha", "beta");   // {alpha,beta} — deduplicated, sorted
StringSet more = ["gamma", "alpha"];                  // collection expressions work

tags.Count;                 // 2
tags[0];                    // "alpha"
tags.Contains("alpha");     // true
tags.IsSubsetOf(more);      // false
tags.Union(more);           // {alpha,beta,gamma}
tags.ToString();            // "{alpha,beta}"

// Validated wrapper arity (Vogen/Metalama/StronglyTypedId-style keys):
public readonly record struct Sku(int Value);   // or a generated wrapper

var skus = SkuSet.From([new Sku(1), new Sku(2), new Sku(1)]);  // {1,2}
```

--------------------------------

### CreateUnboundedEnd

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/irangefactory.md

Creates a range with no upper bound, starting at the given start value. The start can be inclusive or exclusive.

```APIDOC
## CreateUnboundedEnd

### Description
Creates a range with no upper bound, starting at the given start value.

### Signature
`static TRange CreateUnboundedEnd(T start, bool startInclusive)`

### Parameters
- **start** (T) - Required - The start bound.
- **startInclusive** (bool) - Required - Whether the start bound is inclusive.

### Returns
- **TRange** - The created range.
```

--------------------------------

### Query PostgreSQL with docker exec

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/walkthrough.md

Runs psql inside the bookings-db container to select booking and room data.

```sh
docker exec bookings-db psql -U postgres -d bookings -At \
  -c 'SELECT "Id", "Period", "Arrival" FROM "Bookings" ORDER BY "Id"' \
  -c 'SELECT "Id", "Features", "Bookable" FROM "Rooms" ORDER BY "Id"'
```

--------------------------------

### CreateUnboundedEnd

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/types.md

Creates a range with no upper bound, starting from the specified start value to positive infinity. The start inclusivity can be controlled via the optional parameter.

```APIDOC
## CreateUnboundedEnd

### Description
Creates a range with no upper bound, starting from the specified start value to positive infinity. The start inclusivity can be controlled via the optional parameter.

### Method
Static factory method

### Parameters
- **start** (T) - Required - The start value of the range.
- **startInclusive** (bool) - Optional - Whether the start value is inclusive. Default is true.

### Returns
A range instance of the corresponding type.
```

--------------------------------

### Install CodoMetis.ValueRanges.EFCore.PostgreSQL package

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/efcore.md

Adds the EF Core PostgreSQL package to the project. Required before using the UseValueRanges() extension.

```bash
dotnet add package CodoMetis.ValueRanges.EFCore.PostgreSQL
```

--------------------------------

### IUnboundedEndRange<T> interface definition

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/range-interfaces.md

Defines a range unbounded on the right: [Start, +∞) or (Start, +∞). Includes Start and StartInclusive properties, and default implementations for IntersectWith and MergeWith using IntersectEngine and MergeEngine.

```csharp
[JsonConverter(typeof(InterfaceDeclaredJsonConverter))]
public interface IUnboundedEndRange<T> : IRange<T> where T : struct, IComparable<T>, IEquatable<T>
{
    T Start { get; }
    bool StartInclusive { get; }

    TRange IRange<T>.IntersectWith<TRange>(IRange<T> other) => IntersectEngine.Execute<TRange, T>(this, other);
    TRange IRange<T>.MergeWith<TRange>(IRange<T> other) => MergeEngine.Execute<TRange, T>(this, other);
}
```

--------------------------------

### Run all tests with dotnet test

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/testing.md

Runs the entire test suite with method-level parallel execution. No shared state between tests.

```bash
dotnet test                          # All tests (method-level parallel)
```

--------------------------------

### CreateUnboundedEnd

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Creates a YearMonthRange with no upper bound, starting at the specified month. The start can be inclusive or exclusive.

```APIDOC
## CreateUnboundedEnd

### Description
Creates a YearMonthRange with no upper bound, starting at the specified month. The start can be inclusive or exclusive.

### Method
CreateUnboundedEnd

### Parameters
- **start** (YearMonth) - Required - The start month of the range.
- **startInclusive** (bool) - Optional - Whether the start month is included. Default is true.

### Returns
YearMonthRange - An unbounded-end range.
```

--------------------------------

### CompareTo

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Compares this InstantRange to another InstantRange.

```APIDOC
## CompareTo

### Description
Compares this InstantRange to another InstantRange.

### Method
instance method

### Signature
public int CompareTo(InstantRange? other)

### Parameters
- **other** (InstantRange?) - Required - The other range to compare.

### Returns
int - A value indicating the relative order of the objects being compared.
```

--------------------------------

### CreateUnboundedEnd

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Creates a range with an unbounded end and a specified start. The start inclusiveness can be controlled via the startInclusive parameter.

```APIDOC
## CreateUnboundedEnd

### Description
Creates a range with an unbounded end and a specified start. The start inclusiveness can be controlled via the startInclusive parameter.

### Method
Static factory method

### Signature
public static LocalDateTimeRange CreateUnboundedEnd(LocalDateTime start, bool startInclusive = true)

### Parameters
- **start** (LocalDateTime) - Required - The start of the range.
- **startInclusive** (bool) - Optional - Whether the start is inclusive. Default is true.

### Returns
- **LocalDateTimeRange** - A new range with unbounded end.
```

--------------------------------

### Run Stryker.NET Mutation Testing

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/testing.md

Manual, occasional mutation testing command. Run from the test project directory; writes reports outside the repository. The first run for 10.0.0 (#91) took 7½ minutes on a 16-core machine. Do not add to CI or scripts that run on every change.

```bash
cd test/CodoMetis.ValueRanges.Tests
dotnet stryker --output /tmp/stryker-$(date +%F)
```

--------------------------------

### CreateUnboundedEnd

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Creates a range with no upper bound, starting at the specified date. The start inclusivity can be controlled via the startInclusive parameter.

```APIDOC
## CreateUnboundedEnd

### Description
Creates a range with no upper bound, starting at the specified date. The start inclusivity can be controlled via the startInclusive parameter.

### Method
CreateUnboundedEnd

### Signature
public static LocalDateRange CreateUnboundedEnd(LocalDate start, bool startInclusive = true)

### Parameters
- **start** (LocalDate) - Required - The start date of the range.
- **startInclusive** (bool) - Optional - Whether the start date is inclusive. Default is true.

### Returns
LocalDateRange - An unbounded-end range.
```

--------------------------------

### DecimalRange.CreateFinite

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/irangefactory.md

Creates a finite range from start and end values. Returns an empty range if the start is greater than or equal to the end.

```APIDOC
## DecimalRange.CreateFinite

### Description
Creates a finite range from start and end values. Returns an empty range if the start is greater than or equal to the end.

### Method
CreateFinite

### Parameters
- **start** (decimal) - Required - The start bound.
- **end** (decimal) - Required - The end bound.

### Returns
- **DecimalRange** - The created range, or an empty range if start >= end.

### Example
```csharp
DecimalRange collapsed = DecimalRange.CreateFinite(5m, 1m); // Empty
DecimalRange point     = DecimalRange.CreateFinite(5m, 5m); // Empty ([5,5) is empty)
```
```

--------------------------------

### Range and set operations with NodaTime

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/src/CodoMetis.ValueRanges.NodaTime/README.md

Shows core range and set operations: creating finite ranges, checking containment, building a RangeSet from adjacent ranges (which merge), and using value sets (LocalDateSet, LocalTimeSet) that store exact moments. Demonstrates half-open intervals, discrete-step merging, and sorted/deduplicated set formatting.

```csharp
using CodoMetis.ValueRanges;
using NodaTime;

var sprint = LocalDateRange.CreateFinite(new LocalDate(2025, 1, 6), new LocalDate(2025, 1, 17));
sprint.Contains(new LocalDate(2025, 1, 10));   // true

var deploy = InstantRange.CreateFinite(
    Instant.FromUtc(2025, 6, 1, 22, 0),
    Instant.FromUtc(2025, 6, 2, 2, 0));        // [start, end) — half-open, like tstzrange

var blocked = RangeSet<LocalDateRange, LocalDate>.From([
    LocalDateRange.CreateFinite(new LocalDate(2025, 1, 1), new LocalDate(2025, 1, 31)),
    LocalDateRange.CreateFinite(new LocalDate(2025, 2, 1), new LocalDate(2025, 2, 28))
]);   // { [2025-01-01,2025-02-28] } — adjacent months merge (discrete step)

var billing = YearMonthRange.CreateFinite(new YearMonth(2025, 1), new YearMonth(2025, 12));
billing.Contains(new YearMonth(2025, 6));      // true — month-granularity periods (v5)

// Value sets (v6) — "exactly these", not "everything between"
LocalDateSet holidays = [new LocalDate(2025, 12, 26), new LocalDate(2025, 1, 1)];
holidays.ToString();                           // {2025-01-01,2025-12-26} — sorted, deduplicated
holidays.Contains(new LocalDate(2025, 1, 1));  // true

var closed = LocalDateSet.From(new LocalDate(2025, 1, 1));
closed.IsProperSubsetOf(holidays);             // true

var slots = LocalTimeSet.From(new LocalTime(17, 30), new LocalTime(9, 0));
slots.ToString();                              // {09:00:00,17:30:00}
```

--------------------------------

### 201 Created response for booking

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/walkthrough.md

Shows the response body with the booking ID, room ID, guest, stay, and arrival. The arrival preserves the sent offset and all seven fraction digits, built from the in-memory object.

```json
{"id":1,"roomId":1,"guest":"Ada","stay":"[2026-07-01,2026-07-04]","arrival":"[2026-07-01T15:00:00.1234567+02:00,2026-07-01T18:00:00.0000000+02:00)"}
```

--------------------------------

### CreateUnboundedEnd

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/date-range.md

Creates a DateRange with no upper bound, starting at the specified date. The start bound is inclusive by default, but can be set to exclusive, which adjusts the canonical bound.

```APIDOC
## CreateUnboundedEnd

### Description
Creates a DateRange with no upper bound, starting at the specified date. The start bound is inclusive by default, but can be set to exclusive, which adjusts the canonical bound.

### Method
Static factory method

### Endpoint
`public static DateRange CreateUnboundedEnd(DateOnly start, bool startInclusive = true)`

### Parameters
- `start` (DateOnly) - Required - Lower bound.
- `startInclusive` (bool) - Optional - Whether `start` is included. Default is `true`.

### Remarks
Because the domain is discrete, `CreateUnboundedEnd(start, startInclusive: false)` uses `start + 1` or `Empty`.
```

--------------------------------

### StringSet.Count

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/value-sets.md

Gets the number of elements in the StringSet.

```APIDOC
## StringSet.Count

### Description
Gets the number of elements in the StringSet.

### Method
Count

### Parameters
None.

### Request Example
```csharp
tags.Count;
```

### Response
#### Success Response
Returns the number of elements in the set.

#### Response Example
```csharp
// 2
```
```

--------------------------------

### Install CodoMetis.ValueRanges.EFCore.PostgreSQL.NodaTime via dotnet CLI

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/src/CodoMetis.ValueRanges.EFCore.PostgreSQL.NodaTime/README.md

Adds the package to your project. Requires PostgreSQL 16 or later.

```sh
dotnet add package CodoMetis.ValueRanges.EFCore.PostgreSQL.NodaTime
```

--------------------------------

### Convert between InstantRange and Interval, and LocalDateRange to DateInterval

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/src/CodoMetis.ValueRanges.NodaTime/README.md

Shows total conversions from NodaTime's Interval to InstantRange and from DateInterval to LocalDateRange, plus round-trip conversions that throw for shapes the NodaTime types cannot express. ToInterval() throws for ranges that are not finite [start, end) over instants; ToDateInterval() is declared on LocalDateRange.Finite and requires pattern matching first.

```csharp
var interval = new Interval(Instant.FromUtc(2025, 1, 1, 0, 0), Instant.FromUtc(2025, 2, 1, 0, 0));
InstantRange range = interval.ToInstantRange();          // [start, end) Finite
Interval back      = range.ToInterval();                 // round-trips

if (LocalDateRange.Parse("[2025-01-01,2025-01-31]", null) is LocalDateRange.Finite finite)
{
    DateInterval dates = finite.ToDateInterval();
}
```

--------------------------------

### Deconstructing range shapes

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/ranges.md

Every shape that carries a bound deconstructs into its constructor parameters. For discrete types, Finite gives (start, end) inclusive; for continuous types, it gives (start, end, startInclusive, endInclusive).

```csharp
var (first, last) = (DateRange.Finite)period;   // pass straight back to DateRange.CreateFinite

if (price is DecimalRange.Finite(var low, var high, var lowInclusive, var highInclusive)) { … }
```

--------------------------------

### Enable ValueRanges mapping in Program.cs

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/walkthrough.md

Configures the DbContext to use Npgsql with the UseValueRanges() option, which turns on the mapping for the ValueRanges types.

```csharp
builder.Services.AddDbContext<BookingContext>(options => options.UseNpgsql(
    builder.Configuration.GetConnectionString("Bookings"),
    npgsql => npgsql.UseValueRanges()));
```

--------------------------------

### StringSet.CanonicalComparer

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/value-sets.md

Gets the canonical comparer for the set, which is StringComparer.Ordinal.

```APIDOC
## StringSet.CanonicalComparer

### Description
Gets the canonical comparer for the set, which is StringComparer.Ordinal.

### Property
`public static IComparer<string> CanonicalComparer => StringComparer.Ordinal;`

### Returns
- **IComparer<string>** - The canonical comparer.
```

--------------------------------

### FindRooms handler with DateRange and StringSet parameters

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/walkthrough.md

Handles the room search request. Validates the stay, filters rooms by required features, bookable period, and no overlapping bookings, then returns the matching rooms.

```csharp
static async Task<IResult> FindRooms(DateRange stay, StringSet? features, BookingContext db)
{
    if (CheckStay(stay) is { } problem)
        return Invalid("stay", problem);

    var required = features ?? StringSet.Empty;
    var rooms = await db.Rooms
        .Where(room => room.Features.IsSupersetOf(required))
        .Where(room => room.Bookable.Contains(stay))
        .Where(room => !db.Bookings.Any(booking => booking.RoomId == room.Id && booking.Period.Overlaps(stay)))
        .OrderBy(room => room.Id)
        .Select(room => new RoomResult(room.Id, room.Name, room.Features))
        .ToListAsync();

    return TypedResults.Ok(new RoomSearch(stay, required, rooms));
}
```

--------------------------------

### StringSet.Values

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/value-sets.md

Gets the values in the set as an immutable array.

```APIDOC
## StringSet.Values

### Description
Gets the values in the set as an immutable array.

### Property
`public ImmutableArray<string> Values { get; }`

### Returns
- **ImmutableArray<string>** - The values in the set.
```

--------------------------------

### Empty

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Gets an empty YearMonthRange that contains no months.

```APIDOC
## Empty

### Description
Gets an empty YearMonthRange that contains no months.

### Method
Empty

### Returns
YearMonthRange - An empty range.
```

--------------------------------

### Check IsUnboundedStart and IsUnboundedEnd on the infinite range

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/migration.md

Before 10.0.0, IsUnboundedStart() and IsUnboundedEnd() returned false for the infinite range (,), but PostgreSQL's lower_inf and upper_inf return true. Now memory and SQL agree. Pattern-match on shape interfaces to test the kind of range.

```csharp
Int32Range.Infinite.IsUnboundedStart();   // v9: false   v10: true
Int32Range.Infinite.IsUnboundedEnd();     // v9: false   v10: true
Int32Range.CreateUnboundedStart(5).IsUnboundedEnd();   // false in both
```

```csharp
if (range is IUnboundedStartRange<int> s) { … s.End … }   // (-∞, end] only, never (,)
```

--------------------------------

### Infinite

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/nodatime-ranges.md

Gets an infinite range (unbounded on both ends).

```APIDOC
## Infinite

### Description
Gets an infinite range (unbounded on both ends).

### Property
public static LocalDateTimeRange Infinite { get; }

### Returns
- **LocalDateTimeRange** - An infinite range.
```

--------------------------------

### Load booking with curl

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/walkthrough.md

Loads the booking row from PostgreSQL via the API endpoint.

```bash
curl http://localhost:5000/bookings/1
```

--------------------------------

### Run convention tests to list divergences and missing attributes

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/architecture.md

Run second; CloneDivergenceTests lists members differing from family consensus, JsonDefaultContractTests and TypeConverterContractTests list variants without attributes, MappingParityTests lists types no IRelationalTypeMappingSource resolves, and the literal sweeps pick up types by reflection needing only the Bounds row.

```bash
dotnet test --filter "FullyQualifiedName~Conventions.Tests"
```

--------------------------------

### Split a range into fixed-size pieces

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/ranges.md

Splits a finite range into consecutive pieces of one step each, starting from the range's start. The last piece is clipped to the range's end. For continuous types, pieces are half-open except the last. Errors: unbounded range throws NotSupportedException; step of zero or less throws ArgumentOutOfRangeException; a step too small to move the start also throws ArgumentOutOfRangeException. Runs in memory only; not translated by EF Core.

```csharp
Int32Range.CreateFinite(1, 10).Split(4);   // [1,4] [5,8] [9,10]

var hours = TimeRange.CreateFinite(new TimeOnly(9, 0), new TimeOnly(17, 30));
hours.Split(TimeSpan.FromMinutes(30));     // 17 half-hour slots, 09:00–09:30 through 17:00–17:30
```

--------------------------------

### Run oracle status command for unheld claims and unwaived members

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/architecture.md

Run after integration tests; reports unheld claims and unwaived members, then divergences with waiver status, then runs the consumer smoke test for packed artefacts and Native AOT consumer.

```bash
dotnet run tools/oracles.cs status
```

```bash
dotnet run tools/oracles.cs clones
```

```bash
test/consumer-smoke-test.sh
```

--------------------------------

### StringSet indexer

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/value-sets.md

Gets the element at the specified index in the StringSet.

```APIDOC
## StringSet indexer

### Description
Gets the element at the specified index in the StringSet.

### Method
Indexer

### Parameters
- **index** (int) - Required - The zero-based index of the element to get.

### Request Example
```csharp
tags[0];
```

### Response
#### Success Response
Returns the element at the specified index.

#### Response Example
```csharp
// "alpha"
```
```

--------------------------------

### StringSet<TElement>.Count

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/value-sets.md

Gets the number of elements in the set.

```APIDOC
## StringSet<TElement>.Count

### Description
Gets the number of elements in the set.

### Property
`public int Count { get; }`

### Returns
- **int** - The number of elements in the set.
```

--------------------------------

### SkuSet.From

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/value-sets.md

Creates a SkuSet from a collection of Sku values, deduplicating and sorting the elements.

```APIDOC
## SkuSet.From

### Description
Creates a SkuSet from a collection of Sku values, deduplicating and sorting the elements.

### Method
From

### Parameters
- **values** (Sku[]) - Required - The Sku values to include in the set.

### Request Example
```csharp
var skus = SkuSet.From([new Sku(1), new Sku(2), new Sku(1)]);
```

### Response
#### Success Response
Returns a SkuSet containing the unique, sorted Sku values.

#### Response Example
```csharp
// {1,2}
```
```

--------------------------------

### StringSet.IsEmpty

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/_autodocs/api-reference/value-sets.md

Gets a value indicating whether the set is empty.

```APIDOC
## StringSet.IsEmpty

### Description
Gets a value indicating whether the set is empty.

### Property
`public bool IsEmpty { get; }`

### Returns
- **bool** - True if the set is empty; otherwise, false.
```

--------------------------------

### Search response after second booking

Source: https://github.com/caffeinatedcoder/codometis.valueranges/blob/main/docs/walkthrough.md

The first search, sent again, now finds only the Lighthouse room because the Harbour room is booked for the requested window.

```json
{"stay":"[2026-07-01,2026-07-04]","features":["balcony","sea-view"],"rooms":[{"id":3,"name":"Lighthouse","features":["balcony","bathtub","sea-view"]}]}
```
Tokens:
Raw