BencodeValue Class

Definition

Namespace

Bodu.Text.Bencode.Nodes

Assembly

Bodu.Text.Bencode.dll

Package

Bodu.Text.Bencode 1.0.0

Source

BencodeValue.cs

Represents a scalar Bencode (BEP 3) value - either an integer or a byte string - within a node tree.

public sealed class BencodeValue : BencodeNode

Inheritance

object

BencodeNode

BencodeValue

Inherited Members

BencodeNode.AsObject()

BencodeNode.AsArray()

BencodeNode.AsValue()

BencodeNode.ToByteArray()

BencodeNode.Parse(ReadOnlySpan<byte>)

BencodeNode.Parse(ReadOnlySpan<byte>, BencodeNodeOptions)

BencodeNode.Parse(ReadOnlySpan<byte>, BencodeNodeOptions, BencodeDocumentOptions)

BencodeNode.GetPath()

BencodeNode.ReplaceWith(BencodeNode)

BencodeNode.DeepEquals(BencodeNode, BencodeNode)

BencodeNode.Parent

BencodeNode.Root

BencodeNode.this[int]

BencodeNode.this[string]

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

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

Because Bencode has only two scalar kinds, a BencodeValue stores either a 64-bit integer or a byte string; the two are distinguished by GetValueKind(). A string is stored as its UTF-8 byte string, and an integer-valued instance can be read back as any fixed-width integer type through a checked conversion.

// Bencode's native scalar is the byte string; text is a UTF-8 convenience view.
BencodeValue length = BencodeValue.Create(262144L);
BencodeValue name = BencodeValue.Create("data.bin");
BencodeValue hash = BencodeValue.Create(new byte[] { 0x12, 0x34, 0x56 });

var text = name.GetValue<string>();     // "data.bin"
var raw = hash.GetValue<byte[]>();      // the original bytes

Methods

Create(byte[])

Creates a BencodeValue holding a copy of the supplied byte array as a byte string.

public static BencodeValue Create(byte[] value)

Parameters

value byte[]

The byte-string content.

Returns

BencodeValue

A new byte-string node.

Exceptions

ArgumentNullException

Thrown when value is null.

Create(int)

Creates a BencodeValue holding the supplied 32-bit integer.

public static BencodeValue Create(int value)

Parameters

value int

The integer value.

Returns

BencodeValue

A new integer-valued node.

Create(long)

Creates a BencodeValue holding the supplied 64-bit integer.

public static BencodeValue Create(long value)

Parameters

value long

The integer value.

Returns

BencodeValue

A new integer-valued node.

Create(ReadOnlySpan<byte>)

Creates a BencodeValue holding a copy of the supplied bytes as a byte string.

public static BencodeValue Create(ReadOnlySpan<byte> value)

Parameters

value ReadOnlySpan<byte>

The byte-string content.

Returns

BencodeValue

A new byte-string node.

Create(string)

Creates a BencodeValue holding the supplied string as a UTF-8 byte string.

public static BencodeValue Create(string value)

Parameters

value string

The string value.

Returns

BencodeValue

A new byte-string node.

Exceptions

ArgumentNullException

Thrown when value is null.

Create(ulong)

Creates a BencodeValue holding the supplied unsigned 64-bit integer, permitting the full ulong range.

public static BencodeValue Create(ulong value)

Parameters

value ulong

The unsigned integer value.

Returns

BencodeValue

A new integer-valued node.

Remarks

Bencode integers are arbitrary-precision per BEP 3, so values between MaxValue and MaxValue are valid documents. Such a value reads back through GetValue<ulong>(); requesting a narrower integer type fails. Values within the signed 64-bit range are stored identically to Create(long).

DeepClone()

Creates a deep copy of this node and its entire subtree.

public override BencodeNode DeepClone()

Returns

BencodeNode

An independent clone with no parent.

GetValueKind()

Gets the kind of value this node represents.

public override BencodeValueKind GetValueKind()

Returns

BencodeValueKind

The BencodeValueKind of this node.

GetValue<T>()

Returns the scalar value converted to the requested type.

public T GetValue<T>()

Returns

T

The converted scalar value.

Type Parameters

T

The type to convert the scalar value to.

Exceptions

InvalidOperationException

Thrown when the stored value cannot be converted to T.

ToString()

Returns a string representation of this node.

public override string ToString()

Returns

string

A textual rendering of this node.

TryGetValue<T>(out T)

Attempts to convert the scalar value to the requested type.

public bool TryGetValue<T>(out T value)

Parameters

value T

When this method returns true, the converted value; otherwise the default value of T.

Returns

bool

true when the stored value was converted to T; otherwise false.

Type Parameters

T

The type to convert the scalar value to.

Remarks

Integer values convert to any fixed-width integer type through a checked conversion that fails when the value is out of range, and byte strings convert to string (UTF-8 decode) or to a copy of the underlying byte array. Any other combination of stored kind and requested type yields false.

WriteTo(Utf8BencodeWriter)

Writes the canonical Bencode encoding of this node to the supplied writer.

public override void WriteTo(Utf8BencodeWriter writer)

Parameters

writer Utf8BencodeWriter

The destination writer.

Exceptions

BencodeSerializationException

Thrown when the subtree rooted at this node contains a null entry, which has no Bencode representation.

Applies to

Product	Versions
.NET	8, 10