Class NbtWriter

Namespace: fNbt

Assembly: fNbt.dll

An efficient writer for writing NBT data directly to streams. Each instance of NbtWriter writes one complete file. NbtWriter enforces the structural rules of the NBT format, except that it does not check for duplicate tag names within a compound. The flavor's own restrictions, such as its permitted tag types and string ceilings, are enforced only while ValidateOnWrite is on.

public sealed class NbtWriter

Inheritance: object

NbtWriter

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Every check the writer can make up front runs before any byte is written or a list slot consumed, so a refused call leaves the writer as it was. A write that fails after committing bytes, an I/O error for example, leaves the writer in an error state where every later call throws NbtFormatException. See IsInErrorState.

Constructors

NbtWriter(Stream, string)

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

public NbtWriter(Stream stream, string rootTagName)

Parameters

stream Stream: Stream to write to.
rootTagName string: Name to give to the root tag (written immediately).

Exceptions

ArgumentNullException: stream or rootTagName is null.
ArgumentException: stream is not writable.

NbtWriter(Stream, string, bool)

Initializes a new instance of the NbtWriter class.

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

Parameters

stream Stream: Stream to write to.
rootTagName string: Name to give to the root tag (written immediately).
bigEndian bool: Whether NBT data should be in Big-Endian encoding.

Exceptions

ArgumentNullException: stream or rootTagName is null.
ArgumentException: stream is not writable.

NbtWriter(Stream, string, NbtFlavor)

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

public NbtWriter(Stream stream, string rootTagName, NbtFlavor flavor)

Parameters

stream Stream: Stream to write to.
rootTagName string: Name to give to the root tag (written immediately).
flavor NbtFlavor: Encoding to write with.

Exceptions

ArgumentNullException: stream, rootTagName, or flavor is null.
ArgumentException: stream is not writable; or the flavor has no root name (use NbtCodec for those).

NbtWriter(Stream, string, NbtOptions)

Initializes a new instance of the NbtWriter class with the given options. When write validation is on, the flavor's tag-type range and string ceiling are enforced as tags are written.

public NbtWriter(Stream stream, string rootTagName, NbtOptions options)

Parameters

stream Stream: Stream to write to.
rootTagName string: Name to give to the root tag (written immediately).
options NbtOptions: Settings to use, resolved here. May not be null.

Exceptions

ArgumentNullException: stream, rootTagName, options, or the options' Flavor is null.
ArgumentException: stream is not writable; or the options' flavor has no root name (use NbtCodec for those).
ArgumentOutOfRangeException: MaxAllocation is zero or negative.

Properties

BaseStream

Gets the underlying stream of the NbtWriter, flushing buffered output first.

public Stream BaseStream { get; }

Property Value

Stream

Exceptions

IOException: Flushing the stream failed.

Flavor

The flavor this writer encodes with, fixed at construction.

public NbtFlavor Flavor { get; }

Property Value

NbtFlavor

IsDone

Gets whether the root tag has been closed. No more tags may be written after the root tag has been closed.

public bool IsDone { get; }

Property Value

bool

IsInErrorState

Gets whether an earlier write failed after emitting bytes, an I/O error for example. The document cannot be finished: every later write, End, and Finish() call throws NbtFormatException, and the partial output should be discarded. A write refused before it emitted anything leaves the writer usable and does not set this.

public bool IsInErrorState { get; }

Property Value

bool

Remarks

A stream that reads this from inside its own Write sees true for the write in flight: that state and a failure share one sentinel.

Methods

BeginCompound()

Begins an unnamed compound tag.

public void BeginCompound()

Exceptions

NbtFormatException: No more tags can be written -OR- a named compound tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded -OR- tags are nested more than 512 levels deep.

BeginCompound(string)

Begins a named compound tag.

public void BeginCompound(string tagName)

Parameters

tagName string: Name to give to this compound tag. May not be null.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed compound tag was expected -OR- a tag of a different type was expected -OR- tags are nested more than 512 levels deep.

BeginList(string, NbtTagType, int)

Begins a named list tag.

public void BeginList(string tagName, NbtTagType elementType, int size)

Parameters

