Class SerializationWriter

A SerializationWriter instance is used to store values and objects in a byte array.

Once an instance is created, use the various methods to store the required data. ToArray() will return a byte[] containing all of the data required for deserialization. This can be stored in the SerializationInfo parameter in an ISerializable.GetObjectData() method.

As an alternative to ToArray(), if you want to apply some post-processing to the serialized bytes, such as compression, call AppendTokenTables first to ensure that the string and object token tables are appended to the stream, and then cast BaseStream to MemoryStream. You can then access the MemoryStream's internal buffer as follows: 

writer.AppendTokenTables();
         MemoryStream stream = (MemoryStream) writer.BaseStream;
         serializedData = MiniLZO.Compress(stream.GetBuffer(), (int) stream.Length);
Inheritance
object
BinaryWriter
SerializationWriter
Implements
Inherited Members
Namespace: SuperOffice.IO
Assembly: SoCore.dll
Syntax
public sealed class SerializationWriter : BinaryWriter, IDisposable

Constructors

SerializationWriter()

Creates a FastSerializer with the Default Capacity (1kb)

Declaration
public SerializationWriter()

SerializationWriter(int)

Creates a FastSerializer with the specified capacity

Declaration
public SerializationWriter(int capacity)
Parameters
Type Name Description
int capacity

Fields

DefaultCapacity

Default capacity for the underlying MemoryStream

Declaration
public static int DefaultCapacity
Field Value
Type Description
int

DefaultOptimizeForSize

The Default setting for the OptimizeForSize property.

Declaration
public static bool DefaultOptimizeForSize
Field Value
Type Description
bool

DefaultPreserveDecimalScale

The Default setting for the PreserveDecimalScale property.

Declaration
public static bool DefaultPreserveDecimalScale
Field Value
Type Description
bool

HighestOptimizable16BitValue

Holds the highest Int16 that can be optimized into less than the normal 2 bytes

Declaration
public const short HighestOptimizable16BitValue = 127
Field Value
Type Description
short

HighestOptimizable32BitValue

Holds the highest Int32 that can be optimized into less than the normal 4 bytes

Declaration
public const int HighestOptimizable32BitValue = 2097151
Field Value
Type Description
int

HighestOptimizable64BitValue

Holds the highest Int64 that can be optimized into less than the normal 8 bytes

Declaration
public const long HighestOptimizable64BitValue = 562949953421311
Field Value
Type Description
long

Properties

OptimizeForSize

Gets or Sets a boolean flag to indicate whether to optimize for size (default) by storing data as packed bits or sections where possible. Setting this value to false will turn off this optimization and store data directly which increases the speed. Note: This only affects optimization of data passed to the WriteObject method and direct calls to the WriteOptimized methods will always pack data into the smallest space where possible.

Declaration
public bool OptimizeForSize { get; set; }
Property Value
Type Description
bool

PreserveDecimalScale

Gets or Sets a boolean flag to indicate whether to preserve the scale within a Decimal value when it would have no effect on the represented value. Note: a 2m value and a 2.00m value represent the same value but internally they are stored differently - the former has a value of 2 and a scale of 0 and the latter has a value of 200 and a scale of 2. The scaling factor also preserves any trailing zeroes in a Decimal number. Trailing zeroes do not affect the value of a Decimal number in arithmetic or comparison operations. However, trailing zeroes can be revealed by the ToString method if an appropriate format string is applied. From a serialization point of view, the former will take 2 bytes whereas the latter would take 4 bytes, therefore it is preferable to not save the scale where it doesn't affect the represented value.

Declaration
public bool PreserveDecimalScale { get; set; }
Property Value
Type Description
bool

TypeSurrogates

Holds a list of optional IFastSerializationTypeSurrogate instances which SerializationWriter and SerializationReader will use to serialize objects not directly supported. It is important to use the same list on both client and server ends to ensure that the same surrogated-types are supported.

Declaration
public static ArrayList TypeSurrogates { get; }
Property Value
Type Description
ArrayList

Methods

AppendTokenTables()

Writes the contents of the string and object token tables into the stream. Also write the starting offset into the first 4 bytes of the stream. Notes: Called automatically by ToArray(). Can be used to ensure that the complete graph is written before using an alternate technique of extracting a Byte[] such as using compression on the underlying stream.

