Table of Contents

Class NbtReader

Namespace
fNbt
Assembly
fNbt.dll

Represents a reader that provides fast, non-cached, forward-only access to NBT data. Each instance of NbtReader reads one complete file.

public class NbtReader
Inheritance
NbtReader
Inherited Members

Constructors

NbtReader(Stream)

Initializes a new instance of the NbtReader class with the current defaults (DefaultFlavor and the other NbtOptions defaults).

public NbtReader(Stream stream)

Parameters

stream Stream

Stream to read from.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

stream is not readable.

NbtReader(Stream, bool)

Initializes a new instance of the NbtReader class.

[Obsolete("Use NbtReader(Stream, NbtFlavor) instead. true corresponds to NbtFlavor.Java, false to NbtFlavor.Bedrock.")]
public NbtReader(Stream stream, bool bigEndian)

Parameters

stream Stream

Stream to read from.

bigEndian bool

Whether NBT data is in Big-Endian encoding.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

stream is not readable.

NbtReader(Stream, NbtFlavor)

Initializes a new instance of the NbtReader class for the given flavor, with the current default policy settings.

public NbtReader(Stream stream, NbtFlavor flavor)

Parameters

stream Stream

Stream to read from.

flavor NbtFlavor

Encoding to read with.

Exceptions

ArgumentNullException

stream or flavor is null.

ArgumentException

stream is not readable; or the flavor has no root name (use NbtCodec for those).

NbtReader(Stream, NbtOptions)

Initializes a new instance of the NbtReader class with the given options. When read validation is on, the flavor's tag-type range and string ceiling are enforced; MaxAllocation caps declared-length allocations either way.

public NbtReader(Stream stream, NbtOptions options)

Parameters

stream Stream

Stream to read from.

options NbtOptions

Settings to use, resolved here. May not be null.

Exceptions

ArgumentNullException

stream, options, or the options' Flavor is null.

ArgumentException

stream is not readable; or the options' flavor has no root name (use NbtCodec for those).

ArgumentOutOfRangeException

MaxAllocation is zero or negative.

Properties

BaseStream

Gets the Stream from which data is being read.

public Stream BaseStream { get; }

Property Value

Stream

CacheTagValues

Parsing option: Whether NbtReader should save a copy of the most recently read tag's value. Unless CacheTagValues is true, tag values can only be read once. Default is false.

public bool CacheTagValues { get; set; }

Property Value

bool

Depth

Gets the depth of the current tag in the hierarchy. RootTag is at depth 1, its descendant tags are 2, etc.

public int Depth { get; }

Property Value

int

Flavor

The flavor this reader decodes with, fixed at construction.

public NbtFlavor Flavor { get; }

Property Value

NbtFlavor

HasLength

Whether the current tag has length (Lists, ByteArrays, IntArrays, and LongArrays have length). Compound tags also have length, technically, but it is not known until all child tags are read.

public bool HasLength { get; }

Property Value

bool

HasName

Whether current tag has a name.

public bool HasName { get; }

Property Value

bool

HasValue

Whether current tag has a value to read.

public bool HasValue { get; }

Property Value

bool

IsAtStreamEnd

Whether this reader has reached the end of stream.

public bool IsAtStreamEnd { get; }

Property Value

bool

IsCompound

Whether the current tag is a Compound.

public bool IsCompound { get; }

Property Value

bool

IsInErrorState

Gets whether this NbtReader instance is in state of error. No further reading can be done from this instance if a parse error occurred.

public bool IsInErrorState { get; }

Property Value

bool

IsList

Whether the current tag is a List.

public bool IsList { get; }

Property Value

bool

IsListElement

Whether tag that we are currently on is a list element.

public bool IsListElement { get; }

Property Value

bool

ListIndex

If the parent tag is TAG_List, returns index of the current tag.

public int ListIndex { get; }

Property Value

int

ListType

If the current tag is TAG_List, returns type of the list elements.

public NbtTagType ListType { get; }

Property Value

NbtTagType

LongTagStartOffset

Gets the offset of the current tag's first byte from the stream position at which this NbtReader was created, which is the start of the document, as a long. Always 0 if the stream is not seekable.

public long LongTagStartOffset { get; }

Property Value

long

ParentName

Gets the name of the parent tag. May be null (for root tags and descendants of list elements).

public string? ParentName { get; }

Property Value

string

ParentTagLength

