Guides
Recipe-style walk-throughs and conceptual introductions for every library in the Bodu suite, organized by the suite's seven topics. Each topic has its own guides landing page that maps the member libraries' guide sections, and each library's section below is organized by namespace, with one walk-through per headline type.
If you are new to Bodu, start with the introduction for the project overview, or the getting-started page for install commands. To choose between hashing or cryptography types that sound similar, see the Bodu.IO.Hashing and Bodu.Security.Cryptography introductions.
Topic guide landings: Core Foundations · Hashing & Cryptography · Globalization & Calendars · Text & Serialization · Configuration · Numerics & Financial · Binary Formats & I/O
Core Foundations
General-purpose building blocks every other package depends on - see the Core Foundations guides landing.
Bodu.Core
Day-of-week patterns, pooled buffers, async coordination and railway primitives, memoization, natural string ordering, and date / numeric / span extensions - the Bodu, Bodu.Buffers, Bodu.Extensions, Bodu.Functional, and Bodu.Threading namespaces.
Overview
Namespace map for Bodu.Core and Bodu.Collections - key types and which guide covers each.
WeekPattern
Immutable bitmask value type for day-of-week sets - composition, parsing, bitwise operators.
Natural string comparer
Numeric-aware ordering (file2 before file10) as a stateless, thread-safe NaturalStringComparer with the StringComparer factory shape.
Pooled buffer builder
PooledBufferBuilder<T> - assemble a span from ArrayPool<T>-rented arrays; implements IBufferWriter<T> and IMemoryOwner<T>.
Async coordination primitives
The Bodu.Threading counterparts of the synchronous System.Threading gates - await a lock or a signal without blocking a thread.
Options, results, and eithers
The Bodu.Functional railway primitives - Option<T>, Result / Result<T>, and Either<TLeft,TRight>.
Memoization
Memoizer - wrap a pure, expensive Func<…> in a thread-safe result cache.
Bodu.Collections
The specialized collection catalogue (depends on Bodu.Core) - bounded rings, eviction-aware caches, navigable and range-keyed lookups, interval trees, graphs, tries, and probabilistic sketches in the Bodu.Collections.Generic, .Generic.Graphs, .Generic.Trees, and Bodu.Collections.Probabilistic namespaces.
Choosing a collection
The decision guide - which collection to reach for, without walking every namespace.
Circular buffer
Fixed-capacity FIFO ring buffer - single-threaded and thread-safe variants, overwrite mode, peek / dequeue / try-enqueue patterns.
Deque
Double-ended queue with O(1) add and remove at both ends; growable or fixed-capacity.
Evicting dictionary
Capacity-bounded key-value store with FIFO, LRU, LFU, MRU, Random, and Second-Chance eviction policies.
The remaining collection guides - sequenced and bidirectional dictionaries, indexed priority queue, ordered sets, multiset, multi-value dictionary, segmented buffer, range-keyed lookups, interval tree, bit set, navigable set and dictionary, layered and defaulting dictionaries, the two-key table, probabilistic sketches, graphs, and tries - are listed on the Core Foundations guides landing.
Bodu.Collections.Generic API reference
Bodu.Collections.Concurrent
The thread-safe members of the catalogue (depends on Bodu.Collections), in the Bodu.Collections.Generic.Concurrent namespace.
Concurrent collections
ConcurrentCircularBuffer<T> (lock-free Vyukov MPMC), ConcurrentHashSet<T> (lock-free split-ordered), and ConcurrentEvictingDictionary<TKey,TValue> (lock-striped bounded cache).
Bodu.Collections.Generic.Concurrent API reference
Hashing & Cryptography
Non-cryptographic hashing on one side, a formal adversary model on the other - see the Hashing & Cryptography guides landing for the combined map.
Bodu.IO.Hashing
Non-cryptographic hashing - fingerprints, checksums, and check digits - built on the BCL NonCryptographicHashAlgorithm contract. Nothing here is safe against an adversary; everything is fast and portable.
Overview
Namespace map (Bodu.IO.Hashing, .Checksums, .CheckDigits) - key types and which guide covers each.
Bodu.IO.Hashing - Fingerprints
Using FNV
FNV-1 and FNV-1a at 32- and 64-bit widths - the textbook constant-memory fingerprint.
Using CityHash
32-, 64-, and 128-bit Google CityHash - SIMD-friendly fingerprint for long inputs.
Using MurmurHash3
32- and 128-bit MurmurHash3 - seeded, excellent avalanche.
Using Pearson
Table-driven hash with output widths from 8 to 2048 bits.
Classic string hashes
Bernstein, BKDR, SDBM, JSHash, Elf64, ApHash, PJW, SuperFastHash.
For xxHash specifically, use
System.IO.Hashing.XxHash32/XxHash64/XxHash3/XxHash128from the BCL - Bodu does not duplicate them.
Bodu.IO.Hashing.Checksums - Checksums
Using CRC
One engine, 113 named standards (CRC-1 through CRC-64), custom parameter sets, shared lookup-table cache.
CRC catalogue
Reference table of every named CRC standard - name, width, polynomial, init, reflect, XOR-out.
Using Fletcher
Twin-accumulator checksums in 16-, 32-, and 64-bit widths.
Using Adler
Adler-32 (zlib), Adler-32C (SIMD), Adler-64.
Bodu.IO.Hashing.CheckDigits
Check digits overview
Luhn, Damm, Verhoeff, EAN, GTIN, ISIN, IBAN, ISBN, SEDOL, CUSIP, ABA routing, LEI - single- and multi-character validators for human-typed identifiers.
Bodu.Security.Cryptography
Cryptographic primitives with a formal adversary model - block ciphers, stream ciphers, AEAD constructions, keyed and unkeyed hashes - derived from the standard BCL base classes (SymmetricAlgorithm, HashAlgorithm).
Overview
Namespace map and selection table for cipher, hash, and AEAD families.
Foundations
Encryption basics
Key, IV, Tweak, BlockMode, Padding - the mental model every cipher in the library follows.
Cipher block modes
ECB, CBC, CFB, OFB, CTR - one worked round-trip per mode.
Padding
PKCS7, Zeros, None, ISO 10126, ISO 7816-4, ANSI X9.23 - how each one pads and when it round-trips cleanly.
Composing primitives
IBlockCipher + BlockCipherModeFactory + PaddingFactory vs the SymmetricAlgorithm wrappers.
Symmetric ciphers - Standard
Using Skipjack
NSA design (declassified 1998); legacy interoperability only.
Using Blowfish
Schneier 1993; 64-bit block; expensive key schedule.
Camellia, Twofish, and Serpent128 follow the same SymmetricAlgorithm lifecycle - see the Bodu.Security.Cryptography API reference for their parameters.
Symmetric ciphers - Tweakable
Using Threefish-256
Smallest Threefish variant; 256-bit block, 256-bit key, 128-bit tweak.
Using Threefish-512
Recommended general-purpose Threefish variant; 512-bit block, 512-bit key, 128-bit tweak.
Using Threefish-1024
Highest Threefish security margin; 1024-bit block, 1024-bit key, 128-bit tweak.
Serpent256 / Serpent512 / Serpent1024 are wide-block tweakable Serpent constructions - non-standard, see the API reference for their parameters.
Symmetric ciphers - Stream
Using stream ciphers
ChaCha20, XChaCha20, Salsa20, XSalsa20, Rabbit, HC-128 - raw XOR keystream ciphers (no block, no padding). Confidentiality only; pair with a MAC or prefer AEAD.
Symmetric ciphers - AEAD
AEAD modes
GCM, CCM, OCB, EAX, SIV, GCM-SIV - authenticated encryption using AesBlockCipher + a mode transform.
Cryptographic hashes
Hashing overview
Cross-cutting overview of keyed hashes, cryptographic digests, and Merkle trees.
Using Tiger
128 / 160 / 192-bit cryptographic digest optimized for 64-bit platforms.
Using CubeHash
SHA-3 finalist with tunable rounds and block size.
Using Snefru
Legacy cryptographic digest; interop only (cryptanalytically broken).
Merkle trees and proofs
The RFC 6962 tree over any inner HashAlgorithm - roots over entries, blocks, or a write-time accumulator; inclusion and consistency proofs; length-bound roots.
Whirlpool, Blake2b, Blake2s, Blake3, Skein256 / Skein512 / Skein1024, and Shake ship without dedicated walk-throughs - consult the API reference directly.
Keyed hashes (MAC)
Using SipHash
SipHash-64 / SipHash-128 - keyed PRF for hash-flooding-resistant tables.
Using Poly1305
One-time authenticator (RFC 8439); pair with ChaCha20 or AES-CTR.
ASCON family
ASCON overview
All five NIST SP 800-232 types with selection guidance.
ASCON hashing
AsconHash256 and AsconHashA256.
ASCON XOF
AsconXof128 and AsconCxof128.
ASCON AEAD
AsconAead128 - sponge-based authenticated encryption.
Bodu.Security.Cryptography API reference
Globalization & Calendars
The notable-date runtime, its companions, and the regional data packs - see the Globalization & Calendars guides landing for the full map including the notable-date catalogue.
Bodu.Globalization.Calendar
Rule-driven notable-date (public holiday, observance, festival) resolution for any year, territory, or calendar system.
Overview
Resolution pipeline, namespace map, and key-type table.
Using NotableDateService
Resolving for a year, filtering by territory and category, layering overrides.
Authoring notable-date rules
In-code, embedded XML / JSON, companion assemblies, runtime overrides.
Date calculation algorithms
Built-in algorithms (Easter, Hindu Lunar, Losar, Vesak, Asalha Puja, Qingming) and custom-algorithm walk-through.
Calendar data packs
Official Americas / Europe / Asia-Pacific companion assemblies.
Bodu.Globalization.Calendar API reference
Text & Serialization
Binary-to-text codecs, document formats, and object serializers - see the Text & Serialization guides landing for the disambiguation between the three jobs.
Bodu.Text.Encoding
Binary-to-text encoders for Base16, Base32, Base64, Base58, and Base85 with every common
variant - span- and UTF-8-friendly, OperationStatus-aware, with a unified IBinaryEncoding interface for
runtime-pluggable encoding choice.
Overview
The encoding family, payload-expansion comparison, and the choose-an-encoding decision table.
Using Base16 (hexadecimal)
Formatting decorations (case / prefix / spacing / line breaks), lenient parsing, hex dumps, BCL aliases.
Using Base32
Standard / HexExtended / Crockford / Z-Base-32 variants, TOTP secrets, padding control.
Using Base64
Standard / URL-safe / MIME variants, JWT decoding, 76-character line wrapping.
Using Base58
Bitcoin / Flickr / Ripple alphabets, leading-zero preservation, address decoding.
Using Base85 (Ascii85 and Z85)
Adobe Ascii85 with the z shortcut and partial-group rules; ZeroMQ Z85 with shell-safe alphabet.
The IBinaryEncoding interface
Runtime-selected encoding choice via BinaryEncodings.Get(name) and the IBinaryEncoding contract.
Bodu.Text.Filtering
Include/exclude filtering for lists of text values - glob and regex patterns compiled once into a
cost-tiered TextFilter, with Ant / MSBuild set semantics or gitignore-style ordered rules and
built-in match telemetry.
Overview
How the engine works - compile-once filters, cost-tier classification, and the guide map.
Patterns and globs
The full glob grammar - classes, {a,b} alternation, escapes - and when to reach for regex.
Evaluation modes
AnyMatch sets vs LastMatchWins ordered rules, allowlists, gitignore-convention parsing.
Telemetry and tuning
Statistics, per-pattern hit counts, the observer hook, cost tiers, fail-safe regex timeouts.
Bodu.Text.Formats (Delimited · DotEnv · INI)
The line-oriented text formats - Bodu.Text.Delimited, Bodu.Text.DotEnv, and Bodu.Text.Ini, each a
standalone System.Text.Json-shaped library (token reader/writer, serializer, mutable and read-only DOMs)
reachable through the Bodu.Text.Formats umbrella package.
Overview
Namespace map and where each guide fits.
Using delimited (CSV / TSV)
RFC 4180 quoting, delimiter selection, header handling, the streaming Utf8DelimitedReader / Utf8DelimitedWriter, typed records via DelimitedSerializer, and the dialect policies on DelimitedReaderOptions.
Using DotEnv
KEY=VALUE parsing, quoting and escape rules, the export prefix, and typed settings via DotEnvSerializer.
Using INI
Hoisted globals and section objects, typed binding via IniSerializer, duplicate-section and duplicate-key policies, and comment-preserving mutation through the IniNode DOM.
Streams and async I/O
The forward-only Utf8*Reader / Utf8*Writer token surfaces, the typed record-streaming serializer overloads, and the lifetime and mid-stream error contracts.
Bodu.Text.Bencode, Bodu.Text.Toml, and Bodu.Text.Yaml (serializers)
Three self-contained serializers that map your own types to and from a format.
They share an architecture and a System.Text.Json-aligned shape - what you learn
for one transfers to the next - and each has its own guide set.
Overview
The three libraries, the shared tiers (serializer, DOMs, reader/writer), and how to choose a format.
TOML guides
TomlSerializer, the type mapping, spec-version selection, both DOMs, converters, callbacks, and the built-in catalog.
Bencode guides
BencodeSerializer, byte strings, canonical key ordering, both DOMs, and the kinds Bencode cannot represent.
YAML guides
YamlSerializer, the 1.2 core schema, both DOMs, multi-document streams, [Yaml…] attributes, and custom converters.
Configuration
Layered, EditorConfig-style configuration and its Microsoft.Extensions.Configuration bridge - see the Configuration guides landing.
Bodu.Text.Configuration
Parse a configuration document under one of the four profiles, resolve it for a target path, and read typed values back out.
Overview
Namespace map, the parse → resolve → view pipeline, and where each guide fits.
Parsing and profiles
ConfigurationDocument.Parse, ConfigurationParseOptions, and the four profile presets - inline comments, duplicate handling, length limits.
Views and resolution
Resolve → ConfigurationView: glob matching against a target path, key projection, typed getters, missing-key fallbacks.
Diagnostics
The structured diagnostic surface - modes, severities, and the full ConfigurationDiagnosticCode catalogue.
Bodu.Text.Configuration API reference
Bodu.Extensions.Configuration.Text
Surface a parsed and resolved document through the standard IConfiguration pipeline that ASP.NET Core and Generic Host already consume.
Overview
Namespace map - builder extensions, file and stream sources and providers, DI options helpers.
Configuration sources
AddTextConfigurationFile / AddTextConfigurationStream, the conventional file probe, reload-on-change, target-path anchoring, and IOptions<T> binding.
Bodu.Extensions.Configuration.Text API reference
Numerics & Financial
Exact arithmetic and the monetary primitives built on it - see the Numerics & Financial guides landing.
Bodu.Numerics
Generic-math value primitives - exact rational arithmetic and bounded intervals.
Overview
The two value types, their generic-math surfaces, and where each guide fits.
Working with Fraction<T>
Canonical form, GCD reduction, BigInteger promotion, the INumber<T> surface, approximation.
Formatting and parsing
Format specifiers, mixed numbers, vulgar fractions, culture handling, parse shapes.
Working with Interval<T>
Closed / open / half-open bounds, containment, intersection, union, adjacency.
JSON serialization
The System.Text.Json converters, wire shapes, and round-tripping Fraction<BigInteger>.
Bodu.Financial
Type-safe money, the ISO 4217 currency catalogue, exchange rates, allocation, and cash rounding.
Overview
The money types, the currency catalogue, and where each guide fits.
Working with Money<TCurrency>
Compile-time currency safety, arithmetic, allocation, rounding, and the runtime Money form.
Working with exchange rates
ExchangeRate and ExchangeRate<TBase, TQuote> - conversion, inversion, composition.
Exchange-rate lookups
Dated providers, lookup results, provenance, and fallback stacks over a worked dataset.
Dependency injection
AddFinancialService - registering currency lookup, monetary contexts, and rate providers.
Binary Formats & I/O
Legacy binary container and document formats - a read/edit/author compound-file container with narrower read-only format readers on top; see the Binary Formats & I/O guides landing.
Bodu.IO.Compound
A reader, editor, and writer for the OLE2 / Compound File Binary (CFB) container - the structured-storage "file system in a file" used by legacy Office documents (.xls, .doc, .ppt, .msg). It navigates the storage hierarchy, reads the raw byte payload of each named stream, edits and authors containers with a transactional Commit / CommitAsync, and reads and writes the OLE property sets, all with no application-format knowledge.
Overview
Namespace map (Bodu.IO.Compound, .PropertySets), the storage-hierarchy mental model, and where each guide fits.
Reading compound files
Open a file, probe the signature, walk the hierarchy with the enumerate and TryOpen surfaces, and read a named stream's bytes.
Buffered vs streaming access
The buffered flag, the CompoundStream cursor, AsMemory vs chunked Read, and bounding memory for large files.
Reading property sets
The SummaryInformation / DocumentSummaryInformation metadata streams, the raw OlePropertySet, and the TryGet* convenience methods.
Bodu.IO.Compound API reference
Bodu.Formats.Excel.Binary
A narrow, read-only BIFF8 (.xls) reader built on Bodu.IO.Compound. It surfaces the raw cell values of each worksheet - strings, numbers, booleans, and errors, including a formula cell's cached result - without formula evaluation, styling, or higher-level interpretation.
Overview
Namespace map (Bodu.Formats.Excel), the layered BIFF8-on-compound-file model, and where each guide fits.
Reading workbooks
Open an .xls from a path or stream, list the sheets and used ranges, control ownership and optional work, and read document properties.
Cell values and dates
The ExcelCell kinds and value projections, a formula's cached result, date-format detection, serial-date conversion, and A1 references.
Streaming vs materialized
The forward-only ExcelWorksheetReader versus the randomly addressable ExcelWorksheet - when to reach for each, and how to bound allocation.