Library guides

These guides start with the job you need to do and then explain which part of CStructSharp fits that job. You don't need to understand compiler construction or native memory layout before you begin.

If this is your first binary-format library, follow the learning path: nine steps, one page each, from what a layout is to the reference material, plus four examples worth reading first. Its first steps are:

1. Binary layout basics explains bytes, offsets, byte order, padding, and the role of a CStruct.
2. Install and make a first parse turns a six-byte header into C# values. Continue with writing, updating, and a complete C# class.
3. Read values and paths shows how to read either a whole object or one nested field; typed values maps a layout to a C# class; choose an API compares stream, span, memory, and output overloads; trimming and Native AOT covers a trimmed or AOT-published application (how mapped classes stay reflection-free, and why dynamic is JIT-only).
4. Write and serialize values creates new binary data, and update existing data changes one field without rebuilding the surrounding object.

When the layout is part of your program's source, the generated code series turns it into typed C# classes at build time - Parse into properties, Serialize from them, allocation-free views, typed setters - with the same rules and the same failure texts as the runtime; runtime or generated? is the decision table.

The data-shape guides cover strings, enums, unions, pointers, conditional fields (with per-item decisions, variable scope, and browser exercises), and the binary metadata types. The operational guides cover errors (including the common-mistakes checklist), runtime variables and limits, performance (including layout reuse and ownership), spans and buffer writers, and byte ranges and addresses. The binary file walkthrough combines the concepts in a larger task.

For JavaScript, take the separate Node.js and browser quick start; the JavaScript API covers browser results, debug ranges, and compiled-layout reuse. Use the glossary when a term is new.

For a deeper foundation, read how C structs occupy memory and memory addresses and stored data. These explain alignment calculations, native C arrays and pointers, platform ABIs, byte order, and text encodings, with exercises and worked answers. They assume introductory programming knowledge, not operating-systems or compiler courses.

For captured or mapped memory, follow the memory-analysis guide series. It covers sources, metadata layouts, pointers, bounded traversal, offline editing, and reliability through executable byte-level examples.

Use the tested recipes when you already know the result you want. Use the layout-language manual when you need to choose syntax or predict exact byte positions.