tagName string: Name to give to this list tag. May not be null.
elementType NbtTagType: Type of elements of this list.
size int: Number of elements in this list. Must not be negative.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed list tag was expected -OR- a tag of a different type was expected -OR- tags are nested more than 512 levels deep -OR- enabled validation does not permit elementType for the flavor.
ArgumentOutOfRangeException: size is negative -OR- elementType is not a valid list element type (End is allowed only when size is 0).

BeginList(NbtTagType, int)

Begins an unnamed list tag.

public void BeginList(NbtTagType elementType, int size)

Parameters

elementType NbtTagType: Type of elements of this list.
size int: Number of elements in this list. Must not be negative.

Exceptions

NbtFormatException: No more tags can be written -OR- a named list tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded -OR- tags are nested more than 512 levels deep -OR- enabled validation does not permit elementType for the flavor.
ArgumentOutOfRangeException: size is negative -OR- elementType is not a valid list element type (End is allowed only when size is 0).

EndCompound()

Ends a compound tag.

public void EndCompound()

Exceptions

NbtFormatException: Not currently in a compound -OR- an earlier write failed partway through.

EndList()

Ends a list tag.

public void EndList()

Exceptions

NbtFormatException: Not currently in a list -OR- not all list elements have been written yet -OR- an earlier write failed partway through.

Finish()

Ensures that file has been written in its entirety, with no tags left open. This method is for verification only, and does not actually write any data. Calling this method is optional (but probably a good idea, to catch any usage errors).

public void Finish()

Exceptions

NbtFormatException: Not all tags have been closed yet -OR- an earlier write failed partway through.

WriteByte(byte)

Writes an unnamed byte tag.

public void WriteByte(byte value)

Parameters

value byte: The unsigned byte to write.

Exceptions

NbtFormatException: No more tags can be written -OR- a named byte tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded.

WriteByte(string, byte)

Writes a named byte tag.

public void WriteByte(string tagName, byte value)

Parameters

tagName string: Name to give to this byte tag. May not be null.
value byte: The unsigned byte to write.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed byte tag was expected -OR- a tag of a different type was expected.

WriteByteArray(byte[])

Writes an unnamed byte array tag, copying data from an array.

public void WriteByteArray(byte[] data)

Parameters

data byte[]: A byte array containing the data to write.

Exceptions

NbtFormatException: No more tags can be written -OR- a named byte array tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded.
ArgumentNullException: data is null

WriteByteArray(byte[], int, int)

Writes an unnamed byte array tag, copying data from an array.

public void WriteByteArray(byte[] data, int offset, int count)

Parameters

data byte[]: A byte array containing the data to write.
offset int: The starting point in data at which to begin writing. Must not be negative.
count int: The number of bytes to write. Must not be negative.

Exceptions

NbtFormatException: No more tags can be written -OR- a named byte array tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded.
ArgumentOutOfRangeException: offset or count is negative.
ArgumentNullException: data is null
ArgumentException: count is greater than offset subtracted from the array length.

WriteByteArray(Stream, int)

Writes an unnamed byte array tag, copying data from a stream.

public void WriteByteArray(Stream dataSource, int count)

Parameters

dataSource Stream: A Stream from which data will be copied.
count int: The number of bytes to write. Must not be negative.

Remarks

A temporary buffer will be allocated, of size up to 8192 bytes. To manually specify a buffer, use one of the other WriteByteArray() overloads.

Exceptions

NbtFormatException: No more tags can be written -OR- a named byte array tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded.
ArgumentOutOfRangeException: count is negative.
ArgumentNullException: dataSource is null.
ArgumentException: Given stream does not support reading.

WriteByteArray(Stream, int, byte[])

Writes an unnamed byte array tag, copying data from a stream.

public void WriteByteArray(Stream dataSource, int count, byte[] buffer)

Parameters

dataSource Stream: A Stream from which data will be copied.
count int: The number of bytes to write. Must not be negative.
buffer byte[]: Buffer to use for copying. Size must be greater than 0. Must not be null.

Exceptions

