Table of Contents

Introduction

Bodu is a solution that ships a family of independent .NET NuGet packages, each focused on a narrow, well-defined problem domain. Every package is versioned and released on its own - and most are self-contained, with the few cross-package dependencies listed below - but they share a single set of source and documentation conventions, a single analyzer and test configuration, and a single quality bar.

The suite is organized into seven topics. Each topic groups the packages that solve related problems, and each has a dedicated overview page explaining the collective purpose of its members and how they fit together. If you are new to Bodu, start with the topic that matches your problem, then drill into the member library's introduction.

The suite in seven topics

Core Foundations

The foundation every other package builds on - collections, buffers, extensions, argument validation, and text-encoding utilities.

Package What it provides Target framework
Bodu.Core The foundation package - a day-of-week WeekPattern value type, pooled buffers, async coordination primitives, railway outcomes (Option<T> / Result<T> / Either<TLeft,TRight>), and a comprehensive set of date, numeric, span, and text extensions sitting on a centralized ThrowHelper. net8.0
Bodu.Collections The specialized collection catalogue (depends on Bodu.Core; namespaces unchanged) - fixed-capacity rings (CircularBuffer<T>, Deque<T>), policy-driven caches (EvictingDictionary<TKey,TValue> with TTL expiry), navigable sets/dictionaries with rank/select, range-keyed lookups and overlap-storing interval trees, graphs, tries and multi-pattern text search, and the probabilistic sketches. net8.0
Bodu.Collections.Concurrent The thread-safe collection companion (depends on Bodu.Collections) - the lock-free ConcurrentCircularBuffer<T> (Vyukov MPMC, IProducerConsumerCollection<T>), the lock-free split-ordered ConcurrentHashSet<T> with snapshot enumeration, and the lock-striped ConcurrentEvictingDictionary<TKey,TValue> bounded cache (all six eviction policies, optional TTL, single-flight GetOrAdd). net8.0
Bodu.Text (namespace in Bodu.Core) Encoding-detection and text / byte conversion helpers over System.Text.Encoding - BOM-based EncodingDetection, plus EncodingExtensions and StringEncodingExtensions for span-, UTF-8-, and pooled-buffer-friendly transcoding, preamble handling, and validation. net8.0

Hashing & Cryptography

Two packages split by a single question - is there an adversary? Non-cryptographic fingerprints, checksums, and check digits on one side; ciphers, AEAD, MACs, digests, KDFs, and the RFC 6962 Merkle tree with its inclusion and consistency proofs on the other.

Package What it provides Target framework
Bodu.IO.Hashing Non-cryptographic hashing on the BCL NonCryptographicHashAlgorithm contract - fingerprints (FNV, CityHash, MurmurHash3, Pearson, Bernstein and the classic string hashes), checksums (CRC, Fletcher, Adler), and check digits (Luhn, Damm, Verhoeff, IBAN, ISBN, …). Nothing here is safe against an adversary; everything is fast and portable. net8.0
Bodu.Security.Cryptography Cryptographic primitives on the BCL SymmetricAlgorithm and HashAlgorithm contracts - managed block ciphers (Threefish, Serpent, Camellia, Twofish, Blowfish, Skipjack), AES paired with six AEAD mode transforms (GCM, CCM, OCB, EAX, SIV, GCM-SIV), keyed hashes (SipHash, Poly1305), cryptographic digests (Tiger, CubeHash, Snefru, Whirlpool, BLAKE2/3, Skein, Shake), the RFC 6962 Merkle tree with inclusion and consistency proofs, and the full ASCON family. net8.0

Globalization & Calendars

A resource-driven notable-date engine plus an ecosystem of opt-in companions (fluent authoring, dependency injection, trust-gated plugins) and per-region holiday data packs.

