Table of Contents

Bodu.Core - Core concepts

This page is the vocabulary the rest of the documentation assumes. Read it once before the getting-started samples or the guides, and refer back whenever a term feels imprecise.

Part of the Core Foundations topic.

For the high-level shape of the library and the namespace map, start with the introduction. The collection vocabulary - fixed capacity, ring backing, eviction policies, navigation, sketches - lives on the Bodu.Collections concepts page, and the concurrency vocabulary on the Bodu.Collections.Concurrent concepts page.

Calendar value sets

A calendar value set is an immutable readonly struct holding the values a schedule selects from one calendar field, one bit per value. DayOfWeekSet holds days of the week; MonthSet, DayOfMonthSet, HourSet, MinuteSet, and SecondSet hold months, days of the month, hours, minutes, and seconds. Each supports:

  • Composition - With and Without return new sets; the operators |, &, ^, ~ compose union, intersection, symmetric difference, and the complement within the field's range.
  • Membership - Contains answers false for a value outside the field's range rather than throwing, so testing a DateTime component is a comparison and a bit test.
  • Text - DayOfWeekSet.Parse("_MTWTF_") produces the weekday set; its text form is a seven-character mask of day initials in Sunday-first order (Monday-first is auto-detected, or forced with ParseExact(input, "M")), with _ for absent days, or seven 0/1 bits. The numeric sets read and write a list of values and ranges, such as "1-3,12", every value without ranges (format L), or one 0/1 per value (format B), and MonthSet also a mask of the months' initials, "JFM________D" (format J). Parse tells the forms apart; ParseExact reads the one you name.
  • Enumeration - each implements IEnumerable<T>, yielding the selected values in ascending order (DayOfWeek order for days) through a struct enumerator that does not allocate.
  • One interface - each implements ICalendarValueSet<TSelf, TValue>, with int values, or DayOfWeek for days, so a generic method can take any of them.

Presets DayOfWeekSet.Empty, DayOfWeekSet.Weekdays, DayOfWeekSet.Weekend, and DayOfWeekSet.All cover the common cases, and the regional working-week presets (MondayToFriday, MondayToSaturday, SundayToThursday, SaturdayToWednesday, …) mirror the members of WorkingDaysOfWeek, the companion enum naming the common working weeks; conversion to and from DayOfWeekSet is via the extension methods on WorkingDaysOfWeekExtensions. DayOfWeekSet replaced WeekPattern in Bodu.Core 1.3.0; the DayOfWeekSet guide maps each removed member to its replacement.

Pooled buffer

A pooled buffer is a writer-style builder backed by ArrayPool<T> rather than new T[]. PooledBufferBuilder<T> rents an array on construction, grows it by re-renting when needed, exposes WrittenSpan for zero-copy reads, and returns the array to the pool on Dispose.

Ownership semantics:

  • The builder owns the rented array; callers must call Dispose (or use using) to return it.
  • WrittenSpan and WrittenMemory are valid only while the builder is alive. Copy out before disposal if the data must outlive the using block.
  • For reference-typed T, the live portion is cleared before the array is returned, preventing unintended object retention.
  • Reset discards the accumulated content and reuses the current rented buffer without a pool round-trip.

The builder implements IBufferWriter<T> and IMemoryOwner<T>, so it slots into standard Span<T> / Memory<T> pipelines.

Railway-oriented outcomes

The Bodu.Functional namespace models "this might not produce a value" as data rather than control flow. Three value types cover the three shapes of the problem:

  • Option<T> - a value that may be absent: Some(value) or None. Reach for it when absence is normal and carries no explanation (a cache miss, an optional setting).
  • Result / Result<T> - success or failure, where failure carries a ResultError (optional code, never-null message, optional captured exception). Reach for it when the caller needs to know why an operation failed without paying for a thrown exception.
  • Either<TLeft, TRight> - a symmetric disjoint union of two equally valid alternatives, with no success/failure bias.

The railway style chains these through combinators instead of if/throw ladders: Map transforms the value on the success track, Bind sequences a fallible step, Filter demotes a Some to None, and Match forces both tracks to be handled at the exit. Task-based companions (MapAsync / BindAsync / MatchAsync / TapAsync on OptionAsyncExtensions and ResultAsyncExtensions) keep the chain flowing through async steps.

Because all three are readonly structs, each defines its default contract - what an unassigned field means:

Type default means
Option<T> None - absence, safely.
Result<T> A failure carrying an empty error - never a phantom success.
Either<TLeft,TRight> An explicit uninitialized state - neither side is fabricated.

Natural ordering

Ordinal string comparison sorts file10 before file2 because '1' < '2' - correct for code, wrong for humans. Natural ordering compares embedded digit runs numerically while comparing the surrounding text as text, so file2 sorts before file10.

