BencodeReader Class

Reads bencode from a stream or a PipeReader one token at a time, without building the whole document in memory.

public sealed class BencodeReader : IAsyncDisposable

Remarks

The reader checks the encoding as it reads (one encoding per integer and string, keys that are strings, at most 64 nested containers, a single root value), and throws a FormatException at the first invalid token. It does not detect duplicate dictionary keys, which would require keeping every key: BencodeReader.ReadValueAsync does.

Implements

Constructors

NameDescription
BencodeReader(PipeReader)Creates a reader over a PipeReader. Disposing the reader does not complete reader.
BencodeReader(Stream, bool)Creates a reader over a stream.

BencodeReader overloads

BencodeReader(PipeReader)

BencodeReader.cs

Creates a reader over a PipeReader. Disposing the reader does not complete reader.

public BencodeReader(PipeReader reader)
Parameters
reader PipeReader

BencodeReader(Stream, bool)

BencodeReader.cs

Creates a reader over a stream.

public BencodeReader(Stream stream, bool leaveOpen = false)
Parameters
stream Stream
The stream to read.
leaveOpen bool
true to leave the stream open when the reader is disposed.

Properties

NameDescription
BytesConsumedGets the number of bytes read so far, up to the end of the current token.
CurrentDepthGets the number of lists and dictionaries that contain the current token.
TokenTypeGets the kind of the current token.

BytesConsumed

BencodeReader.cs

Gets the number of bytes read so far, up to the end of the current token.

public long BytesConsumed { get; }

Property value

long

CurrentDepth

BencodeReader.cs

Gets the number of lists and dictionaries that contain the current token.

public int CurrentDepth { get; }

Property value

int

Gets the kind of the current token.

public BencodeTokenType TokenType { get; }

Property value

BencodeTokenType

Methods

NameDescription
DisposeAsync()Releases the buffers of the reader, and completes the stream reader when the reader was created from a stream.
GetBigInteger()Gets the current BencodeTokenType.Integer token, whatever its size.
GetBytes()Gets the bytes of the current BencodeTokenType.String or BencodeTokenType.Key token.
GetInt64()Gets the current BencodeTokenType.Integer token as a Int64.
GetUtf8String()Decodes the current BencodeTokenType.String or BencodeTokenType.Key token as UTF-8.
ReadAsync(CancellationToken)Reads the next token.
ReadValueAsync(CancellationToken)Returns the value that starts at the current token, reading the rest of the list or dictionary it starts.
SkipAsync(CancellationToken)Skips the children of the current BencodeTokenType.StartList or BencodeTokenType.StartDictionary token, and positions the reader on its end. Other tokens are left as they are.
TryGetInt64(long)Gets the current BencodeTokenType.Integer token as a Int64 when it fits in one.

DisposeAsync()

BencodeReader.cs

Releases the buffers of the reader, and completes the stream reader when the reader was created from a stream.

net10.0

public ValueTask DisposeAsync()

net11.0

public ValueTask DisposeAsync()

Returns

ValueTask

GetBigInteger()

BencodeReader.cs

Gets the current BencodeTokenType.Integer token, whatever its size.

public BigInteger GetBigInteger()

Returns

BigInteger

Exceptions

InvalidOperationException
The current token is not an integer.

Gets the bytes of the current BencodeTokenType.String or BencodeTokenType.Key token.

public ReadOnlyMemory<byte> GetBytes()

Returns

ReadOnlyMemory<byte>

Exceptions

InvalidOperationException
The current token is not a string or a key.

Gets the current BencodeTokenType.Integer token as a Int64.

public long GetInt64()

Returns

long

Exceptions

InvalidOperationException
The current token is not an integer.
OverflowException
The integer does not fit in a Int64.

GetUtf8String()

BencodeReader.cs

Decodes the current BencodeTokenType.String or BencodeTokenType.Key token as UTF-8.

public string GetUtf8String()

Returns

string

Exceptions

InvalidOperationException
The current token is not a string or a key.
DecoderFallbackException
The bytes are not valid UTF-8.

ReadAsync(CancellationToken)

BencodeReader.cs

Reads the next token.

net10.0

public ValueTask<bool> ReadAsync(CancellationToken cancellationToken = default)

net11.0

public ValueTask<bool> ReadAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask<bool> true when a token was read; false when the root value is complete and the data ends.

Exceptions

FormatException
The data is not valid bencode, or it has data after the root value.

ReadValueAsync(CancellationToken)

BencodeReader.cs

Returns the value that starts at the current token, reading the rest of the list or dictionary it starts.

net10.0

public ValueTask<BencodeValue> ReadValueAsync(CancellationToken cancellationToken = default)

net11.0

public ValueTask<BencodeValue> ReadValueAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask<BencodeValue>

Exceptions

InvalidOperationException
The current token does not start a value.
FormatException
The data is not valid bencode, or a dictionary has a duplicate key.

Remarks

After the call, the reader is positioned on the last token of the value. A key returns a BencodeString.

SkipAsync(CancellationToken)

BencodeReader.cs

Skips the children of the current BencodeTokenType.StartList or BencodeTokenType.StartDictionary token, and positions the reader on its end. Other tokens are left as they are.

net10.0

public ValueTask SkipAsync(CancellationToken cancellationToken = default)

net11.0

public ValueTask SkipAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask

TryGetInt64(long)

BencodeReader.cs

Gets the current BencodeTokenType.Integer token as a Int64 when it fits in one.

public bool TryGetInt64(out long value)

Parameters

value long

Returns

bool

Exceptions

InvalidOperationException
The current token is not an integer.