Package What it provides Target framework
Bodu.Globalization.Calendar Rule-driven notable-date resolution - public holidays, observances, religious festivals - for any year, territory, or calendar system. Built-in algorithms cover Gregorian and Orthodox Easter, Hindu Lunar dates, Losar, Vesak, Asalha Puja, and Qingming, with a pluggable algorithm registry, observance-adjustment pipeline, and trust-policy-driven plugin host. Companion packages add fluent authoring (…Builder), IServiceCollection registration (…DependencyInjection), plugin loading (…Plugins), and five regional data packs. net8.0
Bodu.Globalization.Recurrence Recurrence-rule evaluation with no dependency on the calendar engine - RecurrenceRule for RFC 5545 RRULE (parse, format, and occurrence enumeration across every frequency and BY* part), RecurrenceSet for rules composed with RDATE / EXDATE, CronExpression for Vixie five-field and six-field cron, and AnchoredInterval for instant-anchored repetition. Every form answers both GetNextOccurrence and GetPreviousOccurrence, and is pure in its arguments - no wall clock, no machine time zone. net8.0

Text & Serialization

Three different jobs that all sound like "text": binary-to-text codecs, document formats, and object serializers.

Package What it provides Target framework
Bodu.Text.Encoding Binary-to-text encoders for Base16, Base32, Base64, Base58, and Base85 with every common variant (RFC 4648 standard / hex-extended / URL-safe / MIME, Crockford, z-base-32, Bitcoin/Flickr / Ripple, Ascii85 / Z85). Each encoding exposes the same modern API shape: span- and UTF-8-friendly overloads, OperationStatus streaming, length-prediction helpers, validation predicates, plus a unified IBinaryEncoding interface for runtime-pluggable encoding choice. net8.0
Bodu.Text.Filtering A high-performance include/exclude filtering engine for lists of text values. Glob (wildcard, character-class, {a,b} alternation) and regex patterns compile once into an immutable TextFilter that runs the cheapest matching strategies first; choose Ant / MSBuild-style AnyMatch sets or gitignore-style LastMatchWins ordered rules, parse raw lines with the gitignore conventions, and observe decisions through built-in statistics and a per-decision observer. net8.0
Bodu.Text.Formats Self-framing text document formats with strongly-typed value models and span- and stream-friendly codecs. An umbrella over three sibling packages - Delimited (CSV / TSV), DotEnv, and Ini - each shipping a Utf8…Reader / Utf8…Writer pair, a …Serializer POCO mapper, and mutable and read-only DOMs, with strict invariant enforcement. net8.0
Bodu.Text.Bencode · Bodu.Text.Toml · Bodu.Text.Yaml Three serializers that map your own types to and from a format - a shared architecture over the Bodu.Text.Serialization engine and a System.Text.Json-aligned shape, each shipping a …Serializer, a mutable …Node and a read-only …Document DOM, and a low-level Utf8…Reader / Utf8…Writer pair. Bencode covers BitTorrent BEP 3; TOML covers v1.0.0 / v1.1.0; YAML the 1.2 core schema with block / flow collections, anchors, and multi-document streams. See the shared family introduction. net8.0

Configuration

Layered, EditorConfig-style configuration - a parser/resolver plus a bridge into the Microsoft.Extensions.Configuration pipeline.

Package What it provides Target framework
Bodu.Text.Configuration EditorConfig-style configuration layering over an INI document model. Layers a preamble plus glob-anchored sections in source order for a target file path, then projects the result into a flat, colon-delimited ConfigurationView with typed accessors (GetInt32, GetEnum<T>, GetValue<T>). Profile presets, optional diagnostic collection, and byte-faithful round-trip save. net8.0
Bodu.Extensions.Configuration.Text Bridges Bodu.Text.Configuration to Microsoft.Extensions.Configuration. Adds AddTextConfiguration* entry points on IConfigurationBuilder - mirroring AddJsonFile / AddJsonStream - so a Bodu configuration file layers alongside JSON, INI, XML, and environment-variable sources, with IOptions<T> binding and reload-on-change support. net8.0

Numerics & Financial

Exact arithmetic - rational numbers and intervals, and the money, currency, and exchange-rate primitives built on top of them.

