Quick Reference

Chapter 11 - Quick lookup for SDDL syntax and features

This reference provides a quick lookup for SDDL syntax, types, operators, and functions. For detailed explanations and examples, follow the chapter links.

Type Reference

Primitive Integer Types

Type	Size	Signed	Endian	Chapter
`Int8`	1 byte	Yes	N/A	Core Concepts
`Int16LE`, `Int16BE`	2 bytes	Yes	Little/Big	Core Concepts
`Int32LE`, `Int32BE`	4 bytes	Yes	Little/Big	Core Concepts
`Int64LE`, `Int64BE`	8 bytes	Yes	Little/Big	Core Concepts
`UInt8`	1 byte	No	N/A	Core Concepts
`UInt16LE`, `UInt16BE`	2 bytes	No	Little/Big	Core Concepts
`UInt32LE`, `UInt32BE`	4 bytes	No	Little/Big	Core Concepts
`UInt64LE`, `UInt64BE`	8 bytes	No	Little/Big	Core Concepts

Note: All multi-byte types must explicitly specify endianness (LE or BE).

Floating-Point Types

Type	Size	Format	Endian	Chapter
`Float16LE`, `Float16BE`	2 bytes	IEEE 754	Little/Big	Core Concepts
`Float32LE`, `Float32BE`	4 bytes	IEEE 754	Little/Big	Core Concepts
`Float64LE`, `Float64BE`	8 bytes	IEEE 754	Little/Big	Core Concepts
`BFloat16LE`, `BFloat16BE`	2 bytes	Google bfloat16	Little/Big	Core Concepts

Raw Bytes

Type	Description	Chapter
`Bytes(n)`	Fixed-size byte array of length `n`	Core Concepts
`Bytes until delim`	Variable-size bytes until delimiter	Core Concepts

Syntax Quick Reference

Records

Record TypeName(param1, param2) = {
  field1: Type1,
  field2: Type2(param1)
} pad_to size pad_align boundary

See: Core Concepts - Records

Unions

Union TypeName(selector, param) = {
  case 1: Type1(param),
  case 2, 3: Type2(param),
  case 4..10: Type3(param),
  default: Type4(param)
}

See: Conditional & Variant Data - Unions

Enumerations

enum EnumName {
  VALUE1 = 1,
  VALUE2 = 2,
  VALUE3 = 1 << 2
}

See: Conditional & Variant Data - Enumerations

Conditional Fields

Single field:

when condition { field: Type }

Block form:

when condition {
  field1: Type1,
  field2: Type2,
  var x = field1 + field2
}

See: Conditional & Variant Data - Conditional Fields

Arrays

fixed: Type[count]                    # Fixed-size
multi: Type[height][width]            # Multi-dimensional
auto: Type[]                          # Auto-sized (to end of scope)
soa_array: soa Type[count]            # Structure-of-arrays

See: Arrays & Collections

Variables

var name = expression

See: Variables & Expressions

Validation

expect condition                      # Standalone validation
field: Type where (condition)         # Inline validation

See: Variables & Expressions

Switch Expressions

var value = switch selector {
  case 1: result1,
  case 2, 3: result2,
  case 4..10: result3,
  default: result4
}

Rules:

All cases must return the same type
Overlapping ranges cause a format error
No match without default causes a data error

See: Variables & Expressions - Switch Expressions

Operator Reference

Arithmetic Operators

Operator	Description	Example	Chapter
`+`	Addition	`a + b`	Variables & Expressions
`-`	Subtraction	`a - b`	Variables & Expressions
`*`	Multiplication	`a * b`	Variables & Expressions
`/`	Division	`a / b`	Variables & Expressions
`%`	Modulo	`a % b`	Variables & Expressions

Note: All arithmetic is 64-bit signed. Overflow or division by zero causes a format error.

Bitwise Operators

Operator	Description	Example	Chapter
`&`	Bitwise AND	`flags & 0x01`	Variables & Expressions
`\\|`	Bitwise OR	`a \\| b`	Variables & Expressions
`^`	Bitwise XOR	`a ^ b`	Variables & Expressions
`<<`	Left shift	`value << 8`	Variables & Expressions
`>>`	Right shift	`value >> 8`	Variables & Expressions

Comparison Operators

Operator	Description	Example	Chapter
`==`	Equal	`a == b`	Variables & Expressions
`!=`	Not equal	`a != b`	Variables & Expressions
`<`	Less than	`a < b`	Variables & Expressions
`<=`	Less or equal	`a <= b`	Variables & Expressions
`>`	Greater than	`a > b`	Variables & Expressions
`>=`	Greater or equal	`a >= b`	Variables & Expressions
`in`	Enum membership	`value in EnumType`	Conditional & Variant Data

Logical Operators

Operator	Description	Example	Chapter
`and`	Logical AND	`a and b`	Variables & Expressions
`or`	Logical OR	`a or b`	Variables & Expressions
`not`	Logical NOT	`not a`	Variables & Expressions

