Struct DataStreamWriter

Writes data in an endian format to serialize data.

Namespace: Unity.Collections
Assembly: Unity.Collections.dll
Syntax
[MovedFrom(true, "Unity.Networking.Transport", "Unity.Networking.Transport", null)]
public struct DataStreamWriter
Remarks

Data streams can be used to serialize data (e.g. over the network). The DataStreamWriter and DataStreamReader classes work together to serialize data for sending and then to deserialize when receiving.

DataStreamWriter writes data in the endian format native to the current machine architecture. For network byte order use the so named methods.
The reader can be used to deserialize the data from a NativeArray<byte>, writing data to a NativeArray<byte> and reading it back can be done like this:

using (var data = new NativeArray<byte>(16, Allocator.Persistent))
{
    var dataWriter = new DataStreamWriter(data);
    dataWriter.WriteInt(42);
    dataWriter.WriteInt(1234);
    // Length is the actual amount of data inside the writer,
    // Capacity is the total amount.
    var dataReader = new DataStreamReader(nativeArrayOfBytes.GetSubArray(0, dataWriter.Length));
    var myFirstInt = dataReader.ReadInt();
    var mySecondInt = dataReader.ReadInt();
}

There are a number of functions for various data types. If a copy of the writer is stored it can be used to overwrite the data later on. This is particularly useful when the size of the data is written at the start and you want to write it at the end when you know the value. IsLittleEndian

using (var data = new NativeArray<byte>(16, Allocator.Persistent))
{
    var dataWriter = new DataStreamWriter(data);
    // My header data
    var headerSizeMark = dataWriter;
    dataWriter.WriteUShort((ushort)0);
    var payloadSizeMark = dataWriter;
    dataWriter.WriteUShort((ushort)0);
    dataWriter.WriteInt(42);
    dataWriter.WriteInt(1234);
    var headerSize = data.Length;
    // Update header size to correct value
    headerSizeMark.WriteUShort((ushort)headerSize);
    // My payload data
    byte[] someBytes = Encoding.ASCII.GetBytes("some string");
    dataWriter.Write(someBytes, someBytes.Length);
    // Update payload size to correct value
    payloadSizeMark.WriteUShort((ushort)(dataWriter.Length - headerSize));
}

Constructors

DataStreamWriter(byte*, int)

Initializes a new instance of the DataStreamWriter struct with a memory we don't own

Declaration
public DataStreamWriter(byte* data, int length)
Parameters
Type Name Description
byte* data

Pointer to the data
int length

Length of the data

DataStreamWriter(int, AllocatorHandle)

Initializes a new instance of the DataStreamWriter struct.

Declaration
public DataStreamWriter(int length, AllocatorManager.AllocatorHandle allocator)
Parameters
Type Name Description
int length

The number of bytes available in the buffer.
AllocatorManager.AllocatorHandle allocator

The Allocator used to allocate the memory.

DataStreamWriter(NativeArray<byte>)

Initializes a new instance of the DataStreamWriter struct with a NativeArray<byte>

Declaration
public DataStreamWriter(NativeArray<byte> data)
Parameters
Type Name Description
NativeArray<byte> data

The buffer to attach to the DataStreamWriter.

Fields

m_SendHandleData

Used for sending data asynchronously.

Declaration
public IntPtr m_SendHandleData
Field Value
Type Description
IntPtr

Properties

Capacity

The total size of the data buffer, see Length for the size of space used in the buffer.

Declaration
public readonly int Capacity { get; }
Property Value
Type Description
int

HasFailedWrites

If there is a write failure this returns true. A failure might happen if an attempt is made to write more than there is capacity for.

Declaration
public readonly bool HasFailedWrites { get; }
Property Value
Type Description
bool

IsCreated

True if there is a valid data buffer present. This would be false if the writer was created with no arguments.

Declaration
public readonly bool IsCreated { get; }
Property Value
Type Description
bool

IsLittleEndian

Show the byte order in which the current computer architecture stores data.

Declaration
public static bool IsLittleEndian { get; }
Property Value
Type Description
bool
Remarks

Different computer architectures store data using different byte orders.

  • Big-endian: the most significant byte is at the left end of a word.
  • Little-endian: means the most significant byte is at the right end of a word.

Length

The size of the buffer used. See Capacity for the total size.

Declaration
public int Length { get; }
Property Value
Type Description
int

LengthInBits

The size of the buffer used in bits. See Length for the length in bytes.

Declaration
public int LengthInBits { get; }
Property Value
Type Description
int

Methods

AsNativeArray()

Convert internal data buffer to NativeArray for use in entities APIs.

Declaration
public NativeArray<byte> AsNativeArray()
Returns
Type Description
NativeArray<byte>

NativeArray representation of internal buffer.

Clear()

Moves the write position to the start of the data buffer used.