Package What it provides Target framework
Bodu.Numerics Generic-math value primitives - Fraction<T> for exact rational arithmetic over any IBinaryInteger<T> with canonical-form auto-reduction and BigInteger-promoted intermediates, and Interval<T> for closed / open / half-open bounded intervals with intersection, union, and adjacency. net8.0
Bodu.Financial Type-safe monetary primitives - Money<TCurrency> (currency as type parameter, so cross-currency arithmetic fails the build), Money for runtime-tagged scenarios, MoneyBag for multi-currency portfolios, the ISO 4217 currency catalogue, exchange-rate providers, allocation, and cash rounding. net8.0

Binary Formats & I/O

Legacy binary container and document formats - a general-purpose compound-file container (read, edit, and author) with narrower read-only format readers layered on top.

Package What it provides Target framework
Bodu.IO.Compound A reader, editor, and writer for the OLE2 / Compound File Binary (CFB) container - the structured-storage "file system in a file" behind legacy Office documents (.xls, .doc, .ppt, .msg). Navigates the RootStorage hierarchy, reads each named stream through a seekable CompoundStream cursor (buffered or on-demand), edits and authors containers with a transactional Commit / CommitAsync, and reads and writes the OLE summary-information property sets. net8.0
Bodu.IO.Biff A low-level codec for the Excel Binary Interchange File Format (BIFF5 and BIFF8) record streams found inside legacy .xls workbooks - the substrate beneath Bodu.Formats.Excel.Binary, in the same relation Bodu.IO.Pst has to Bodu.Formats.Outlook.Pst. The forward-only BiffReader frames records and exposes typed accessors; BiffSstReader walks the shared string table; BiffWriter emits BIFF5 or BIFF8 records. No compound-file dependency, no workbook or cell model. net8.0
Bodu.Formats.Excel.Binary A narrow, read-only BIFF5 and BIFF8 (.xls) reader built on Bodu.IO.Compound and Bodu.IO.Biff that surfaces raw worksheet cell values - strings, numbers, booleans, and errors - without formula evaluation, styling, or higher-level interpretation. net8.0
Bodu.IO.Pst A low-level, read-only container reader for the Outlook personal-folders format (PST / MS-PST, Unicode and ANSI) - the node database (header, node and block B-trees, block data with the permute and cyclic encodings decoded and checksums verified, data and subnode trees) and the LTP layer over it, exposing each PstNode's property-context and table-context views with wire-typed values. The substrate beneath the .pst mail-store reader; no MAPI semantics, no writing. net8.0
Bodu.Formats.Outlook The Outlook format readers over the shared MAPI value model - property tags and types, the tag-addressed MapiPropertyCollection, and named-property identities in Bodu.Formats.Outlook; Bodu.Formats.Outlook.Msg opens a .msg message over Bodu.IO.Compound, and Bodu.Formats.Outlook.Pst opens a .pst mail store over Bodu.IO.Pst - folders, messages, recipients, attachments, embedded messages, and the text / HTML / compressed-RTF bodies. Read-only; no MAPI session emulation. net8.0

Each package is versioned and released independently - take the one you need and ignore the others. Bodu.Core sits under the whole suite: its ThrowHelper supplies the shared argument validation, and every runtime package references it directly or transitively. The remaining cross-package dependencies run one way: Bodu.Collections builds on Bodu.Core, and Bodu.Collections.Concurrent builds on Bodu.Collections; Bodu.Text.Formats is an umbrella over Bodu.Text.Delimited, Bodu.Text.DotEnv, and Bodu.Text.Ini, and those three - like Bodu.Text.Bencode, Bodu.Text.Toml, and Bodu.Text.Yaml - build on the shared Bodu.Text.Serialization engine; Bodu.Text.Configuration references only Bodu.Core; Bodu.Extensions.Configuration.Text builds on Bodu.Text.Configuration, Bodu.Text.Toml, and Bodu.Text.Bencode plus Microsoft.Extensions.Configuration; Bodu.Financial builds on Bodu.Numerics for its Fraction<BigInteger> precision escape hatch; Bodu.Formats.Excel.Binary builds on Bodu.IO.Compound and Bodu.IO.Biff to read BIFF5 and BIFF8 .xls workbooks; Bodu.IO.Pst builds on Bodu.Collections; Bodu.Formats.Outlook is container-free and is consumed by Bodu.Formats.Outlook.Msg (over Bodu.IO.Compound) and Bodu.Formats.Outlook.Pst (over Bodu.IO.Pst); and Bodu.Globalization.Recurrence references only Bodu.Core - it is a sibling of the calendar engine, not a dependant. The package matrix lists every package's dependencies.

