Feature Matrix
Scannable map of capabilities. Use the More links for samples and tests.
| Feature | What it does | How to use / more |
|---|---|---|
build.rs codegen | Compile-time schema → Rust module in OUT_DIR | generate_to_out_dir("schemas/….xml", config)? · plain include! or sbe_mod!(name) · Quick start · codegen examples |
| Wire compatibility | Same on-wire layout as official SBE | Dual encode ergo vs sbe-tool · sbe_tool_wire_parity_test · golden fixtures · Benchmarks · baseline_test |
| Flyweight decode | Zero-copy over &[u8] | CarDecoder::try_from(buf)?; car.serial_number() · feature-tour |
| Composite wire image | #[repr(transparent)] Engine([u8; N]) + LE accessors; flyweight default | Not a repr(C) overlay · Core ideas · composite_layout_test |
| Per-field vs whole struct | Flyweight or *FixedFields / *Domain | Single field: flyweight · always fill fixed block: .fixed(&CarFixedFields { … }) · whole message owned: CarDomain · Core ideas · feature-tour |
| Stage-struct encode + closures | Wire order as named monomorphic stages; groups via nested closures | bids(n, |g| g.add(|e| …))? · wrong order = missing method · Core ideas · Recipes · Benchmarks |
| Consuming decode stages | Distinct after-stage decoder types | into_bids()? → next named stage · ordered_decoder_stages_test · l3_consuming_stages_test |
| Three-tier constructors (0.1.12+) | try_* → Result; bare wrap/decode panic if short; unsafe *_unchecked | CarDecoder::try_decode(buf, 0)? · CarDecoder::verify(buf)? · demo_try_vs_trusted · Trust boundary |
| Placement metadata | Buffer utils on get_metadata() so field names remaining / buffer / limit / message_offset stay natural (no _field rename) | dec.get_metadata().remaining() · schema field remaining → dec.remaining() · Generated code · reserved_name_clash_test |
| Exact buffer sizing | Schema-aware length for nested/ragged msgs — no hand-calculated sizes | compute_length_with_header() (fixed) · compute_length_with_header(…) (flat) · *EncodedLength (nested) · Core ideas · l3-book · encoded_length_api_test |
| Schema docs → rustdoc | XML descriptions become item docs | description="…" / <description> / <comment> / <!-- --> · schema_docs_provenance_test |
Display / Debug | Diagnostic print (not wire format) | println!("{car}"); · Display / Debug · demo_display_debug |
| NULL / MIN / MAX | Schema sentinels as consts | MODEL_YEAR_NULL · baseline_test |
| Version-aware fields | sinceVersion / acting version | Option or skip on older wire · baseline_test · multi_schema_versioning_test |
| Groups / nested groups | Repeating dimensions | bids(n, |g| g.add(…))? · l3-book · l3_orderbook_test |
| Bulk group encode / decode | bulk_add(&[Entry]) / bulk_add_domain(&[EntryDomain]) / bulk_decode() -> Vec<Entry> for eligible flat groups | Wire bulk_add: about 22-23% lower encode latency than per-entry add() for the audited 1,000-entry cases. DTO re-encode selects the domain bulk path automatically when wire and domain fields match; remeasure for your schema · group_encode_bench |
| Var-data / text | Length-prefix; optional UTF-8/ASCII | manufacturer(b"Honda")? · *_as_str when encoding set · feature-tour |
| Fixed arrays + bulk helpers | Arrays, put, pad string, copy-out | put_some_numbers(…) · vehicle_code_str · copy_vehicle_code · java_parity_features_test |
| Enums / sets / bool | Wire enums, bitsets, _bool | available() / available_bool(true) · comprehensive_test |
with_conversion | Wire type → any app type you impl | price_from(&Cents)? / price_as::<Cents>()? · Configuration · exchange-example |
with_domain_type | Wire type → one fixed Rust path | enc.try_price(d)?; let d = dec.try_price()? · l3-book · Configuration |
| Domain DTOs | Owned structs + re-encode; allocation-free automatic bulk write for eligible flat groups; var-data via [DomainVarData] | .with_domain_objects(DomainVarData::Strings) · Domain DTOs · domain_objects_test |
AnyMessage + frames | Multi-template + framed streams | AnyMessage::try_decode (bare decode is the same path today) · FrameCursor · demo_any_message |
verify | Full tail bounds check (associated) | CarDecoder::verify(buf)? · demo_try_vs_trusted |
| Schema identity | Id / version / hashes | SCHEMA_ID, SCHEMA_HASH, SCHEMA_SHA256_HEX · generated module header |
| Multi-schema shared types | Dedup across packages | .with_shared_module + generate_multi · exchange-example · multi_schema_versioning_test |
| Keyword-safe names | type → type_ | .with_keyword_append_token("_") · java_parity_features_test |
| XSD-shaped validation | Opt-in stricter check for schema authors | validate_against_sbe_xsd / parse_with_xsd_validation · xsd.rs |
| Zero-alloc hot path | Flyweights + caller buffers | allocation_count_test · Benchmarks |
| Property round-trip | Random messages encode→decode | cargo test -p ergo-sbe --test proptest_roundtrip · proptest_roundtrip |
NullVal → Option<T> | Enum/boolean NullVal mapped to Option; wire-identical | .with_null_as_option(ConversionSelector::named_type("EventCode")) or .with_all_enums_as_option() — dec.code() -> Option<EventCode> · NullVal design note |
| Domain var-data types | CompactString (≤24B inline), SmolStr (O(1) clone), bytes::Bytes (shared) | .with_domain_objects(DomainVarData::CompactStrings) — feature-gated: compact_str, smol_str, bytes · Feature integrations |
| Codec-level type accessors | into_<field>_as_compact_str() / _as_smol_str() / _as_bytes() on consuming stages | Feature-gated behind compact_str, smol_str, bytes · Feature integrations |
| Chrono timestamps | DateTime<Utc> / NaiveDateTime from wire i64 | .with_domain_type(ConversionSelector::semantic_type("UTCTimestamp"), "chrono::DateTime<chrono::Utc>") — feature-gated: chrono · Timestamps |
| Lean constructor | GenerationConfig::lean("minimal") — no Display/Debug/dispatch, explicit settings preserved | lean() shorthand for new().profile(Lean) · GenerationConfig |
| Must-use lifecycle | #[must_use] on SessionBuilder, AsyncClusterConnect, ClusterClaim | Compile-time guard against discarded builder/connect/claim · SessionBuilder |
| PayloadTooLarge | Typed error when header+payload exceeds Aeron max | ClusterError::PayloadTooLarge { operation, requested, maximum } · Cluster client |
| Zero-alloc offer_parts | Fragmented path uses offer_parts gather — no heap, no payload copy | Stack header + borrowed payload · Cluster client |
| checked_deadline | Fallible deadline: rejects zero/overflow | ClusterError::InvalidTimeout · Cluster client |