Declaration
public void Clear()

Flush()

Causes any buffered bits to be written to the data buffer. Note this needs to be invoked after using methods that writes directly to the bit buffer.

Declaration
public void Flush()

WriteByte(byte)

Writes an unsigned byte to the current stream and advances the stream position by one byte.

Declaration
public bool WriteByte(byte value)
Parameters
Type Name Description
byte value

The unsigned byte to write.
Returns
Type Description
bool

Whether the write was successful

WriteBytes(Span<byte>)

Copy Span of bytes into the writer's data buffer.

Declaration
public bool WriteBytes(Span<byte> value)
Parameters
Type Name Description
Span<byte> value

Source byte span
Returns
Type Description
bool

Whether the write was successful

WriteBytes(NativeArray<byte>)

Copy NativeArray of bytes into the writer's data buffer.

Declaration
public bool WriteBytes(NativeArray<byte> value)
Parameters
Type Name Description
NativeArray<byte> value

Source byte array
Returns
Type Description
bool

Whether the write was successful

WriteDouble(double)

Writes a 8-byte floating point value to the data stream.

Declaration
public bool WriteDouble(double value)
Parameters
Type Name Description
double value

The 8-byte floating point value to write.
Returns
Type Description
bool

Whether the write was successful

WriteFixedString128(FixedString128Bytes)

Writes a FixedString128Bytes value to the data stream.

Declaration
public bool WriteFixedString128(FixedString128Bytes str)
Parameters
Type Name Description
FixedString128Bytes str

The FixedString128Bytes to write.
Returns
Type Description
bool

Whether the write was successful

WriteFixedString32(FixedString32Bytes)

Writes a FixedString32Bytes value to the data stream.

Declaration
public bool WriteFixedString32(FixedString32Bytes str)
Parameters
Type Name Description
FixedString32Bytes str

The FixedString32Bytes to write.
Returns
Type Description
bool

Whether the write was successful

WriteFixedString4096(FixedString4096Bytes)

Writes a FixedString4096Bytes value to the data stream.

Declaration
public bool WriteFixedString4096(FixedString4096Bytes str)
Parameters
Type Name Description
FixedString4096Bytes str

The FixedString4096Bytes to write.
Returns
Type Description
bool

Whether the write was successful

WriteFixedString512(FixedString512Bytes)

Writes a FixedString512Bytes value to the data stream.

Declaration
public bool WriteFixedString512(FixedString512Bytes str)
Parameters
Type Name Description
FixedString512Bytes str

The FixedString512Bytes to write.
Returns
Type Description
bool

Whether the write was successful

WriteFixedString64(FixedString64Bytes)

Writes a FixedString64Bytes value to the data stream.

Declaration
public bool WriteFixedString64(FixedString64Bytes str)
Parameters
Type Name Description
FixedString64Bytes str

The FixedString64Bytes to write.
Returns
Type Description
bool

Whether the write was successful

WriteFloat(float)

Writes a 4-byte floating point value to the data stream.

Declaration
public bool WriteFloat(float value)
Parameters
Type Name Description
float value

The 4-byte floating point value to write.
Returns
Type Description
bool

Whether the write was successful

WriteInt(int)

Writes a 4-byte signed integer from the current stream and advances the current position of the stream by four bytes.

Declaration
public bool WriteInt(int value)
Parameters
Type Name Description
int value

The 4-byte signed integer to write.
Returns
Type Description
bool

Whether the write was successful

WriteIntNetworkByteOrder(int)

Writes a 4-byte signed integer from the current stream using Big-endian byte order and advances the current position of the stream by four bytes. If the current machine is in little-endian order, the byte order will be swapped.

Declaration
public bool WriteIntNetworkByteOrder(int value)
Parameters
Type Name Description
int value

The 4-byte signed integer to write.
Returns
Type Description
bool

Whether the write was successful

WriteLong(long)

Writes an 8-byte signed long from the stream and advances the current position of the stream by eight bytes.

Declaration
public bool WriteLong(long value)
Parameters
Type Name Description
long value

The 8-byte signed long to write.
Returns
Type Description
bool

Whether the write was successful

WritePackedDouble(double, in StreamCompressionModel)

Writes a 8-byte floating point value to the data stream using a StreamCompressionModel.

Declaration
public bool WritePackedDouble(double value, in StreamCompressionModel model)
Parameters
Type Name Description
double value

The 8-byte floating point value to write.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedDoubleDelta(double, double, in StreamCompressionModel)

Writes a 8-byte floating point value to the data stream.

If the data did not change a zero bit is prepended, otherwise a 1 bit is prepended. When reading back the data, the first bit is then checked for whether the data was changed or not.

Declaration
public bool WritePackedDoubleDelta(double value, double baseline, in StreamCompressionModel model)
Parameters
Type Name Description
double value