If the parent tag is TAG_List, returns the number of elements.

public int ParentTagLength { get; }

Property Value

int

ParentTagType

Gets the type of the parent tag. Returns TagType.Unknown if there is no parent tag.

public NbtTagType ParentTagType { get; }

Property Value

NbtTagType

RootName

Gets the name of the root tag of this NBT stream.

public string? RootName { get; }

Property Value

string

SkipEndTags

Parsing option: Whether NbtReader should skip End tags in ReadToFollowing() automatically while parsing. Default is true.

public bool SkipEndTags { get; set; }

Property Value

bool

TagLength

If the current tag is TAG_List, TAG_Byte_Array, TAG_Int_Array, or TAG_Long_Array, returns the number of elements.

public int TagLength { get; }

Property Value

int

TagName

Gets the name of the current tag. May be null (for list elements and end tags).

public string? TagName { get; }

Property Value

string

TagStartOffset

Gets the offset of the current tag's first byte from the stream position at which this NbtReader was created, which is the start of the document. Always 0 if the stream is not seekable.

public int TagStartOffset { get; }

Property Value

int

Exceptions

OverflowException

The offset does not fit in an int; use LongTagStartOffset for documents past 2 GiB.

TagType

Gets the type of the current tag.

public NbtTagType TagType { get; }

Property Value

NbtTagType

TagsRead

Gets the number of tags read from the stream so far (including the current tag and all skipped tags). If SkipEndTags is false, all end tags are also counted.

public int TagsRead { get; }

Property Value

int

Methods

ReadAsTag()

Reads the entirety of the current tag, including any descendants, and constructs an NbtTag object of the appropriate type. Cannot be called on an End tag, which no NbtTag represents; the reader stays usable after that refusal.

public NbtTag ReadAsTag()

Returns

NbtTag

Constructed NbtTag object.

Exceptions

NbtFormatException

If an error occurred while parsing data in NBT format.

InvalidReaderStateException

If NbtReader cannot recover from a previous parsing error.

EndOfStreamException

End of stream has been reached (no more tags can be read).

InvalidOperationException

The reader is on an End tag, or the tag's value has already been read and CacheTagValues is false.

ReadListAsArray<T>()

If the current tag is a List, or a value element of one, reads the list's remaining values as an array. A current element whose value has not been read yet is included; one whose value was already read is not. The element type must be byte, short, int, long, float, double, or string. Stops reading after the last list element; an empty list is not entered, so the reader stays on the list tag.

public T[] ReadListAsArray<T>()

Returns

T[]

List contents converted to an array of the requested type.

Type Parameters

T

Element type of the array to be returned: the list's own element type, any primitive or string type ChangeType(object, Type) can reach from it, or an enum type over a list of integral values or member names.

Remarks

The refusals below are checked before anything is read, so after one of them the reader is where it was. A failure once reading has begun, a conversion included, leaves the reader in its error state, since the stream position is then unknown. After a successful call no value is available to ReadValue(), even with CacheTagValues.

Exceptions

EndOfStreamException

End of stream has been reached, or the list's declared length does not fit in the remaining stream.

InvalidOperationException

The reader is not on a List or one of its value elements, the list's element type is not supported by this method, or T is not a type values can be converted to.

FormatException

A value could not be converted to T.

OverflowException

A value does not fit in T.

InvalidReaderStateException

If NbtReader cannot recover from a previous parsing error.

NbtFormatException

If an error occurred while parsing data in NBT format.

ReadToDescendant(string?)

Advances the NbtReader to the next descendant tag with the specified name. If none matches, the reader is left on the first tag outside the current tag's subtree: its next sibling, an enclosing container's End tag when SkipEndTags is false, or the end of the stream.

public bool ReadToDescendant(string? tagName)

Parameters

tagName string

Name of the tag you wish to move to. May be null (to look for next unnamed tag).

Returns

bool

true if a matching descendant tag is found; otherwise false.

Exceptions

NbtFormatException

If an error occurred while parsing data in NBT format.

InvalidReaderStateException

If NbtReader cannot recover from a previous parsing error.

ReadToFollowing()

Reads the next tag from the stream.

public bool ReadToFollowing()

Returns

bool

true if the next tag was read successfully; false if there are no more tags to read.

Exceptions

NbtFormatException

If an error occurred while parsing data in NBT format.

InvalidReaderStateException

If NbtReader cannot recover from a previous parsing error.