Declaration
public int AppendTokenTables()
Returns
Type Description
int

The length of the string and object tables.

DumpTypeUsage()

A SerializationWriter instance is used to store values and objects in a byte array.

Once an instance is created, use the various methods to store the required data. ToArray() will return a byte[] containing all of the data required for deserialization. This can be stored in the SerializationInfo parameter in an ISerializable.GetObjectData() method.

As an alternative to ToArray(), if you want to apply some post-processing to the serialized bytes, such as compression, call AppendTokenTables first to ensure that the string and object token tables are appended to the stream, and then cast BaseStream to MemoryStream. You can then access the MemoryStream's internal buffer as follows: 

writer.AppendTokenTables();
         MemoryStream stream = (MemoryStream) writer.BaseStream;
         serializedData = MiniLZO.Compress(stream.GetBuffer(), (int) stream.Length);
Declaration
[Conditional("DEBUG")]
public void DumpTypeUsage()

ToArray()

Returns a byte[] containing all of the serialized data.

The current implementation has the data in 3 sections:

  1. A 4 byte Int32 giving the offset to the 3rd section.
  2. The main serialized data.
  3. The serialized string tokenization lists and object tokenization lists.

Only call this method once all of the data has been serialized.

This method appends all of the tokenized data (string and object) to the end of the stream and ensures that the first four bytes reflect the offset of the tokenized data so that it can be deserialized first. This is the reason for requiring a rewindable stream.

Future implementations may also allow the serialized data to be accessed via 2 byte[] arrays. This would remove the requirement for a rewindable stream opening the possibility of streaming the serialized data directly over the network allowing simultaneous of partially simultaneous deserialization.

Declaration
public byte[] ToArray()
Returns
Type Description
byte[]

A byte[] containing all serialized data.

ToStream()

Returns a Stream containing all of the serialized data.

Declaration
public Stream ToStream()
Returns
Type Description
Stream

Stream containing all serialized data

Write(IOwnedDataSerializable, object)

Allows any object implementing IOwnedDataSerializable to serialize itself into this SerializationWriter. A context may also be used to give the object an indication of what data to store. As an example, using a BitVector32 gives a list of flags and the object can conditionally store data depending on those flags.

Declaration
public void Write(IOwnedDataSerializable target, object context)
Parameters
Type Name Description
IOwnedDataSerializable target

The IOwnedDataSerializable object to ask for owned data
object context

An arbtritrary object but BitVector32 recommended

Write(bool[])

Writes a Boolean[] into the stream. Notes: A null or empty array will take 1 byte. Calls WriteOptimized(Boolean[]).

Declaration
public void Write(bool[] values)
Parameters
Type Name Description
bool[] values

The Boolean[] to store.

Write(byte[])

Writes a Byte[] into the stream. Notes: A null or empty array will take 1 byte.

Declaration
public override void Write(byte[] values)
Parameters
Type Name Description
byte[] values

The Byte[] to store.
Overrides

Write(char[])

Writes a Char[] into the stream. Notes: A null or empty array will take 1 byte.

Declaration
public override void Write(char[] values)
Parameters
Type Name Description
char[] values

The Char[] to store.
Overrides

Write(ArrayList)

Writes an ArrayList into the stream using the fewest number of bytes possible. Stored Size: 1 byte upwards depending on data content Notes: A null Arraylist takes 1 byte. An empty ArrayList takes 2 bytes. The contents are stored using WriteOptimized(ArrayList) which should be used if the ArrayList is guaranteed never to be null.

Declaration
public void Write(ArrayList value)
Parameters
Type Name Description
ArrayList value

The ArrayList to store.

Write(BitArray)

Writes a BitArray value into the stream using the fewest number of bytes possible. Stored Size: 1 byte upwards depending on data content Notes: A null BitArray takes 1 byte. An empty BitArray takes 2 bytes.

Declaration
public void Write(BitArray value)
Parameters
Type Name Description
BitArray value

The BitArray value to store.

Write(BitVector32)

Writes a BitVector32 into the stream. Stored Size: 4 bytes.

Declaration
public void Write(BitVector32 value)
Parameters
Type Name Description
BitVector32 value

The BitVector32 to store.

Write(DateTime)

Writes a DateTime value into the stream. Stored Size: 8 bytes

Declaration
public void Write(DateTime value)
Parameters
Type Name Description
DateTime value