The current 8-byte floating point value.
double baseline

The previous 8-byte floating value, used to compute the diff.
StreamCompressionModel model

Not currently used.
Returns
Type Description
bool

Whether the write was successful

WritePackedFixedString128Delta(FixedString128Bytes, FixedString128Bytes, in StreamCompressionModel)

Writes a delta FixedString128Bytes value to the data stream using a StreamCompressionModel.

Declaration
public bool WritePackedFixedString128Delta(FixedString128Bytes str, FixedString128Bytes baseline, in StreamCompressionModel model)
Parameters
Type Name Description
FixedString128Bytes str

The current FixedString128Bytes value.
FixedString128Bytes baseline

The previous FixedString128Bytes value, used to compute the diff.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedFixedString32Delta(FixedString32Bytes, FixedString32Bytes, in StreamCompressionModel)

Writes a FixedString32Bytes delta value to the data stream using a StreamCompressionModel.

Declaration
public bool WritePackedFixedString32Delta(FixedString32Bytes str, FixedString32Bytes baseline, in StreamCompressionModel model)
Parameters
Type Name Description
FixedString32Bytes str

The current FixedString32Bytes value.
FixedString32Bytes baseline

The previous FixedString32Bytes value, used to compute the diff.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedFixedString4096Delta(FixedString4096Bytes, FixedString4096Bytes, in StreamCompressionModel)

Writes a delta FixedString4096Bytes value to the data stream using a StreamCompressionModel.

Declaration
public bool WritePackedFixedString4096Delta(FixedString4096Bytes str, FixedString4096Bytes baseline, in StreamCompressionModel model)
Parameters
Type Name Description
FixedString4096Bytes str

The current FixedString4096Bytes value.
FixedString4096Bytes baseline

The previous FixedString4096Bytes value, used to compute the diff.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedFixedString512Delta(FixedString512Bytes, FixedString512Bytes, in StreamCompressionModel)

Writes a delta FixedString512Bytes value to the data stream using a StreamCompressionModel.

Declaration
public bool WritePackedFixedString512Delta(FixedString512Bytes str, FixedString512Bytes baseline, in StreamCompressionModel model)
Parameters
Type Name Description
FixedString512Bytes str

The current FixedString512Bytes value.
FixedString512Bytes baseline

The previous FixedString512Bytes value, used to compute the diff.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedFixedString64Delta(FixedString64Bytes, FixedString64Bytes, in StreamCompressionModel)

Writes a delta FixedString64Bytes value to the data stream using a StreamCompressionModel.

Declaration
public bool WritePackedFixedString64Delta(FixedString64Bytes str, FixedString64Bytes baseline, in StreamCompressionModel model)
Parameters
Type Name Description
FixedString64Bytes str

The current FixedString64Bytes value.
FixedString64Bytes baseline

The previous FixedString64Bytes value, used to compute the diff.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedFloat(float, in StreamCompressionModel)

Writes a 4-byte floating point value to the data stream using a StreamCompressionModel.

Declaration
public bool WritePackedFloat(float value, in StreamCompressionModel model)
Parameters
Type Name Description
float value

The 4-byte floating point value to write.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedFloatDelta(float, float, in StreamCompressionModel)

Writes a 4-byte floating point value to the data stream.

If the data did not change a zero bit is prepended, otherwise a 1 bit is prepended. When reading back the data, the first bit is then checked for whether the data was changed or not.

Declaration
public bool WritePackedFloatDelta(float value, float baseline, in StreamCompressionModel model)
Parameters
Type Name Description
float value

The current 4-byte floating point value.
float baseline

The previous 4-byte floating value, used to compute the diff.
StreamCompressionModel model

Not currently used.
Returns
Type Description
bool

Whether the write was successful

WritePackedInt(int, in StreamCompressionModel)

Writes a 4-byte signed integer value to the data stream using a StreamCompressionModel. Negative values are interleaved between positive values, i.e. (0, -1, 1, -2, 2)

Declaration
public bool WritePackedInt(int value, in StreamCompressionModel model)
Parameters
Type Name Description
int value

The 4-byte signed integer to write.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedIntDelta(int, int, in StreamCompressionModel)

Writes a delta 4-byte signed integer value to the data stream using a StreamCompressionModel.

Declaration
public bool WritePackedIntDelta(int value, int baseline, in StreamCompressionModel model)
Parameters
Type Name Description
int value

The current 4-byte signed integer value.
int baseline

The previous 4-byte signed integer value, used to compute the diff.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedLong(long, in StreamCompressionModel)

Writes a 8-byte signed long value to the data stream using a StreamCompressionModel.

Declaration
public bool WritePackedLong(long value, in StreamCompressionModel model)
Parameters
Type Name Description
long value

The 8-byte signed long to write.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedLongDelta(long, long, in StreamCompressionModel)