NaturalStringComparer implements this as a standard IComparer<string> with ordinal, case-insensitive, and culture-aware modes, so it drops into OrderBy, SortedSet<string>, Array.Sort, or any API that accepts a comparer. Its companions ComparableExtensions and ComparableHelper round out ordering ergonomics for any IComparable<T> - Min, Max, Clamp, and readable comparison predicates (IsGreaterThan, IsGreaterThanOrEqual). See the Natural string comparer guide.

Async coordination

The Bodu.Threading namespace provides the async-friendly peers of the BCL synchronization types: where lock, Monitor, and ManualResetEvent block a thread, these primitives return awaitables, so a waiting caller yields its thread back to the pool.

The common contract: waiting never blocks a thread, cancellation is honoured through CancellationToken parameters, and lock releases are scoped by IDisposable so a using guarantees the release path. RateGate is the exception: it never waits, so it has no awaitable and no token. See the Async coordination primitives guide.

ThrowHelper

ThrowHelper centralises the ArgumentException family for the entire Bodu suite - every Bodu library calls into it rather than rolling its own checks. The pattern is:

public static double Average(IReadOnlyList<int> values)
{
    ThrowHelper.ThrowIfNull(values);
    ThrowHelper.ThrowIfZero(values.Count);
    return values.Average();
}

The helpers are partitioned by concern across partial files: Null, Numeric, Comparison, Equality, Array, Collection, Span, Stream, Type, String, Ascii. Each helper accepts a [CallerArgumentExpression(nameof(value))] string? paramName = null parameter, so the call site does not need to repeat the argument name. The same surface ships for net8.0 and net10.0.

Centralising the guards means the exception messages and parameter-name capture stay consistent across every Bodu library - and ThrowHelper is the primary dependency the other Bodu packages take on Bodu.Core.

Random generator abstraction

Several extension helpers - shuffles, sampling, randomised access - and the Bodu.Collections catalogue depend on a pluggable random source rather than a hard-coded Random. The seam is IRandomGenerator, a one-method interface (int Next(int maxValue)).

Two implementations ship in Bodu.Core:

Implementation Use when
XorShiftRandom Tight inner loops, reproducible tests, or shuffle code where the BCL's Random is the measured bottleneck. Subclasses System.Random and implements IRandomGenerator.
SystemRandomAdapter An existing System.Random instance must be reused - for example a seeded Random shared across multiple helpers. Wraps the Random and forwards calls.

Neither implementation is cryptographically secure; both are deterministic given a seed. Callers that need cryptographic randomness should use <xref:System.Security.Cryptography.RandomNumberGenerator> directly. Helpers that accept an IRandomGenerator make the dependency explicit so tests can supply a deterministic generator without monkey-patching globals.

Calendar-shape extensions

The Bodu.Extensions namespace ships several enums that encode the shape of a calendar without implementing one - they parameterise the date arithmetic on DateTimeExtensions and DateOnlyExtensions without pulling in Bodu.Globalization.Calendar:

Type Encodes
CalendarQuarterDefinition The start month of Q1 - JanuaryToDecember, JulyToJune, AprilToMarch, April6ToApril5 (UK tax year), March25ToMarch24 (Lady Day), OctoberToSeptember, FebruaryToJanuary, plus Custom for externally defined rules. Drives Quarter, FirstDateOfQuarter, LastDateOfQuarter, and the other quarter members; the fiscal-year members (FiscalYear, AddFiscalYears, and their companions) take an IQuarterDefinitionProvider instead.
WeekOrdinal The ordinal position of a weekday in a month - First, Second, Third, Fourth, Fifth, Last. Drives NthDateOfWeekInMonth and the recurrence-rule patterns.
FiscalWeekPattern The 4-4-5 / 4-5-4 / 5-4-4 split for retail-style 13-week fiscal quarters. Each quarter is always 13 weeks; the pattern only affects fiscal-period boundaries inside the quarter. The extra week in a 53-week fiscal year is always appended to the final period of Q4.
WorkingDaysOfWeek Named working-week presets - MondayToFriday, MondayToSaturday, SaturdayToThursday, SaturdayToWednesday, and others - plus Custom, a working week defined by an IWeekendDefinitionProvider; a caller holding a DayOfWeekSet passes it directly to the DayOfWeekSet overloads instead. Drives IsWeekday, IsWeekend, IsInWorkingWeek, NextWeekday.
IWeekendDefinitionProvider The injection seam for non-enumerable weekend rules - pass an implementation to override the built-in WorkingDaysOfWeek presets when an application needs hybrid, rotating, or domain-specific weekend logic.

These types are pure data carriers. The actual algorithms live on the extension classes (DateTimeExtensions.*, DateOnlyExtensions.*) so the same shapes can be passed to a DateTime, DateOnly, or any future date type without duplicating the enums.

Where to go next