Class NbtFile

Namespace: fNbt

Assembly: fNbt.dll

Represents a complete NBT file.

public sealed class NbtFile

Inheritance: object

NbtFile

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Constructors

NbtFile()

Creates an empty NbtFile. RootTag will be set to an empty NbtCompound with a blank name ("").

public NbtFile()

NbtFile(string)

Loads NBT data from a file using the most common settings. Automatically detects compression. Assumes the file to be big-endian, and uses default buffer size.

public NbtFile(string fileName)

Parameters

fileName string: Name of the file from which data will be loaded.

Exceptions

ArgumentNullException: fileName is null.
FileNotFoundException: If given file was not found.
EndOfStreamException: If file ended earlier than expected.
InvalidDataException: If file compression could not be detected, or decompressing failed.
NbtFormatException: If an error occurred while parsing data in NBT format.
IOException: If an I/O error occurred while reading the file.

NbtFile(NbtCompound)

Creates a new NBT file with the given root tag.

public NbtFile(NbtCompound rootTag)

Parameters

rootTag NbtCompound: Compound tag to set as the root tag. May be null.

Exceptions

ArgumentException: If given rootTag is unnamed.

Properties

BigEndian

Whether this file should read/write tags in big-endian encoding format.

public bool BigEndian { get; set; }

Property Value

bool

BigEndianByDefault

Whether new NbtFiles should default to big-endian encoding (default: true).

public static bool BigEndianByDefault { get; set; }

Property Value

bool

BufferSize

Gets or sets the size of internal buffer used for reading files and streams. Initialized to value of DefaultBufferSize property.

public int BufferSize { get; set; }

Property Value

int

Exceptions

ArgumentOutOfRangeException: value is negative.

DefaultBufferSize

Gets or sets the default value of BufferSize property. Default is 8192. Set to 0 to disable buffering by default.

public static int DefaultBufferSize { get; set; }

Property Value

int

Exceptions

ArgumentOutOfRangeException: value is negative.

FileCompression

Gets the compression method used for most recent loading/saving of this file. Defaults to AutoDetect.

public NbtCompression FileCompression { get; }

Property Value

NbtCompression

FileName

Gets the file name used for most recent loading/saving of this file. May be null, if this NbtFile instance has not been loaded from, or saved to, a file.

public string? FileName { get; }

Property Value

string

RootTag

Root tag of this file. Must be a named CompoundTag. Defaults to an empty-named tag.

public NbtCompound RootTag { get; set; }

Property Value

NbtCompound

Exceptions

ArgumentException: If given tag is unnamed.

Methods

LoadFromBuffer(byte[], int, int, NbtCompression)

Loads NBT data from a byte array. Existing RootTag will be replaced. FileName will be set to null.

public long LoadFromBuffer(byte[] buffer, int index, int length, NbtCompression compression)

Parameters

buffer byte[]: Stream from which data will be loaded. If compression is set to AutoDetect, this stream must support seeking.
index int: The index into buffer at which the stream begins. Must not be negative.
length int: Maximum number of bytes to read from the given buffer. Must not be negative. An EndOfStreamException is thrown if NBT stream is longer than the given length.
compression NbtCompression: Compression method to use for loading/saving this file.

Returns

long: Number of bytes read from the buffer.

Exceptions

ArgumentNullException: buffer is null.
ArgumentOutOfRangeException: If an unrecognized/unsupported value was given for compression; if index or length is less than zero; if the sum of index and length is greater than the length of buffer.
EndOfStreamException: If NBT stream extends beyond the given length.
InvalidDataException: If file compression could not be detected or decompressing failed.
NbtFormatException: If an error occurred while parsing data in NBT format.

LoadFromBuffer(byte[], int, int, NbtCompression, TagSelector?)

Loads NBT data from a byte array. Existing RootTag will be replaced. FileName will be set to null.

public long LoadFromBuffer(byte[] buffer, int index, int length, NbtCompression compression, TagSelector? selector)

Parameters