Library introductions

Each library has a dedicated introduction page that explains its namespaces, the role of each headline type, and the scenarios it is designed for. Pair it with the matching getting-started page for install commands and a minimal sample. The cards below follow the seven-topic order.

Core Foundations

Bodu.Core

Day-of-week patterns, pooled buffers, async coordination and railway primitives, and date / numeric / span extensions. Useful in almost any application; depended on internally by every other Bodu package.

Introduction Getting started Guides API reference

Bodu.Collections

The specialized collection catalogue - bounded rings, eviction-aware caches with TTL expiry, navigable and range-keyed lookups, interval trees, graphs, tries, and probabilistic sketches. Depends on Bodu.Core; namespaces unchanged.

Introduction Getting started Guides API reference

Bodu.Collections.Concurrent

The thread-safe collection companion - a lock-free MPMC ConcurrentCircularBuffer<T>, a lock-free split-ordered ConcurrentHashSet<T>, both with snapshot enumeration, and the lock-striped ConcurrentEvictingDictionary<TKey,TValue> bounded cache. Depends on Bodu.Collections.

Introduction Getting started Guides API reference

Bodu.Text

Encoding detection and ergonomic text / byte conversion over System.Text.Encoding - BOM-based EncodingDetection, plus span-, UTF-8-, and pooled-buffer-friendly EncodingExtensions and StringEncodingExtensions.

Introduction API reference

Hashing & Cryptography

Bodu.IO.Hashing

Non-cryptographic hashes - fingerprints, checksums, and human-readable check digits. Optimized for speed, portability, and error-detection coverage rather than adversary resistance.

Introduction Getting started Guides API reference

Bodu.Security.Cryptography

Block ciphers, authenticated encryption, keyed hashes, and cryptographic digests with a formal adversary model. Drops into any API that expects SymmetricAlgorithm or HashAlgorithm.

Introduction Getting started Guides API reference

Globalization & Calendars

Bodu.Globalization.Calendar

Notable-date resolution and dynamic calendar calculators driven from pluggable XML or JSON rule sources, with an observance-adjustment pipeline, plugin host, and territory filtering.

Introduction Getting started Guides API reference

Bodu.Globalization.Recurrence

Recurrence-rule evaluation in four shapes - RFC 5545 RRULE and RecurrenceSet, Vixie CronExpression, and instant-anchored AnchoredInterval - each answering both the next and the previous occurrence, and each pure in its arguments.

Introduction Getting started Guides API reference

Text & Serialization

Bodu.Text.Encoding

Binary-to-text encoders for Base16, Base32, Base64, Base58, and Base85 with every common variant. Span-, UTF-8-, and OperationStatus-friendly; unified IBinaryEncoding interface for runtime-pluggable choice.

Introduction Getting started Guides

Bodu.Text.Filtering

Include/exclude text filtering: glob and regex patterns compiled into a cost-tiered TextFilter, with Ant / MSBuild set semantics or gitignore-style ordered rules, gitignore-convention parsing, and built-in match telemetry.

Introduction Getting started Guides

Bodu.Text.Formats

Self-framing text document formats with strongly-typed value models and span- and stream-friendly codecs. Ships Delimited (CSV / TSV), DotEnv, and Ini as sibling namespaces, each with strict invariant enforcement.

Introduction Getting started Guides

Bodu serializers - Bencode, TOML & YAML

Three serializers - POCO ↔ format - for Bencode (BEP 3), TOML, and YAML. A shared architecture over Bodu.Text.Serialization, each with a serializer, a mutable and a read-only DOM, and a low-level Utf8…Reader / Utf8…Writer pair.

Introduction Bencode TOML YAML Guides

Configuration

Bodu.Text.Configuration