Operator Precedence

SDDL follows C11 operator precedence. Use parentheses for clarity.

See: Variables & Expressions - Operator Precedence

Function Reference

Mathematical Functions

Function	Description	Returns	Chapter
`abs(x)`	Absolute value of x	64-bit signed int	Variables & Expressions
`min(a, b)`	Minimum of a and b	64-bit signed int	Variables & Expressions
`max(a, b)`	Maximum of a and b	64-bit signed int	Variables & Expressions
`clamp(l, x, h)`	Clamp x to range [l, h]	64-bit signed int	Variables & Expressions
`sgn(x)`	Sign of x (-1, 0, or 1)	64-bit signed int	Variables & Expressions
`between(l, x, h)`	True if l ≤ x ≤ h	Boolean (0 or 1)	Variables & Expressions

Alignment and Division

Function	Description	Returns	Chapter
`ceil_div(x, d)`	Ceiling division ⌈x / d⌉	64-bit signed int	Variables & Expressions
`align_up(x, a)`	Round x up to multiple of a	64-bit signed int	Variables & Expressions

Size and Position Functions

Function	Description	Instant-Parse?	Chapter
`sizeof(T())`	Static size of type T	Yes	Variables & Expressions
`parsed_length(field)`	Parsed byte size of field	No (requires scan)	Variables & Expressions
`current_position()`	Current parser position	No (requires scan)	Variables & Expressions
`scope_remaining()`	Bytes remaining in scope	No (requires scan)	Variables & Expressions

Padding and Alignment

Record-Level Modifiers

Modifier	Description	Chapter
`pad_to n`	Extend record to exactly n bytes	Alignment & Padding
`pad_align n`	Round record size up to multiple of n	Alignment & Padding

Both can be combined: pad_to is applied first, then pad_align.

Field-Level Alignment

aligned_field: align(16) Type

See: Alignment & Padding - Field Alignment

Annotations

Annotation	Purpose	Chapter
`@instant_parse`	Enforce instant-parse requirement	Instant-Parse Model
`@err_msg "text"`	Custom error message for validation	Best Practices
`@chunk_size`	Hint for chunk processing	sddl-for-llm

See: sddl-for-llm - Annotations

Instant-Parse Model

A type is instant-parse if all field offsets and sizes can be computed from parameters and constants alone (no dependency on parsed data).

What Breaks Instant-Parse

Field size/offset depends on previously parsed field
Using Bytes until (delimiter-based parsing)
expect or where referencing local fields
Using current_position() or state-dependent functions
Auto-sized arrays (Type[])

Instant-Parse Rules

Construct	Instant-Parse When...
Record	All fields are instant-parse and no local field dependencies
Union	Selector is parameter/constant AND all cases are instant-parse
Array	Size is parameter/constant AND element type is instant-parse
Variable	References only parameters/constants
Conditional	Condition uses only parameters/constants

See: Instant-Parse Model

Common Patterns

Magic Number Validation

magic: Bytes(4)
expect magic == "RIFF"

See: Real-World Formats - Common Patterns

Length-Prefixed Data

length: UInt32LE
data: Bytes(length)

Flag Extraction

flags: UInt8
var has_feature = (flags & 0x01) != 0
when has_feature { feature_data: FeatureData }

See: Variables & Expressions - Flag Extraction

Version-Based Layout

version: UInt16LE
when version >= 2 { extended_fields: ExtendedData }

See: Conditional & Variant Data - Version-Specific Fields

Array Size Computation

width: UInt32LE
height: UInt32LE
var num_pixels = width * height
pixels: Pixel[num_pixels]

See: Variables & Expressions - Computing Array Sizes

Error Types

Error Type	When It Occurs	Example
Format Error	Structural contradiction	Overlapping union cases, `pad_to` too small, overflow
Data Error	Data doesn't match expected structure	Failed `expect`, missing delimiter, unmatched union case
Instant-Parse Violation	`@instant_parse` requirement not met	Field depends on parsed data

See: sddl-for-llm - Error Classes

Keywords

Reserved: Record, Union, enum, when, then, case, default, var, expect, where, scan, soa, align, pad_to, pad_align, until, include_delim, switch, and, or, not, in

See: Getting Started - Basic Syntax

Complete Documentation

For comprehensive learning and detailed explanations:

Introduction - What is SDDL and why use it?
Getting Started - Your first SDDL description
Core Concepts - Types, records, and basic structures
Arrays & Collections - Working with arrays
Instant-Parse Model - Performance and layout
Alignment & Padding - Memory layout control
Conditional & Variant Data - Unions and conditionals
Variables & Expressions - Computing values
Best Practices - Guidelines for effective SDDL
Real-World Formats - Complete examples (WAV, BMP)
sddl-for-llm - Complete technical specification