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

object

NbtReader

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Constructors

NbtReader(Stream)

Initializes a new instance of the NbtReader class.

public NbtReader(Stream stream)

Parameters

stream Stream

Stream to read from.

Remarks

Assumes that data in the stream is Big-Endian encoded.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

stream is not readable.

NbtReader(Stream, bool)

Initializes a new instance of the NbtReader class.

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.

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

HasLength

Whether the current tag has length (Lists, ByteArrays, and IntArrays 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

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, or TAG_Int_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 number of bytes from the beginning of the stream to the beginning of this tag. If the stream is not seekable, this value will always be 0.

public int TagStartOffset { get; }

Property Value

int

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.

public NbtTag ReadAsTag()

Returns

NbtTag

Constructed NbtTag object; null if SkipEndTags is true and trying to read an End tag.

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

Tag value has already been read, and CacheTagValues is false.

ReadListAsArray<T>()

If the current tag is a List, reads all elements of this list as an array. If any tags/values have already been read from this list, only reads the remaining unread tags/values. ListType must be a value type (byte, short, int, long, float, double, or string). Stops reading after the last list element.

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. Tag contents should be convertible to this type.

Exceptions

EndOfStreamException

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

InvalidOperationException

Current tag is not of type List.

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 a matching child tag is not found, the NbtReader is positioned on the end tag.

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.

InvalidOperationException

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.

InvalidOperationException

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 an object of the type specified.

public T ReadValueAs<T>()

Returns

T

Tag value converted to the requested type.

Type Parameters

T

The type of the value to be returned. Tag value should be convertible to this 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.

InvalidCastException

Tag value cannot be converted to 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