NbtFormatException: No more tags can be written -OR- a named byte array tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded.
ArgumentOutOfRangeException: count is negative.
ArgumentNullException: dataSource is null.
ArgumentException: Given stream does not support reading -OR- buffer size is 0.

WriteByteArray(string, byte[])

Writes a named byte array tag, copying data from an array.

public void WriteByteArray(string tagName, byte[] data)

Parameters

tagName string: Name to give to this byte array tag. May not be null.
data byte[]: A byte array containing the data to write.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed byte array tag was expected -OR- a tag of a different type was expected.
ArgumentNullException: tagName or data is null

WriteByteArray(string, byte[], int, int)

Writes a named byte array tag, copying data from an array.

public void WriteByteArray(string tagName, byte[] data, int offset, int count)

Parameters

tagName string: Name to give to this byte array tag. May not be null.
data byte[]: A byte array containing the data to write.
offset int: The starting point in data at which to begin writing. Must not be negative.
count int: The number of bytes to write. Must not be negative.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed byte array tag was expected -OR- a tag of a different type was expected.
ArgumentOutOfRangeException: offset or count is negative.
ArgumentNullException: tagName or data is null
ArgumentException: count is greater than offset subtracted from the array length.

WriteByteArray(string, Stream, int)

Writes a named byte array tag, copying data from a stream.

public void WriteByteArray(string tagName, Stream dataSource, int count)

Parameters

tagName string: Name to give to this byte array tag. May not be null.
dataSource Stream: A Stream from which data will be copied.
count int: The number of bytes to write. Must not be negative.

Remarks

A temporary buffer will be allocated, of size up to 8192 bytes. To manually specify a buffer, use one of the other WriteByteArray() overloads.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed byte array tag was expected -OR- a tag of a different type was expected.
ArgumentOutOfRangeException: count is negative.
ArgumentNullException: dataSource is null.
ArgumentException: Given stream does not support reading.

WriteByteArray(string, Stream, int, byte[])

Writes a named byte array tag, copying data from a stream.

public void WriteByteArray(string tagName, Stream dataSource, int count, byte[] buffer)

Parameters

tagName string: Name to give to this byte array tag. May not be null.
dataSource Stream: A Stream from which data will be copied.
count int: The number of bytes to write. Must not be negative.
buffer byte[]: Buffer to use for copying. Size must be greater than 0. Must not be null.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed byte array tag was expected -OR- a tag of a different type was expected.
ArgumentOutOfRangeException: count is negative.
ArgumentNullException: dataSource is null.
ArgumentException: Given stream does not support reading -OR- buffer size is 0.

WriteDouble(double)

Writes an unnamed double tag.

public void WriteDouble(double value)

Parameters

value double: The eight-byte floating-point value to write.

Exceptions

NbtFormatException: No more tags can be written -OR- a named double tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded.

WriteDouble(string, double)

Writes a named double tag.

public void WriteDouble(string tagName, double value)

Parameters

tagName string: Name to give to this double tag. May not be null.
value double: The eight-byte floating-point value to write.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed double tag was expected -OR- a tag of a different type was expected.

WriteFloat(float)

Writes an unnamed float tag.

public void WriteFloat(float value)

Parameters

value float: The four-byte floating-point value to write.

Exceptions

NbtFormatException: No more tags can be written -OR- a named float tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded.

WriteFloat(string, float)

Writes a named float tag.

public void WriteFloat(string tagName, float value)

Parameters

tagName string: Name to give to this float tag. May not be null.
value float: The four-byte floating-point value to write.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed float tag was expected -OR- a tag of a different type was expected.

WriteInt(int)

Writes an unnamed int tag.

public void WriteInt(int value)

Parameters

value int: The four-byte signed integer to write.

Exceptions

NbtFormatException: No more tags can be written -OR- a named int tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded.

WriteInt(string, int)

Writes a named int tag.

public void WriteInt(string tagName, int value)

Parameters

tagName string: Name to give to this int tag. May not be null.
value int: The four-byte signed integer to write.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed int tag was expected -OR- a tag of a different type was expected.

WriteIntArray(int[])

Writes an unnamed int array tag, copying data from an array.

public void WriteIntArray(int[] data)

Parameters

