Class MetadataDecoder

Namespace

DatabentoDotNet.Dbn

Assembly

DatabentoDotNet.Dbn.dll

Decodes the Metadata block that opens a DBN stream.

public static class MetadataDecoder

Inheritance

object

MetadataDecoder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The primitive takes a span, not a stream. The incremental decoder reaches its metadata state holding a buffer it has already filled from the socket; handing it only a Stream API would force it to copy those bytes back out through a stream shim for no reason. Decode(ReadOnlySpan<byte>, VersionUpgradePolicy) is therefore the real entry point and Decode(Stream, VersionUpgradePolicy) is a convenience over it.

Two steps, because the length is inside the bytes. A reader cannot know how many bytes the metadata occupies until it has read the 8-byte prelude, so DecodePrelude(ReadOnlySpan<byte>, out byte, out int) and DecodeAfterPrelude(ReadOnlySpan<byte>, byte, VersionUpgradePolicy) are exposed separately: read 8 bytes, learn the length, wait for that many more, then decode. The combined Decode overloads are for callers that already hold the whole block.

Every multi-byte field is little-endian, and this decoder reads each one explicitly through BinaryPrimitives rather than reinterpreting the header as a struct. The header is not a fixed layout across versions, so there is no struct to reinterpret.

Methods

Decode(Stream, VersionUpgradePolicy)

Reads and decodes a metadata block from the current position of source, leaving the stream positioned on the first record.

public static Metadata Decode(Stream source, VersionUpgradePolicy upgradePolicy = VersionUpgradePolicy.UpgradeToV3)

Parameters

source Stream

A readable stream positioned at the DBN magic.

upgradePolicy VersionUpgradePolicy

How to present data from an older DBN version.

Returns

Metadata

The decoded metadata.

Remarks

A convenience over the span form for callers that already hold a stream — a file, say. It buffers the block, because the block's own length is only known after the prelude, and decoding needs it contiguous. It buffers it incrementally, for the reasons set out on ReadBody(Stream, int): the prelude's length is not trusted to size an allocation.

Exceptions

ArgumentNullException

source is null.

DbnDecodeException

The stream ends early, or its bytes are not valid DBN metadata.

Decode(ReadOnlySpan<byte>, VersionUpgradePolicy)

Decodes a complete metadata block — prelude included — from the start of source.

public static Metadata Decode(ReadOnlySpan<byte> source, VersionUpgradePolicy upgradePolicy = VersionUpgradePolicy.UpgradeToV3)

Parameters

source ReadOnlySpan<byte>

The stream's bytes from the magic onwards. Anything past the metadata block is ignored, so passing a whole file is fine.

upgradePolicy VersionUpgradePolicy

How to present data from an older DBN version. The default matches upstream's default and reports every stream as version 3.

Returns

Metadata

The decoded metadata.

Exceptions

DbnDecodeException

The bytes are not valid DBN metadata.

DecodeAfterPrelude(ReadOnlySpan<byte>, byte, VersionUpgradePolicy)

Decodes a metadata block whose prelude has already been read and consumed.

public static Metadata DecodeAfterPrelude(ReadOnlySpan<byte> body, byte version, VersionUpgradePolicy upgradePolicy = VersionUpgradePolicy.UpgradeToV3)

Parameters

body ReadOnlySpan<byte>

Exactly the bytes the prelude's length field counted: the fixed section, the variable section, and any version-3 end padding.

version byte

The version byte from the prelude.

upgradePolicy VersionUpgradePolicy

How to present data from an older DBN version.

Returns

Metadata

The decoded metadata.

Exceptions

DbnDecodeException

The bytes are not valid DBN metadata.

DecodePrelude(ReadOnlySpan<byte>, out byte, out int)

Reads the 8-byte prelude: the magic string, the DBN version, and the byte length of the metadata that follows it.

public static void DecodePrelude(ReadOnlySpan<byte> source, out byte version, out int length)

Parameters

source ReadOnlySpan<byte>

At least MetadataPreludeLength bytes, starting at the magic.

version byte

Receives the DBN version byte.

length int

Receives the length in bytes of the metadata block following the prelude.

Remarks

length excludes these 8 bytes. It counts the fixed section plus the variable section (plus any version-3 end padding), so the first record begins at MetadataPreludeLength + length. Treating it as the total instead shifts every record in the stream by 8 bytes, which does not fail loudly — it decodes garbage.

Exceptions

DbnDecodeException

source is too short, does not start with the DBN magic, states a version this library cannot decode, or states a length outside MetadataFixedLength..MaxMetadataLength.