Writes a delta 8-byte signed long value to the data stream using a StreamCompressionModel.

Declaration
public bool WritePackedLongDelta(long value, long baseline, in StreamCompressionModel model)
Parameters
Type Name Description
long value

The current 8-byte signed long value.
long baseline

The previous 8-byte signed long value, used to compute the diff.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedUInt(uint, in StreamCompressionModel)

Writes a 4-byte unsigned integer value to the data stream using a StreamCompressionModel.

Declaration
public bool WritePackedUInt(uint value, in StreamCompressionModel model)
Parameters
Type Name Description
uint value

The 4-byte unsigned integer to write.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedUIntDelta(uint, uint, in StreamCompressionModel)

Writes a delta 4-byte unsigned integer value to the data stream using a StreamCompressionModel. Note that the Uint values are cast to an Int after computing the diff.

Declaration
public bool WritePackedUIntDelta(uint value, uint baseline, in StreamCompressionModel model)
Parameters
Type Name Description
uint value

The current 4-byte unsigned integer value.
uint baseline

The previous 4-byte unsigned integer value, used to compute the diff.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedULong(ulong, in StreamCompressionModel)

Writes an 8-byte unsigned long value to the data stream using a StreamCompressionModel.

Declaration
public bool WritePackedULong(ulong value, in StreamCompressionModel model)
Parameters
Type Name Description
ulong value

The 8-byte unsigned long to write.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WritePackedULongDelta(ulong, ulong, in StreamCompressionModel)

Writes a delta 8-byte unsigned long value to the data stream using a StreamCompressionModel. Note that the unsigned long values are cast to a signed long after computing the diff.

Declaration
public bool WritePackedULongDelta(ulong value, ulong baseline, in StreamCompressionModel model)
Parameters
Type Name Description
ulong value

The current 8-byte unsigned long value.
ulong baseline

The previous 8-byte unsigned long, used to compute the diff.
StreamCompressionModel model

StreamCompressionModel model for writing value in a packed manner.
Returns
Type Description
bool

Whether the write was successful

WriteRawBits(uint, int)

Appends a specified number of bits to the data stream.

Declaration
public bool WriteRawBits(uint value, int numbits)
Parameters
Type Name Description
uint value

The bits to write.
int numbits

A positive number of bytes to write.
Returns
Type Description
bool

Whether the write was successful

WriteShort(short)

Writes a 2-byte signed short to the current stream and advances the stream position by two bytes.

Declaration
public bool WriteShort(short value)
Parameters
Type Name Description
short value

The 2-byte signed short to write.
Returns
Type Description
bool

Whether the write was successful

WriteShortNetworkByteOrder(short)

Writes a 2-byte signed short to the current stream using Big-endian byte order and advances the stream position by two bytes. If the stream is in little-endian order, the byte order will be swapped.

Declaration
public bool WriteShortNetworkByteOrder(short value)
Parameters
Type Name Description
short value

The 2-byte signed short to write.
Returns
Type Description
bool

Whether the write was successful

WriteUInt(uint)

Reads a 4-byte unsigned integer from the current stream and advances the current position of the stream by four bytes.

Declaration
public bool WriteUInt(uint value)
Parameters
Type Name Description
uint value

The 4-byte unsigned integer to write.
Returns
Type Description
bool

Whether the write was successful

WriteUIntNetworkByteOrder(uint)

Writes a 4-byte unsigned integer from the current stream using Big-endian byte order and advances the current position of the stream by four bytes. If the stream is in little-endian order, the byte order will be swapped.

Declaration
public bool WriteUIntNetworkByteOrder(uint value)
Parameters
Type Name Description
uint value

The 4-byte unsigned integer to write.
Returns
Type Description
bool

Whether the write was successful

WriteULong(ulong)

Reads an 8-byte unsigned long from the stream and advances the current position of the stream by eight bytes.

Declaration
public bool WriteULong(ulong value)
Parameters
Type Name Description
ulong value

The 8-byte unsigned long to write.
Returns
Type Description
bool

Whether the write was successful

WriteUShort(ushort)

Writes a 2-byte unsigned short to the current stream and advances the stream position by two bytes.

Declaration
public bool WriteUShort(ushort value)
Parameters
Type Name Description
ushort value

The 2-byte unsigned short to write.
Returns
Type Description
bool

Whether the write was successful

WriteUShortNetworkByteOrder(ushort)

Writes a 2-byte unsigned short to the current stream using Big-endian byte order and advances the stream position by two bytes. If the stream is in little-endian order, the byte order will be swapped.

Declaration
public bool WriteUShortNetworkByteOrder(ushort value)
Parameters
Type Name Description
ushort value

The 2-byte unsigned short to write.
Returns
Type Description
bool

Whether the write was successful

Extension Methods