The DateTime value to store.

Write(DateTime[])

Writes a DateTime[] into the stream. Notes: A null or empty array will take 1 byte.

Declaration
public void Write(DateTime[] values)
Parameters
Type Name Description
DateTime[] values

The DateTime[] to store.

Write(decimal[])

Writes a Decimal[] into the stream. Notes: A null or empty array will take 1 byte. Calls WriteOptimized(Decimal[]).

Declaration
public void Write(decimal[] values)
Parameters
Type Name Description
decimal[] values

The Decimal[] to store.

Write(double[])

Writes a Double[] into the stream. Notes: A null or empty array will take 1 byte.

Declaration
public void Write(double[] values)
Parameters
Type Name Description
double[] values

The Double[] to store.

Write(Guid)

Writes a Guid into the stream. Stored Size: 16 bytes.

Declaration
public void Write(Guid value)
Parameters
Type Name Description
Guid value

Write(Guid[])

Writes a Guid[] into the stream. Notes: A null or empty array will take 1 byte.

Declaration
public void Write(Guid[] values)
Parameters
Type Name Description
Guid[] values

The Guid[] to store.

Write(short[])

Writes an Int16[]or a null into the stream. Notes: A null or empty array will take 1 byte. Calls WriteOptimized(decimal[]).

Declaration
public void Write(short[] values)
Parameters
Type Name Description
short[] values

The Int16[] to store.

Write(int[])

Writes an Int32[] into the stream. Notes: A null or empty array will take 1 byte.

Declaration
public void Write(int[] values)
Parameters
Type Name Description
int[] values

The Int32[] to store.

Write(long[])

Writes an Int64[] into the stream. Notes: A null or empty array will take 1 byte.

Declaration
public void Write(long[] values)
Parameters
Type Name Description
long[] values

The Int64[] to store.

Write(object[])

Writes an object[] into the stream. Stored Size: 2 bytes upwards depending on data content Notes: A null object[] takes 1 byte. An empty object[] takes 2 bytes. The contents of the array will be stored optimized.

Declaration
public void Write(object[] values)
Parameters
Type Name Description
object[] values

The object[] to store.

Write(sbyte[])

Writes an SByte[] into the stream. Notes: A null or empty array will take 1 byte.

Declaration
public void Write(sbyte[] values)
Parameters
Type Name Description
sbyte[] values

The SByte[] to store.

Write(float[])

Writes a Single[] into the stream. Notes: A null or empty array will take 1 byte.

Declaration
public void Write(float[] values)
Parameters
Type Name Description
float[] values

The Single[] to store.

Write(string)

Calls WriteOptimized(string). This override to hide base BinaryWriter.Write(string).

Declaration
public override void Write(string value)
Parameters
Type Name Description
string value

The string to store.
Overrides

Write(TimeSpan)

Writes a TimeSpan value into the stream. Stored Size: 8 bytes

Declaration
public void Write(TimeSpan value)
Parameters
Type Name Description
TimeSpan value

The TimeSpan value to store.

Write(TimeSpan[])

Writes a TimeSpan[] into the stream. Notes: A null or empty array will take 1 byte.

Declaration
public void Write(TimeSpan[] values)
Parameters
Type Name Description
TimeSpan[] values

The TimeSpan[] to store.

Write(Type, bool)

Stores a Type object into the stream. Stored Size: Depends on the length of the Type's name and whether the fullyQualified parameter is set. A null Type takes 1 byte.

Declaration
public void Write(Type value, bool fullyQualified)
Parameters
Type Name Description
Type value

The Type to store.
bool fullyQualified

true to store the AssemblyQualifiedName or false to store the FullName.

Write(ushort[])

Writes a UInt16[] into the stream. Notes: A null or empty array will take 1 byte.

Declaration
public void Write(ushort[] values)
Parameters
Type Name Description
ushort[] values

The UInt16[] to store.

Write(uint[])

Writes a UInt32[] into the stream. Notes: A null or empty array will take 1 byte.

Declaration
public void Write(uint[] values)
Parameters
Type Name Description
uint[] values

The UInt32[] to store.

Write(ulong[])

Writes a UInt64[] into the stream. Notes: A null or empty array will take 1 byte.

Declaration
public void Write(ulong[] values)
Parameters
Type Name Description
ulong[] values

