BencodeDocument Class

Definition

Namespace

Bodu.Text.Bencode.Document

Assembly

Bodu.Text.Bencode.dll

Package

Bodu.Text.Bencode 1.0.0

Source

BencodeDocument.Row.cs

Provides a read-only, high-performance document object model over Bencode (BEP 3) bytes. The source is parsed once into a flat metadata index and exposed through lightweight BencodeElement struct views; no node tree is materialized.

public sealed class BencodeDocument : IDisposable

Inheritance

object

BencodeDocument

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Remarks

A BencodeDocument owns a buffer rented from Shared that holds a copy of the parsed bytes, together with a flat array of row records describing the document structure. Because byte-string elements reference that buffer directly, every BencodeElement, enumerator, and BencodeProperty obtained from a document is valid only until the document is disposed.

Call Dispose() when finished to return the rented buffer to the pool. After disposal, any operation on an element belonging to the document throws ObjectDisposedException.

// Dispose returns the pooled buffer; elements are valid only until then.
using BencodeDocument doc = BencodeDocument.Parse("d3:cowi42ee"u8);

BencodeElement root = doc.RootElement;
long age = root.GetProperty("cow").GetInt64();   // 42

Properties

RootElement

Gets the root element of the document.

public BencodeElement RootElement { get; }

Property Value

BencodeElement

A BencodeElement positioned on the document's single root value.

Methods

Dispose()

Returns the rented buffer to Shared and invalidates the document.

public void Dispose()

Remarks

Disposal is idempotent: calling it more than once has no further effect. After disposal, every element, enumerator, and property obtained from the document throws ObjectDisposedException. For the non-pooled documents that back Clone() results, disposal is a no-op and the document remains usable.

Parse(byte[])

Parses the supplied Bencode bytes into a BencodeDocument.

public static BencodeDocument Parse(byte[] data)

Parameters

data byte[]

The Bencode source bytes.

Returns

BencodeDocument

A document over a private copy of data.

Exceptions

ArgumentNullException

Thrown when data is null.

BencodeFormatException

Thrown when the bytes are not a single, canonical Bencode value.

Parse(byte[], BencodeDocumentOptions)

Parses the supplied Bencode bytes into a BencodeDocument using the supplied options.

public static BencodeDocument Parse(byte[] data, BencodeDocumentOptions options)

Parameters

data byte[]

The Bencode source bytes.

options BencodeDocumentOptions

The document options controlling the maximum nesting depth.

Returns

BencodeDocument

A document over a private copy of data.

Remarks

A MaxDepth of zero or less selects the default maximum depth of 64, and a larger value is clamped to Bodu.Text.Bencode.BencodeLimits.AbsoluteMaxDepth; a document nested deeper than the effective limit throws BencodeFormatException.

Exceptions

ArgumentNullException

Thrown when data is null.

BencodeFormatException

Thrown when the bytes are not a single, canonical Bencode value, or nest deeper than the configured maximum.

Parse(ReadOnlySpan<byte>)

Parses the supplied Bencode bytes into a BencodeDocument.

public static BencodeDocument Parse(ReadOnlySpan<byte> data)

Parameters

data ReadOnlySpan<byte>

The Bencode source bytes.

Returns

BencodeDocument

A document over a private copy of data.

Exceptions

BencodeFormatException

Thrown when the bytes are not a single, canonical Bencode value.

Parse(ReadOnlySpan<byte>, BencodeDocumentOptions)

Parses the supplied Bencode bytes into a BencodeDocument using the supplied options.

public static BencodeDocument Parse(ReadOnlySpan<byte> data, BencodeDocumentOptions options)

Parameters

data ReadOnlySpan<byte>

The Bencode source bytes.

options BencodeDocumentOptions

The document options controlling the maximum nesting depth.

Returns

BencodeDocument

A document over a private copy of data.

Remarks

A MaxDepth of zero or less selects the default maximum depth of 64, and a larger value is clamped to Bodu.Text.Bencode.BencodeLimits.AbsoluteMaxDepth; a document nested deeper than the effective limit throws BencodeFormatException.

Exceptions

BencodeFormatException

Thrown when the bytes are not a single, canonical Bencode value, or nest deeper than the configured maximum.

WriteTo(Utf8BencodeWriter)

Writes the document's root value to the supplied writer.

public void WriteTo(Utf8BencodeWriter writer)

Parameters

writer Utf8BencodeWriter

The destination writer.

Remarks

The encoded bytes are emitted verbatim through WriteRawValue(ReadOnlySpan<byte>, bool); because the document was validated when parsed, no re-validation occurs.

Exceptions

ObjectDisposedException

Thrown when the document has been disposed.

InvalidOperationException

Thrown when the writer's call sequence does not permit a value at the current position.

Applies to

Product	Versions
.NET	8, 10