buffer byte[]: Stream from which data will be loaded. If compression is set to AutoDetect, this stream must support seeking.
index int: The index into buffer at which the stream begins. Must not be negative.
length int: Maximum number of bytes to read from the given buffer. Must not be negative. An EndOfStreamException is thrown if NBT stream is longer than the given length.
compression NbtCompression: Compression method to use for loading/saving this file.
selector TagSelector: Optional callback to select which tags to load into memory. Root may not be skipped. No reference is stored to this callback after loading (don't worry about implicitly captured closures). May be null.

Returns

long: Number of bytes read from the buffer.

Exceptions

ArgumentNullException: buffer is null.
ArgumentOutOfRangeException: If an unrecognized/unsupported value was given for compression; if index or length is less than zero; if the sum of index and length is greater than the length of buffer.
EndOfStreamException: If NBT stream extends beyond the given length.
InvalidDataException: If file compression could not be detected or decompressing failed.
NbtFormatException: If an error occurred while parsing data in NBT format.

LoadFromFile(string)

Loads NBT data from a file. Existing RootTag will be replaced. Compression will be auto-detected.

public long LoadFromFile(string fileName)

Parameters

fileName string: Name of the file from which data will be loaded.

Returns

long: Number of bytes read from the file.

Exceptions

ArgumentNullException: fileName is null.
FileNotFoundException: If given file was not found.
EndOfStreamException: If file ended earlier than expected.
InvalidDataException: If file compression could not be detected, or decompressing failed.
NbtFormatException: If an error occurred while parsing data in NBT format.
IOException: If an I/O error occurred while reading the file.

LoadFromFile(string, NbtCompression, TagSelector?)

Loads NBT data from a file. Existing RootTag will be replaced.

public long LoadFromFile(string fileName, NbtCompression compression, TagSelector? selector)

Parameters

fileName string: Name of the file from which data will be loaded.
compression NbtCompression: Compression method to use for loading/saving this file.
selector TagSelector: Optional callback to select which tags to load into memory. Root may not be skipped. No reference is stored to this callback after loading (don't worry about implicitly captured closures). May be null.

Returns

long: Number of bytes read from the file.

Exceptions

ArgumentNullException: fileName is null.
ArgumentOutOfRangeException: If an unrecognized/unsupported value was given for compression.
FileNotFoundException: If given file was not found.
EndOfStreamException: If file ended earlier than expected.
InvalidDataException: If file compression could not be detected, or decompressing failed.
NbtFormatException: If an error occurred while parsing data in NBT format.
IOException: If an I/O error occurred while reading the file.

LoadFromStream(Stream, NbtCompression)

Loads NBT data from a stream. Existing RootTag will be replaced

public long LoadFromStream(Stream stream, NbtCompression compression)

Parameters

stream Stream: Stream from which data will be loaded. If compression is set to AutoDetect, this stream must support seeking.
compression NbtCompression: Compression method to use for loading/saving this file.

Returns

long: Number of bytes read from the stream.

Exceptions

ArgumentNullException: stream is null.
ArgumentOutOfRangeException: If an unrecognized/unsupported value was given for compression.
NotSupportedException: If compression is set to AutoDetect, but the stream is not seekable.
EndOfStreamException: If file ended earlier than expected.
InvalidDataException: If file compression could not be detected, decompressing failed, or given stream does not support reading.
NbtFormatException: If an error occurred while parsing data in NBT format.

LoadFromStream(Stream, NbtCompression, TagSelector?)

Loads NBT data from a stream. Existing RootTag will be replaced

public long LoadFromStream(Stream stream, NbtCompression compression, TagSelector? selector)

Parameters

stream Stream: Stream from which data will be loaded. If compression is set to AutoDetect, this stream must support seeking.
compression NbtCompression: Compression method to use for loading/saving this file.
selector TagSelector: Optional callback to select which tags to load into memory. Root may not be skipped. No reference is stored to this callback after loading (don't worry about implicitly captured closures). May be null.

Returns

long: Number of bytes read from the stream.

Exceptions

ArgumentNullException: stream is null.
ArgumentOutOfRangeException: If an unrecognized/unsupported value was given for compression.
NotSupportedException: If compression is set to AutoDetect, but the stream is not seekable.
EndOfStreamException: If file ended earlier than expected.
InvalidDataException: If file compression could not be detected, decompressing failed, or given stream does not support reading.
NbtFormatException: If an error occurred while parsing data in NBT format.

ReadRootTagName(Stream, NbtCompression, bool, int)

Reads the root name from the given stream of NBT data.

public static string ReadRootTagName(Stream stream, NbtCompression compression, bool bigEndian, int bufferSize)

Parameters

stream Stream: Stream from which data will be loaded. If compression is set to AutoDetect, this stream must support seeking.
compression NbtCompression: Compression method to use for loading this stream.
bigEndian bool: Whether the stream uses big-endian (default) or little-endian encoding.
bufferSize int: No longer used.

Returns

string: Name of the root tag in the given stream.

Exceptions

ArgumentNullException: stream is null.
ArgumentOutOfRangeException: If an unrecognized/unsupported value was given for compression.
NotSupportedException: If compression is set to AutoDetect, but the stream is not seekable.
EndOfStreamException: If file ended earlier than expected.
InvalidDataException: If file compression could not be detected, decompressing failed, or given stream does not support reading.
NbtFormatException: If an error occurred while parsing data in NBT format.

ReadRootTagName(string)

Reads the root name from the given NBT file. Automatically detects compression.

public static string ReadRootTagName(string fileName)

Parameters

fileName string: Name of the file from which first tag will be read.

Returns

string: Name of the root tag in the given NBT file.

Exceptions

ArgumentNullException: fileName is null.
FileNotFoundException: If given file was not found.
EndOfStreamException: If file ended earlier than expected.
InvalidDataException: If file compression could not be detected, or decompressing failed.
NbtFormatException: If an error occurred while parsing data in NBT format.
IOException: If an I/O error occurred while reading the file.

ReadRootTagName(string, NbtCompression, bool, int)

Reads the root name from the given NBT file.

public static string ReadRootTagName(string fileName, NbtCompression compression, bool bigEndian, int bufferSize)

Parameters

fileName string: Name of the file from which data will be loaded.
compression NbtCompression: Format in which the given file is compressed.
bigEndian bool: Whether the file uses big-endian (default) or little-endian encoding.
bufferSize int: No longer used.

Returns

string: Name of the root tag in the given NBT file.

Exceptions

ArgumentNullException: fileName is null.
ArgumentOutOfRangeException: If an unrecognized/unsupported value was given for compression.
FileNotFoundException: If given file was not found.
EndOfStreamException: If file ended earlier than expected.
InvalidDataException: If file compression could not be detected, or decompressing failed.
NbtFormatException: If an error occurred while parsing data in NBT format.
IOException: If an I/O error occurred while reading the file.

SaveToBuffer(byte[], int, NbtCompression)

Saves this NBT file to a stream. Nothing is written to stream if RootTag is null.

public long SaveToBuffer(byte[] buffer, int index, NbtCompression compression)

Parameters

buffer byte[]: Buffer to write data to. May not be null.
index int: The index into buffer at which the stream should begin.
compression NbtCompression: Compression mode to use for saving. May not be AutoDetect.

Returns

long: Number of bytes written to the buffer.

Exceptions

ArgumentNullException: buffer is null.
ArgumentException: If AutoDetect was given as the compression mode.
ArgumentOutOfRangeException: If an unrecognized/unsupported value was given for compression; if index is less than zero; or if index is greater than the length of buffer.
InvalidDataException: If given stream does not support writing.
UnauthorizedAccessException: Specified file is read-only, or a permission issue occurred.
NbtFormatException: If one of the NbtCompound tags contained unnamed tags; or if an NbtList tag had Unknown list type and no elements.

SaveToBuffer(NbtCompression)

Saves this NBT file to a new byte array. Returns an empty array if RootTag is null.

public byte[] SaveToBuffer(NbtCompression compression)

Parameters

compression NbtCompression: Compression mode to use for saving. May not be AutoDetect.

Returns

byte[]: Byte array containing the serialized NBT data.

Exceptions

ArgumentException: If AutoDetect was given as the compression mode.
ArgumentOutOfRangeException: If an unrecognized/unsupported value was given for compression.
InvalidDataException: If given stream does not support writing.
NotSupportedException: If the serialized document does not fit in a single array.
UnauthorizedAccessException: Specified file is read-only, or a permission issue occurred.
NbtFormatException: If one of the NbtCompound tags contained unnamed tags; or if an NbtList tag had Unknown list type and no elements.

SaveToFile(string, NbtCompression)

Saves this NBT file to a stream. Nothing is written to stream if RootTag is null.

public long SaveToFile(string fileName, NbtCompression compression)

Parameters

fileName string: File to write data to. May not be null.
compression NbtCompression: Compression mode to use for saving. May not be AutoDetect.

Returns

long: Number of bytes written to the file.

Exceptions

ArgumentNullException: fileName is null.
ArgumentException: If AutoDetect was given as the compression mode.
ArgumentOutOfRangeException: If an unrecognized/unsupported value was given for compression.
InvalidDataException: If given stream does not support writing.
IOException: If an I/O error occurred while creating the file.
UnauthorizedAccessException: Specified file is read-only, or a permission issue occurred.
NbtFormatException: If one of the NbtCompound tags contained unnamed tags; or if an NbtList tag had Unknown list type and no elements.

SaveToStream(Stream, NbtCompression)

Saves this NBT file to a stream. Nothing is written to stream if RootTag is null.

public long SaveToStream(Stream stream, NbtCompression compression)

Parameters

stream Stream: Stream to write data to. May not be null.
compression NbtCompression: Compression mode to use for saving. May not be AutoDetect.

Returns

long: Number of bytes written to the stream.

Exceptions

ArgumentNullException: stream is null.
ArgumentException: If AutoDetect was given as the compression mode.
ArgumentOutOfRangeException: If an unrecognized/unsupported value was given for compression.
InvalidDataException: If given stream does not support writing.
NbtFormatException: If RootTag is null; or if RootTag is unnamed; or if one of the NbtCompound tags contained unnamed tags; or if an NbtList tag had Unknown list type and no elements.

ToString()

Prints contents of the root tag, and any child tags, to a string.

public override string ToString()

Returns

string

ToString(string)

Prints contents of the root tag, and any child tags, to a string. Indents the string using multiples of the given indentation string.

public string ToString(string indentString)

Parameters

indentString string: String to be used for indentation.

Returns

string: A string representing contents of this tag, and all child tags (if any).

Exceptions

ArgumentNullException: indentString is null.

Table of Contents

Class NbtFile

Constructors

NbtFile()

NbtFile(string)

Parameters

Exceptions

NbtFile(NbtCompound)

Parameters

Exceptions

Properties

BigEndian

Property Value

BigEndianByDefault

Property Value

BufferSize

Property Value

Exceptions

DefaultBufferSize

Property Value

Exceptions

FileCompression

Property Value

FileName

Property Value

RootTag

Property Value

Exceptions

Methods

LoadFromBuffer(byte[], int, int, NbtCompression)

Parameters

Returns

Exceptions

LoadFromBuffer(byte[], int, int, NbtCompression, TagSelector?)

Parameters

Returns

Exceptions

LoadFromFile(string)

Parameters

Returns

Exceptions

LoadFromFile(string, NbtCompression, TagSelector?)

Parameters

Returns

Exceptions

LoadFromStream(Stream, NbtCompression)

Parameters

Returns

Exceptions

LoadFromStream(Stream, NbtCompression, TagSelector?)

Parameters

Returns

Exceptions

ReadRootTagName(Stream, NbtCompression, bool, int)

Parameters

Returns

Exceptions

ReadRootTagName(string)

Parameters

Returns

Exceptions

ReadRootTagName(string, NbtCompression, bool, int)

Parameters

Returns

Exceptions

SaveToBuffer(byte[], int, NbtCompression)

Parameters

Returns

Exceptions

SaveToBuffer(NbtCompression)

Parameters

Returns

Exceptions

SaveToFile(string, NbtCompression)

Parameters

Returns

Exceptions

SaveToStream(Stream, NbtCompression)

Parameters

Returns