EditorConfig-style configuration layering over an INI document model - glob-anchored sections resolved for a target path into a flat, typed ConfigurationView, with profile presets, diagnostic collection, and round-trip save.

Introduction Getting started Guides API reference

Bodu.Extensions.Configuration.Text

The Microsoft.Extensions.Configuration bridge - an AddTextConfiguration* builder entry point that layers a Bodu configuration file alongside JSON, INI, and environment-variable sources with IOptions<T> binding.

Introduction Getting started Guides API reference

Numerics & Financial

Bodu.Numerics

Generic-math value primitives - Fraction<T> for exact rational arithmetic and Interval<T> for closed / open / half-open bounded intervals, both over the INumber<T> abstractions.

Introduction Getting started Guides API reference

Bodu.Financial

Type-safe monetary primitives - Money<TCurrency> with compile-time currency safety, Money for runtime-tagged scenarios, the ISO 4217 catalogue, exchange-rate providers, allocation, and cash rounding.

Introduction Getting started Guides API reference

Binary Formats & I/O

Bodu.IO.Compound

An OLE2 / Compound File Binary (CFB) container reader, editor, and writer - navigate the storage hierarchy, read each named stream through a seekable CompoundStream cursor, edit or author containers with a transactional commit, and read and write the OLE property sets. The BIFF5 and BIFF8 .xls reader Bodu.Formats.Excel.Binary is built on it, with the record stream decoded by Bodu.IO.Biff.

Introduction Getting started Guides API reference

Bodu.IO.Biff

A low-level codec for the BIFF5 and BIFF8 record streams inside legacy .xls workbooks - the substrate beneath Bodu.Formats.Excel.Binary. Walk a workbook stream record by record with the allocation-free BiffReader and its typed accessors, decode the shared string table with BiffSstReader, and emit BIFF5 or BIFF8 records with BiffWriter; no compound-file dependency, no workbook or cell model.

Introduction Getting started API reference

Bodu.Formats.Excel.Binary

A narrow, read-only BIFF5 and BIFF8 (.xls) reader built on Bodu.IO.Compound and Bodu.IO.Biff - surface raw worksheet cell values (strings, numbers, booleans, errors, and a formula's cached result) through a forward-only ExcelWorksheetReader or a randomly addressable ExcelWorksheet, with date-format detection and serial-date conversion, without formula evaluation or styling.

Introduction Getting started Guides API reference

Bodu.IO.Pst

The read-only PST container layer - walk the node database and read any PstNode's property-context and table-context views with wire-typed values, with the block encodings decoded and the checksums verified. No MAPI semantics; the substrate the mail-store reader sits on.

Introduction Getting started Guides API reference

Bodu.Formats.Outlook

The Outlook message and mail-store readers over one shared MAPI value model - open a .msg file or a .pst store and read folders, messages, recipients, attachments, embedded messages, and the text / HTML / compressed-RTF bodies. Read-only.

Introduction Getting started Guides API reference

Design principles

  • Small by intent. Each library solves one coherent problem. If something already fits well elsewhere in .NET, we don't duplicate it.
  • Nullable reference types are enabled solution-wide. Public APIs make their null-intent explicit.
  • Analyzer-clean. StyleCop.Analyzers, Roslynator, the .NET analyzers, AsyncFixer, and the Visual Studio Threading analyzers run at build time. Doc-comment warnings - including CS1591 - are treated as errors.
  • Deterministic builds produce reproducible package outputs.
  • Documentation-first. Every public type and member carries XML documentation in US English, and that documentation is the source of truth for this site. The API reference you see here is generated directly from the source.
  • MIT licensed, with minimal external runtime dependencies - the core libraries depend only on the BCL; the dependency-injection, caching, JSON, and Outlook packages pull in a few permissively licensed Microsoft packages (see Licensing).

Testing and conventions

The solution uses MSTest with a partial-class test layout that mirrors the source layout one-to-one. Test methods follow the naming convention <MethodOrProperty>_When<Condition>[_For<TypedCondition>]_Should<ExpectedResult> and carry an XML <summary> that starts with "Verifies that …", which makes test intent readable directly in the test explorer without opening the test body.

Where to go next