data int[]: An int array containing the data to write.

Exceptions

NbtFormatException: No more tags can be written -OR- a named int array tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded -OR- enabled validation does not permit TAG_Int_Array for the flavor.
ArgumentNullException: data is null

WriteIntArray(int[], int, int)

Writes an unnamed int array tag, copying data from an array.

public void WriteIntArray(int[] data, int offset, int count)

Parameters

data int[]: An int array containing the data to write.
offset int: The starting point in data at which to begin writing. Must not be negative.
count int: The number of elements to write. Must not be negative.

Exceptions

NbtFormatException: No more tags can be written -OR- a named int array tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded -OR- enabled validation does not permit TAG_Int_Array for the flavor.
ArgumentOutOfRangeException: offset or count is negative.
ArgumentNullException: data is null
ArgumentException: count is greater than offset subtracted from the array length.

WriteIntArray(string, int[])

Writes a named int array tag, copying data from an array.

public void WriteIntArray(string tagName, int[] data)

Parameters

tagName string: Name to give to this int array tag. May not be null.
data int[]: An int array containing the data to write.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed int array tag was expected -OR- a tag of a different type was expected -OR- enabled validation does not permit TAG_Int_Array for the flavor.
ArgumentNullException: tagName or data is null

WriteIntArray(string, int[], int, int)

Writes a named int array tag, copying data from an array.

public void WriteIntArray(string tagName, int[] data, int offset, int count)

Parameters

tagName string: Name to give to this int array tag. May not be null.
data int[]: An int array containing the data to write.
offset int: The starting point in data at which to begin writing. Must not be negative.
count int: The number of elements to write. Must not be negative.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed int array tag was expected -OR- a tag of a different type was expected -OR- enabled validation does not permit TAG_Int_Array for the flavor.
ArgumentOutOfRangeException: offset or count is negative.
ArgumentNullException: tagName or data is null
ArgumentException: count is greater than offset subtracted from the array length.

WriteLong(long)

Writes an unnamed long tag.

public void WriteLong(long value)

Parameters

value long: The eight-byte signed integer to write.

Exceptions

NbtFormatException: No more tags can be written -OR- a named long tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded.

WriteLong(string, long)

Writes a named long tag.

public void WriteLong(string tagName, long value)

Parameters

tagName string: Name to give to this long tag. May not be null.
value long: The eight-byte signed integer to write.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed long tag was expected -OR- a tag of a different type was expected.

WriteLongArray(long[])

Writes an unnamed long array tag, copying data from an array.

public void WriteLongArray(long[] data)

Parameters

data long[]: A long array containing the data to write.

Exceptions

NbtFormatException: No more tags can be written -OR- a named long array tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded -OR- enabled validation does not permit TAG_Long_Array for the flavor.
ArgumentNullException: data is null

WriteLongArray(long[], int, int)

Writes an unnamed long array tag, copying data from an array.

public void WriteLongArray(long[] data, int offset, int count)

Parameters

data long[]: A long array containing the data to write.
offset int: The starting point in data at which to begin writing. Must not be negative.
count int: The number of elements to write. Must not be negative.

Exceptions

NbtFormatException: No more tags can be written -OR- a named long array tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded -OR- enabled validation does not permit TAG_Long_Array for the flavor.
ArgumentOutOfRangeException: offset or count is negative.
ArgumentNullException: data is null
ArgumentException: count is greater than offset subtracted from the array length.

WriteLongArray(string, long[])

Writes a named long array tag, copying data from an array.

public void WriteLongArray(string tagName, long[] data)

Parameters

tagName string: Name to give to this long array tag. May not be null.
data long[]: A long array containing the data to write.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed long array tag was expected -OR- a tag of a different type was expected -OR- enabled validation does not permit TAG_Long_Array for the flavor.
ArgumentNullException: tagName or data is null

WriteLongArray(string, long[], int, int)

Writes a named long array tag, copying data from an array.

public void WriteLongArray(string tagName, long[] data, int offset, int count)

Parameters