The UInt64[] to store.

WriteBytesDirect(byte[])

Writes a byte[] directly into the stream. The size of the array is not stored so only use this method when the number of bytes will be known at deserialization time.

A null value will throw an exception

Declaration
public void WriteBytesDirect(byte[] value)
Parameters
Type Name Description
byte[] value

The byte[] to store. Must not be null.

WriteObject(object)

Stores an object into the stream using the fewest number of bytes possible. Stored Size: 1 byte upwards depending on type and/or content.

1 byte: null, DBNull.Value, Boolean

1 to 2 bytes: Int16, UInt16, Byte, SByte, Char,

1 to 4 bytes: Int32, UInt32, Single, BitVector32

1 to 8 bytes: DateTime, TimeSpan, Double, Int64, UInt64

1 or 16 bytes: Guid

1 plus content: string, object[], byte[], char[], BitArray, Type, ArrayList

Any other object be stored using a .Net Binary formatter but this should only be allowed as a last resort: Since this is effectively a different serialization session, there is a possibility of the same shared object being serialized twice or, if the object has a reference directly or indirectly back to the parent object, there is a risk of looping which will throw an exception.

The type of object is checked with the most common types being checked first. Each 'section' can be reordered to provide optimum speed but the check for null should always be first and the default serialization always last.

Once the type is identified, a SerializedType byte is stored in the stream followed by the data for the object (certain types/values may not require storage of data as the SerializedType may imply the value).

For certain objects, if the value is within a certain range then optimized storage may be used. If the value doesn't meet the required optimization criteria then the value is stored directly. The checks for optimization may be disabled by setting the OptimizeForSize property to false in which case the value is stored directly. This could result in a slightly larger stream but there will be a speed increate to compensate.

Declaration
public void WriteObject(object value)
Parameters
Type Name Description
object value

The object to store.

WriteOptimized(bool[])