ReadToFollowing(string?)

Reads until a tag with the specified name is found. Returns false if are no more tags to read (end of stream is reached).

public bool ReadToFollowing(string? tagName)

Parameters

tagName string

Name of the tag. May be null (to look for next unnamed tag).

Returns

bool

true if a matching tag is found; otherwise false.

Exceptions

NbtFormatException

If an error occurred while parsing data in NBT format.

InvalidReaderStateException

If NbtReader cannot recover from a previous parsing error.

ReadToNextSibling()

Advances the NbtReader to the next sibling tag, skipping any child tags. If there are no more siblings, NbtReader is positioned on the tag following the last of this tag's descendants.

public bool ReadToNextSibling()

Returns

bool

true if a sibling element is found; otherwise false.

Exceptions

NbtFormatException

If an error occurred while parsing data in NBT format.

InvalidReaderStateException

If NbtReader cannot recover from a previous parsing error.

ReadToNextSibling(string?)

Advances the NbtReader to the next sibling tag with the specified name. If a matching sibling tag is not found, NbtReader is positioned on the tag following the last siblings.

public bool ReadToNextSibling(string? tagName)

Parameters

tagName string

The name of the sibling tag you wish to move to.

Returns

bool

true if a matching sibling element is found; otherwise false.

Exceptions

NbtFormatException

If an error occurred while parsing data in NBT format.

InvalidReaderStateException

If NbtReader cannot recover from a previous parsing error.

ReadValue()

Reads the value as an object of the correct type, boxed. Cannot be called for tags that do not have a single-object value (compound, list, and end tags).

public object ReadValue()

Returns

object

Tag value converted to the requested type.

Exceptions

EndOfStreamException

End of stream has been reached (no more tags can be read).

NbtFormatException

If an error occurred while parsing data in NBT format.

InvalidOperationException

Value has already been read, or there is no value to read.

InvalidReaderStateException

If NbtReader cannot recover from a previous parsing error.

ReadValueAs<T>()

Reads the value as the type specified: the tag's own value type directly, any type ChangeType(object, Type) can reach from it, such as a wider numeric type or a string, or an enum type from an integral value or a member name. Array values are returned as their own array type only.

public T ReadValueAs<T>()

Returns

T

Tag value converted to the requested type.

Type Parameters

T

The type of the value to be returned.

Remarks

A failed conversion happens after the value was read from the stream, so the value is then gone unless CacheTagValues is on; the reader stays usable.

Exceptions

EndOfStreamException

End of stream has been reached (no more tags can be read).

NbtFormatException

If an error occurred while parsing data in NBT format.

InvalidOperationException

Value has already been read, or there is no value to read.

InvalidReaderStateException

If NbtReader cannot recover from a previous parsing error.

InvalidCastException

Tag value cannot be converted to the requested type.

FormatException

A string value is not in a format the requested type accepts, or names no member of the requested enum type.

OverflowException

The value does not fit in the requested type.

Skip()

Skips current tag, its value/descendants, and any following siblings. In other words, reads until parent tag's sibling.

public int Skip()

Returns

int

Total number of tags that were skipped. Returns 0 if end of the stream is reached.

Exceptions

NbtFormatException

If an error occurred while parsing data in NBT format.

InvalidReaderStateException

If NbtReader cannot recover from a previous parsing error.

ToString()

Returns a String that represents the tag currently being read by this NbtReader instance. Prints current tag's depth, ordinal number, type, name, and size (for arrays and lists). Does not print value. Indents the tag according default indentation (NbtTag.DefaultIndentString).

public override string ToString()

Returns

string

ToString(bool)

Returns a String that represents the tag currently being read by this NbtReader instance. Prints current tag's depth, ordinal number, type, name, size (for arrays and lists), and optionally value. Indents the tag according default indentation (NbtTag.DefaultIndentString).

public string ToString(bool includeValue)

Parameters

includeValue bool

If set to true, also reads and prints the current tag's value. Note that unless CacheTagValues is set to true, you can only read every tag's value ONCE.

Returns

string

ToString(bool, string)

Returns a String that represents the current NbtReader object. Prints current tag's depth, ordinal number, type, name, size (for arrays and lists), and optionally value.

public string ToString(bool includeValue, string indentString)

Parameters

includeValue bool

If set to true, also reads and prints the current tag's value.

indentString string

String to be used for indentation. May be empty string, but may not be null.

Returns

string