tagName string: Name to give to this long array tag. May not be null.
data long[]: A long array containing the data to write.
offset int: The starting point in data at which to begin writing. Must not be negative.
count int: The number of elements to write. Must not be negative.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed long array tag was expected -OR- a tag of a different type was expected -OR- enabled validation does not permit TAG_Long_Array for the flavor.
ArgumentOutOfRangeException: offset or count is negative.
ArgumentNullException: tagName or data is null
ArgumentException: count is greater than offset subtracted from the array length.

WriteShort(short)

Writes an unnamed short tag.

public void WriteShort(short value)

Parameters

value short: The two-byte signed integer to write.

Exceptions

NbtFormatException: No more tags can be written -OR- a named short tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded.

WriteShort(string, short)

Writes a named short tag.

public void WriteShort(string tagName, short value)

Parameters

tagName string: Name to give to this short tag. May not be null.
value short: The two-byte signed integer to write.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed short tag was expected -OR- a tag of a different type was expected.

WriteString(string)

Writes an unnamed string tag.

public void WriteString(string value)

Parameters

value string: The string to write.

Exceptions

NbtFormatException: No more tags can be written -OR- a named string tag was expected -OR- a tag of a different type was expected -OR- the size of a parent list has been exceeded -OR- value is longer than the flavor's limit (65,535 bytes for the Java flavors).

WriteString(string, string)

Writes a named string tag.

public void WriteString(string tagName, string value)

Parameters

tagName string: Name to give to this string tag. May not be null.
value string: The string to write.

Exceptions

NbtFormatException: No more tags can be written -OR- an unnamed string tag was expected -OR- a tag of a different type was expected -OR- value is longer than the flavor's limit (65,535 bytes for the Java flavors).

WriteTag(NbtTag)

Writes a NbtTag object, and all of its child tags, to stream. Use this method sparingly with NbtWriter -- constructing NbtTag objects defeats the purpose of this class. If you already have lots of NbtTag objects, you might as well use NbtFile to write them all at once.

public void WriteTag(NbtTag tag)

Parameters

tag NbtTag: Tag to write. Must not be null.

Remarks

With write validation on for a flavor with restrictions, the whole tree is checked before anything is written. Otherwise a tree that is too deep or holds an overlong string fails partway through and leaves the writer failed.

Exceptions

NbtFormatException: No more tags can be written -OR- given tag is unacceptable at this time -OR- its tree, together with the containers currently open, is nested more than 512 levels deep -OR- a string inside it is longer than the flavor's limit (65,535 bytes for the Java flavors) -OR- enabled validation rejects a tag type or string length inside it for the flavor -OR- an earlier write failed partway through.
ArgumentNullException: tag is null

Table of Contents

Class NbtWriter

Remarks

Constructors

NbtWriter(Stream, string)

Parameters

Exceptions

NbtWriter(Stream, string, bool)

Parameters

Exceptions

NbtWriter(Stream, string, NbtFlavor)

Parameters

Exceptions

NbtWriter(Stream, string, NbtOptions)

Parameters

Exceptions

Properties

BaseStream

Property Value

Exceptions

Flavor

Property Value

IsDone

Property Value

IsInErrorState

Property Value

Remarks

Methods

BeginCompound()

Exceptions

BeginCompound(string)

Parameters

Exceptions

BeginList(string, NbtTagType, int)

Parameters

Exceptions

BeginList(NbtTagType, int)

Parameters

Exceptions

EndCompound()

Exceptions

EndList()

Exceptions

Finish()

Exceptions

WriteByte(byte)

Parameters

Exceptions

WriteByte(string, byte)

Parameters

Exceptions

WriteByteArray(byte[])

Parameters

Exceptions

WriteByteArray(byte[], int, int)

Parameters

Exceptions

WriteByteArray(Stream, int)

Parameters

Remarks

Exceptions

WriteByteArray(Stream, int, byte[])

Parameters

Exceptions

WriteByteArray(string, byte[])

Parameters

Exceptions

WriteByteArray(string, byte[], int, int)

Parameters

Exceptions

WriteByteArray(string, Stream, int)

Parameters

Remarks

Exceptions

WriteByteArray(string, Stream, int, byte[])

Parameters

Exceptions

WriteDouble(double)

Parameters

Exceptions