Table of Contents

BencodeElement Struct

Definition

Namespace
Bodu.Text.Bencode.Document
Assembly
Bodu.Text.Bencode.dll
Package
Bodu.Text.Bencode 1.0.0
Source
BencodeElement.ArrayEnumerator.cs

Represents a single read-only value within a BencodeDocument. The element is a lightweight view - a pair of the owning document and a row index - so copying it is cheap and never materializes a node.

public readonly struct BencodeElement
Inherited Members
Extension Methods

Remarks

An element is valid only for the lifetime of its owning BencodeDocument. After the document is disposed, any member access throws ObjectDisposedException.

Because Bencode (BEP 3) defines only dictionaries, lists, byte strings, and integers, this type has no Boolean, null, or floating-point surface, and exposes byte-string content through both GetString() (UTF-8 text) and GetBytes() (raw bytes). 

// Navigate a parsed torrent without materializing a mutable tree.
using BencodeDocument document = BencodeDocument.Parse(torrentBytes);
BencodeElement root = document.RootElement;

var announce = root.GetProperty("announce").GetString();
BencodeElement info = root.GetProperty("info");
var pieceLength = info.GetProperty("piece length").GetInt64();
byte[] pieces = info.GetProperty("pieces").GetBytes();   // raw byte string

Properties

this[int]

Gets the element at the supplied index within this array element.

public BencodeElement this[int index] { get; }

Parameters

index int

The zero-based index of the element to retrieve.

Property Value

BencodeElement

The element at index.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Array.

ArgumentOutOfRangeException

Thrown when index is negative or not less than the array length.

ValueKind

Gets the kind of this element.

public BencodeValueKind ValueKind { get; }

Property Value

BencodeValueKind

The value kind.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

Methods

Clone()

Creates an independent copy of this element whose lifetime is not tied to the owning document.

public BencodeElement Clone()

Returns

BencodeElement

A BencodeElement backed by a private document that does not require disposal.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

EnumerateArray()

Returns an enumerator that iterates the elements of this array element in order.

public BencodeElement.ArrayEnumerator EnumerateArray()

Returns

BencodeElement.ArrayEnumerator

An BencodeElement.ArrayEnumerator over the array's elements.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Array.

EnumerateObject()

Returns an enumerator that iterates the key/value pairs of this object element in stored order.

public BencodeElement.ObjectEnumerator EnumerateObject()

Returns

BencodeElement.ObjectEnumerator

An BencodeElement.ObjectEnumerator over the object's properties.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Object.

GetArrayLength()

Gets the number of elements in this array element.

public int GetArrayLength()

Returns

int

The element count.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Array.

GetBytes()

Copies this byte-string element's content to a new array.

public byte[] GetBytes()

Returns

byte[]

A copy of the byte-string content.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not a ByteString.

GetInt64()

Gets the value of this integer element as a 64-bit signed integer.

public long GetInt64()

Returns

long

The decoded integer value.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Integer.

BencodeFormatException

Thrown when the integer's value exceeds MaxValue; use GetUInt64() to read values in the upper unsigned 64-bit range.

GetProperty(string)

Gets the value of the property with the supplied name within this object element.

public BencodeElement GetProperty(string propertyName)

Parameters

propertyName string

The name of the property to retrieve.

Returns

BencodeElement

The value element of the matching property.

Exceptions

ArgumentNullException

Thrown when propertyName is null.

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Object.

KeyNotFoundException

Thrown when no property named propertyName exists.

GetRawBytes()

Copies the complete encoded form of this element to a new array. For a byte string the result includes the length prefix, for an integer the i…e framing, and for a container both delimiters and every child.

public byte[] GetRawBytes()

Returns

byte[]

The raw encoded bytes of this element.

Remarks

Because canonical Bencode is byte-exact, the returned slice is suitable for hashing - for example, computing a torrent's info-hash from the info dictionary's element - and for verbatim re-emission through WriteRawValue(ReadOnlySpan<byte>, bool).

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

GetString()

Decodes this byte-string element as UTF-8 text.

public string GetString()

Returns

string

The decoded string.

Remarks

Use GetBytes() instead when the byte string is not valid UTF-8 text.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not a ByteString.

GetUInt64()

Gets the value of this integer element as a 64-bit unsigned integer, accepting any value in [0, MaxValue ].

public ulong GetUInt64()

Returns

ulong

The decoded unsigned integer value.

Remarks

Bencode integers are arbitrary-precision per BEP 3, so a document may carry a value between MaxValue and MaxValue that GetInt64() cannot represent; this accessor reads such values without loss, mirroring GetUInt64().

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Integer.

BencodeFormatException

Thrown when the integer's value is negative.

ToString()

Returns a textual representation of this element.

public override string ToString()

Returns

string

The decimal value for an integer, the UTF-8 text for a byte string, or the literal name of the container kind for an array or object.

Remarks

Container values are not re-serialized; the kind name is returned instead to keep the operation allocation-light.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

TryGetInt64(out long)

Attempts to get the value of this integer element as a 64-bit signed integer.

public bool TryGetInt64(out long value)

Parameters

value long

When this method returns true, the integer value; otherwise zero.

Returns

bool

true when the value fits the signed 64-bit range; false when it is readable only through GetUInt64().

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Integer.

TryGetProperty(string, out BencodeElement)

Attempts to get the value of the property with the supplied name within this object element.

public bool TryGetProperty(string propertyName, out BencodeElement value)

Parameters

propertyName string

The name of the property to retrieve.

value BencodeElement

When this method returns, the value element of the matching property; otherwise the default element.

Returns

bool

true when a matching property was found; otherwise false.

Exceptions

ArgumentNullException

Thrown when propertyName is null.

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Object.

TryGetUInt64(out ulong)

Attempts to get the value of this integer element as a 64-bit unsigned integer.

public bool TryGetUInt64(out ulong value)

Parameters

value ulong

When this method returns true, the unsigned integer value; otherwise zero.

Returns

bool

true when the value is non-negative; otherwise false.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Integer.

WriteTo(Utf8BencodeWriter)

Writes the complete encoded form of this element to the supplied writer.

public void WriteTo(Utf8BencodeWriter writer)

Parameters

writer Utf8BencodeWriter

The destination writer.

Remarks

The encoded bytes are emitted verbatim; because the owning document was validated when parsed, no re-validation occurs.

Exceptions

InvalidOperationException

Thrown when this element is the default value and belongs to no document, or when the writer's call sequence does not permit a value at the current position.

ObjectDisposedException

Thrown when the owning document has been disposed.

Applies to

ProductVersions
.NET8, 10