Cuemon.Extensions.Collections.Generic

Overview

Cuemon.Extensions.Collections.Generic extends standard generic collection interfaces with partitioning, pagination, ordering, shuffling, fallback lookup, and list-navigation helpers. It builds on Cuemon.Collections.Generic, but keeps the entry points on familiar BCL types such as IEnumerable<T>, ICollection<T>, IList<T>, Queue<T>, Stack<T>, and IDictionary<TKey, TValue>.

That makes the package a convenience layer rather than a replacement collection model. You keep working with ordinary .NET collections, then opt into partitioners, pagination objects, and safer mutation or lookup patterns only where the workflow needs them.

Key APIs

AddRange<T> appends either an IEnumerable<T> or params T[] to any ICollection<T>. When the receiver is already a List<T>, the implementation forwards to List<T>.AddRange instead of re-adding one item at a time.

Chunk<T> turns an IEnumerable<T> into a PartitionerEnumerable<T> with a configurable batch size. It validates both the source sequence and the requested size, then exposes a partitioned iterator that can be consumed incrementally.

ToPartitioner<T> offers the same partitioning model for both IEnumerable<T> and ICollection<T>. Use it when you want the explicit PartitionerEnumerable<T> or PartitionerCollection<T> types rather than the more task-oriented Chunk<T> entry point.

ToPagination<T> projects a sequence into a PaginationEnumerable<T> by combining the current page data with a total-element counter and optional PaginationOptions configuration. Tests show it carrying page metadata such as first or last page state and next or previous availability alongside the items.

ToPaginationList<T> eagerly materializes the current page into a PaginationList<T>. That is useful when callers need both the page metadata and indexed access to the page contents.

GetValueOrDefault<TKey, TValue> reads a dictionary entry without forcing the caller to branch around TryGetValue. An overload accepts a Func<TValue> so the fallback value can be computed only when the key is missing.

TryGetValueOrFallback<TKey, TValue> lets the caller derive an alternate key from the dictionary's existing keys before giving up. That gives dictionary consumers a built-in way to express alias or fallback lookup rules without duplicating the retrieval flow.

AddOrUpdate<TKey, TValue> and TryAdd<TKey, TValue> cover the common mutation cases for dictionaries. AddOrUpdate replaces an existing value when the key is already present, while TryAdd supports both unconditional uniqueness checks and caller-supplied add conditions.

HasIndex<T>, Next<T>, and Previous<T> add boundary-aware list navigation to IList<T>. They help callers probe valid positions or move relative to an index without repeating count checks and default-value handling at each call site.

Basic usage

using System.Linq;
using Codebelt.Extensions.Xunit;
using Cuemon.Extensions.Collections.Generic;
using Xunit;

namespace Contoso.Billing.Tests;

public class InvoicePagingTest : Test
{
    public InvoicePagingTest(ITestOutputHelper output) : base(output) { }

    [Fact]
    public void ShouldCreateLastInvoicePageFromProjectedSequence()
    {
        var invoiceNumbers = Enumerable.Range(1200, 53);
        var page = invoiceNumbers.ToPaginationList(() => 53, options =>
        {
            options.PageSize = 10;
            options.PageNumber = 6;
        });

        TestOutput.WriteLine($"Last page contains: {string.Join(", ", page)}");

        Assert.True(page.LastPage);
        Assert.False(page.HasNextPage);
        Assert.Equal(6, page.PageCount);
        Assert.Equal(53, page.TotalElementCount);
        Assert.Equal(new[] { 1250, 1251, 1252 }, page);
    }
}

Use this pattern when a query already yields a standard IEnumerable<T> but the caller still needs an indexable page plus paging metadata for a UI or API response. It matters because ToPaginationList<T> keeps the calling code on standard sequence types while surfacing the boundary information from PaginationList<T> without an extra wrapper layer.

Installation

dotnet add package Cuemon.Extensions.Collections.Generic

Usage guidance

Use this package when your code already works with standard generic collections and you want pagination, partitioned iteration, safer dictionary lookup, or list-navigation helpers without replacing those collection types. If built-in LINQ and BCL collection members already cover the workflow, stay with the framework APIs, and if you need to construct or reason about the lower-level partitioner and pagination types directly, look to Cuemon.Collections.Generic as the underlying package.