Writes an optimized Boolean[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte. Stored as a BitArray.

Declaration
public void WriteOptimized(bool[] values)
Parameters
Type Name Description
bool[] values

The Boolean[] to store.

WriteOptimized(ArrayList)

Writes an non-null ArrayList into the stream using the fewest number of bytes possible. Stored Size: 1 byte upwards depending on data content Notes: An empty ArrayList takes 1 byte.

Declaration
public void WriteOptimized(ArrayList value)
Parameters
Type Name Description
ArrayList value

The ArrayList to store. Must not be null.

WriteOptimized(BitArray)

Writes a BitArray into the stream using the fewest number of bytes possible. Stored Size: 1 byte upwards depending on data content Notes: An empty BitArray takes 1 byte.

Declaration
public void WriteOptimized(BitArray value)
Parameters
Type Name Description
BitArray value

The BitArray value to store. Must not be null.

WriteOptimized(BitVector32)

Writes a BitVector32 into the stream using the fewest number of bytes possible. Stored Size: 1 to 4 bytes. (.Net is 4 bytes) 1 to 7 bits takes 1 byte 8 to 14 bits takes 2 bytes 15 to 21 bits takes 3 bytes 22 to 28 bits takes 4 bytes

29 to 32 bits takes 5 bytes - use Write(BitVector32) method instead

Try to order the BitVector32 masks so that the highest bits are least-likely to be set.

Declaration
public void WriteOptimized(BitVector32 value)
Parameters
Type Name Description
BitVector32 value

The BitVector32 to store. Must not use more than 28 bits.

WriteOptimized(DateTime)

Writes a DateTime value into the stream using the fewest number of bytes possible. Stored Size: 3 bytes to 7 bytes (.Net is 8 bytes) Notes: A DateTime containing only a date takes 3 bytes (except a .NET 2.0 Date with a specified DateTimeKind which will take a minimum of 5 bytes - no further optimization for this situation felt necessary since it is unlikely that a DateTimeKind would be specified without hh:mm also) Date plus hh:mm takes 5 bytes. Date plus hh:mm:ss takes 6 bytes. Date plus hh:mm:ss.fff takes 7 bytes.

Declaration
public void WriteOptimized(DateTime value)
Parameters
Type Name Description
DateTime value

The DateTime value to store. Must not contain sub-millisecond data.

WriteOptimized(DateTime[])

Writes a DateTime[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.

Declaration
public void WriteOptimized(DateTime[] values)
Parameters
Type Name Description
DateTime[] values

The DateTime[] to store.

WriteOptimized(decimal)

Writes a Decimal value into the stream using the fewest number of bytes possible. Stored Size: 1 byte to 14 bytes (.Net is 16 bytes) Restrictions: None

Declaration
public void WriteOptimized(decimal value)
Parameters
Type Name Description
decimal value

The Decimal value to store

WriteOptimized(decimal[])

Writes a Decimal[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.

Declaration
public void WriteOptimized(decimal[] values)
Parameters
Type Name Description
decimal[] values

The Decimal[] to store.

WriteOptimized(short)

Write an Int16 value using the fewest number of bytes possible.

Declaration
public void WriteOptimized(short value)
Parameters
Type Name Description
short value

The Int16 to store. Must be between 0 and 16,383 inclusive.
Remarks

0x0000 - 0x007f (0 to 127) takes 1 byte 0x0080 - 0x03FF (128 to 16,383) takes 2 bytes

0x0400 - 0x7FFF (16,384 to 32,767) takes 3 bytes All negative numbers take 3 bytes

Only call this method if the value is known to be between 0 and 16,383 otherwise use Write(Int16 value)

WriteOptimized(short[])

Writes an Int16[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.

Declaration
public void WriteOptimized(short[] values)
Parameters
Type Name Description
short[] values

The Int16[] to store.

WriteOptimized(int)

Write an Int32 value using the fewest number of bytes possible.

Declaration
public void WriteOptimized(int value)
Parameters
Type Name Description
int value

The Int32 to store. Must be between 0 and 268,435,455 inclusive.
Remarks

0x00000000 - 0x0000007f (0 to 127) takes 1 byte 0x00000080 - 0x000003FF (128 to 16,383) takes 2 bytes 0x00000400 - 0x001FFFFF (16,384 to 2,097,151) takes 3 bytes 0x00200000 - 0x0FFFFFFF (2,097,152 to 268,435,455) takes 4 bytes

0x10000000 - 0x07FFFFFF (268,435,456 and above) takes 5 bytes All negative numbers take 5 bytes

Only call this method if the value is known to be between 0 and 268,435,455 otherwise use Write(Int32 value)

WriteOptimized(int[])

Writes an Int32[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.

Declaration
public void WriteOptimized(int[] values)
Parameters
Type Name Description
int[] values

The Int32[] to store.

WriteOptimized(long)

Write an Int64 value using the fewest number of bytes possible.

Declaration
public void WriteOptimized(long value)
Parameters
Type Name Description
long value

The Int64 to store. Must be between 0 and 72,057,594,037,927,935 inclusive.
Remarks

0x0000000000000000 - 0x000000000000007f (0 to 127) takes 1 byte 0x0000000000000080 - 0x00000000000003FF (128 to 16,383) takes 2 bytes 0x0000000000000400 - 0x00000000001FFFFF (16,384 to 2,097,151) takes 3 bytes 0x0000000000200000 - 0x000000000FFFFFFF (2,097,152 to 268,435,455) takes 4 bytes 0x0000000010000000 - 0x00000007FFFFFFFF (268,435,456 to 34,359,738,367) takes 5 bytes 0x0000000800000000 - 0x000003FFFFFFFFFF (34,359,738,368 to 4,398,046,511,103) takes 6 bytes 0x0000040000000000 - 0x0001FFFFFFFFFFFF (4,398,046,511,104 to 562,949,953,421,311) takes 7 bytes 0x0002000000000000 - 0x00FFFFFFFFFFFFFF (562,949,953,421,312 to 72,057,594,037,927,935) takes 8 bytes

0x0100000000000000 - 0x7FFFFFFFFFFFFFFF (72,057,594,037,927,936 to 9,223,372,036,854,775,807) takes 9 bytes 0x7FFFFFFFFFFFFFFF - 0xFFFFFFFFFFFFFFFF (9,223,372,036,854,775,807 and above) takes 10 bytes All negative numbers take 10 bytes

Only call this method if the value is known to be between 0 and 72,057,594,037,927,935 otherwise use Write(Int64 value)

WriteOptimized(long[])

Writes an Int64[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.

Declaration
public void WriteOptimized(long[] values)
Parameters
Type Name Description
long[] values

The Int64[] to store.

WriteOptimized(object[])

Writes a not-null object[] into the stream using the fewest number of bytes possible. Stored Size: 2 bytes upwards depending on data content Notes: An empty object[] takes 1 byte. The contents of the array will be stored optimized.

Declaration
public void WriteOptimized(object[] values)
Parameters
Type Name Description
object[] values

The object[] to store. Must not be null.

WriteOptimized(object[], object[])

Writes a pair of object[] arrays into the stream using the fewest number of bytes possible. The arrays must not be null and must have the same length The first array's values are written optimized The second array's values are compared against the first and, where identical, will be stored using a single byte. Useful for storing entity data where there is a before-change and after-change set of value pairs and, typically, only a few of the values will have changed.

Declaration
public void WriteOptimized(object[] values1, object[] values2)
Parameters
Type Name Description
object[] values1

The first object[] value which must not be null and must have the same length as values2
object[] values2

The second object[] value which must not be null and must have the same length as values1

WriteOptimized(string)

Writes a string value into the stream using the fewest number of bytes possible. Stored Size: 1 byte upwards depending on string length Notes: Encodes null, Empty, 'Y', 'N', ' ' values as a single byte Any other single char string is stored as two bytes All other strings are stored in a string token list:

The TypeCode representing the current string token list is written first (1 byte), followed by the string token itself (1-4 bytes)

When the current string list has reached 128 values then a new string list is generated and that is used for generating future string tokens. This continues until the maximum number (128) of string lists is in use, after which the string lists are used in a round-robin fashion. By doing this, more lists are created with fewer items which allows a smaller token size to be used for more strings.

The first 16,384 strings will use a 1 byte token. The next 2,097,152 strings will use a 2 byte token. (This should suffice for most uses!) The next 268,435,456 strings will use a 3 byte token. (My, that is a lot!!) The next 34,359,738,368 strings will use a 4 byte token. (only shown for completeness!!!)

Declaration
public void WriteOptimized(string value)
Parameters
Type Name Description
string value

The string to store.

WriteOptimized(TimeSpan)

Writes a TimeSpan value into the stream using the fewest number of bytes possible. Stored Size: 2 bytes to 8 bytes (.Net is 8 bytes) Notes: hh:mm (time) are always stored together and take 2 bytes. If seconds are present then 3 bytes unless (time) is not present in which case 2 bytes since the seconds are stored in the minutes position. If milliseconds are present then 4 bytes. In addition, if days are present they will add 1 to 4 bytes to the above.

Declaration
public void WriteOptimized(TimeSpan value)
Parameters
Type Name Description
TimeSpan value

The TimeSpan value to store. Must not contain sub-millisecond data.

WriteOptimized(TimeSpan[])

Writes a TimeSpan[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.

Declaration
public void WriteOptimized(TimeSpan[] values)
Parameters
Type Name Description
TimeSpan[] values

The TimeSpan[] to store.

WriteOptimized(Type)

Stores a non-null Type object into the stream. Stored Size: Depends on the length of the Type's name. If the type is a System type (mscorlib) then it is stored without assembly name information, otherwise the Type's AssemblyQualifiedName is used.

Declaration
public void WriteOptimized(Type value)
Parameters
Type Name Description
Type value

The Type to store. Must not be null.

WriteOptimized(ushort)

Write a UInt16 value using the fewest number of bytes possible.

Declaration
public void WriteOptimized(ushort value)
Parameters
Type Name Description
ushort value

The UInt16 to store. Must be between 0 and 16,383 inclusive.
Remarks

0x0000 - 0x007f (0 to 127) takes 1 byte 0x0080 - 0x03FF (128 to 16,383) takes 2 bytes

0x0400 - 0xFFFF (16,384 to 65,536) takes 3 bytes

Only call this method if the value is known to be between 0 and 16,383 otherwise use Write(UInt16 value)

WriteOptimized(ushort[])

Writes a UInt16[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.

Declaration
public void WriteOptimized(ushort[] values)
Parameters
Type Name Description
ushort[] values

The UInt16[] to store.

WriteOptimized(uint)

Write a UInt32 value using the fewest number of bytes possible.

Declaration
public void WriteOptimized(uint value)
Parameters
Type Name Description
uint value

The UInt32 to store. Must be between 0 and 268,435,455 inclusive.
Remarks

0x00000000 - 0x0000007f (0 to 127) takes 1 byte 0x00000080 - 0x000003FF (128 to 16,383) takes 2 bytes 0x00000400 - 0x001FFFFF (16,384 to 2,097,151) takes 3 bytes 0x00200000 - 0x0FFFFFFF (2,097,152 to 268,435,455) takes 4 bytes

0x10000000 - 0xFFFFFFFF (268,435,456 and above) takes 5 bytes

Only call this method if the value is known to be between 0 and 268,435,455 otherwise use Write(UInt32 value)

WriteOptimized(uint[])

Writes a UInt32[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.

Declaration
public void WriteOptimized(uint[] values)
Parameters
Type Name Description
uint[] values

The UInt32[] to store.

WriteOptimized(ulong)

Write a UInt64 value using the fewest number of bytes possible.

Declaration
public void WriteOptimized(ulong value)
Parameters
Type Name Description
ulong value

The UInt64 to store. Must be between 0 and 72,057,594,037,927,935 inclusive.
Remarks

0x0000000000000000 - 0x000000000000007f (0 to 127) takes 1 byte 0x0000000000000080 - 0x00000000000003FF (128 to 16,383) takes 2 bytes 0x0000000000000400 - 0x00000000001FFFFF (16,384 to 2,097,151) takes 3 bytes 0x0000000000200000 - 0x000000000FFFFFFF (2,097,152 to 268,435,455) takes 4 bytes 0x0000000010000000 - 0x00000007FFFFFFFF (268,435,456 to 34,359,738,367) takes 5 bytes 0x0000000800000000 - 0x000003FFFFFFFFFF (34,359,738,368 to 4,398,046,511,103) takes 6 bytes 0x0000040000000000 - 0x0001FFFFFFFFFFFF (4,398,046,511,104 to 562,949,953,421,311) takes 7 bytes 0x0002000000000000 - 0x00FFFFFFFFFFFFFF (562,949,953,421,312 to 72,057,594,037,927,935) takes 8 bytes

0x0100000000000000 - 0x7FFFFFFFFFFFFFFF (72,057,594,037,927,936 to 9,223,372,036,854,775,807) takes 9 bytes 0x7FFFFFFFFFFFFFFF - 0xFFFFFFFFFFFFFFFF (9,223,372,036,854,775,807 and above) takes 10 bytes

Only call this method if the value is known to be between 0 and 72,057,594,037,927,935 otherwise use Write(UInt64 value)

WriteOptimized(ulong[])

Writes a UInt64[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.

Declaration
public void WriteOptimized(ulong[] values)
Parameters
Type Name Description
ulong[] values

The UInt64[] to store.

WriteStringDirect(string)

Writes a non-null string directly to the stream without tokenization.

Declaration
public void WriteStringDirect(string value)
Parameters
Type Name Description
string value

The string to store. Must not be null.

WriteTokenizedObject(object)

Writes a token (an Int32 taking 1 to 4 bytes) into the stream that represents the object instance. The same token will always be used for the same object instance.

The object will be serialized once and recreated at deserialization time. Calls to SerializationReader.ReadTokenizedObject() will retrieve the same object instance.

Declaration
public void WriteTokenizedObject(object value)
Parameters
Type Name Description
object value

The object to tokenize. Must not be null and must not be a string.

WriteTokenizedObject(object, bool)

Writes a token (an Int32 taking 1 to 4 bytes) into the stream that represents the object instance. The same token will always be used for the same object instance.

When recreateFromType is set to true, the object's Type will be stored and the object recreated using Activator.GetInstance with a parameterless contructor. This is useful for stateless, factory-type classes.

When recreateFromType is set to false, the object will be serialized once and recreated at deserialization time.

Calls to SerializationReader.ReadTokenizedObject() will retrieve the same object instance.

Declaration
public void WriteTokenizedObject(object value, bool recreateFromType)
Parameters
Type Name Description
object value

The object to tokenize. Must not be null and must not be a string.
bool recreateFromType

true if the object can be recreated using a parameterless constructor; false if the object should be serialized as-is

WriteTypedArray(Array)

Writes a null or a typed array into the stream.

Declaration
public void WriteTypedArray(Array values)
Parameters
Type Name Description
Array values

The array to store.

Implements

Extension Methods

EnumUtil.MapEnums<From, To>(From)