mySobek Home   |   Help
Skip Navigation Links.
Expand <a href='https://sobekrepository.org/sobekcm' title='Sobek home page'>Project Home</a>Project Home
Expand <a href='https://sobekrepository.org/help' title='Online user help'>User Help</a>User Help
Expand <a href='https://sobekrepository.org/sobekcm/technical' title='Sobek home page'>Technical Help</a>Technical Help
Expand <a href='https://sobekrepository.org/software' title='Center for downloading all SobekCM-related software'>Download Center</a>Download Center
Training Videos
Collapse <a href='https://sobekrepository.org/codehelp' title='Details on each of the different classes, interfaces, properties, etc..'>Code Details</a>Code Details
MISSING BANNER
Code Details >> Core >> MemoryMgmt >> SerializationWriter

SerializationWriter Class



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:

Examples

 Copy imageCopy
writer.AppendTokenTables();
MemoryStream stream = (MemoryStream) writer.BaseStream;
   serializedData = MiniLZO.Compress(stream.GetBuffer(), (int) stream.Length);


Namespace: SobekCM.Core.MemoryMgmt
Assembly: SobekCM_Core (in SobekCM_Core.dll) Version: 4.10.0.0 (4.10.0.0)

Syntax

C#
public sealed class SerializationWriter : BinaryWriter

Remarks

Code written by Simon Hewitt and dedicated to public domain (2006)

Inheritance Hierarchy

System..::..Object
  System.IO..::..BinaryWriter
    SobekCM.Core.MemoryMgmt..::..SerializationWriter

Constructors

  NameDescription
Public methodSerializationWriter()()()()
Creates a FastSerializer with the Default Capacity (1kb)
Public methodSerializationWriter(Int32)
Creates a FastSerializer with the specified capacity

Methods

  NameDescription
Public methodAppendTokenTables
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.
Public methodDumpTypeUsage
Dump the type usage information while debugging
Public methodToArray
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.
Public methodWrite(array<Boolean>[]()[][])
Writes a Boolean[] into the stream. Notes: A null or empty array will take 1 byte. Calls WriteOptimized(Boolean[]).
Public methodWrite(array<Byte>[]()[][])
Writes a Byte[] into the stream. Notes: A null or empty array will take 1 byte.
(Overrides BinaryWriter..::..Write(array<Byte>[]()[][]).)
Public methodWrite(array<Char>[]()[][])
Writes a Char[] into the stream. Notes: A null or empty array will take 1 byte.
(Overrides BinaryWriter..::..Write(array<Char>[]()[][]).)
Public methodWrite(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.
Public methodWrite(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.
Public methodWrite(BitVector32)
Writes a BitVector32 into the stream. Stored Size: 4 bytes.
Public methodWrite(DateTime)
Writes a DateTime value into the stream. Stored Size: 8 bytes
Public methodWrite(array<DateTime>[]()[][])
Writes a DateTime[] into the stream. Notes: A null or empty array will take 1 byte.
Public methodWrite(array<Decimal>[]()[][])
Writes a Decimal[] into the stream. Notes: A null or empty array will take 1 byte. Calls WriteOptimized(Decimal[]).
Public methodWrite(array<Double>[]()[][])
Writes a Double[] into the stream. Notes: A null or empty array will take 1 byte.
Public methodWrite(Guid)
Writes a Guid into the stream. Stored Size: 16 bytes.
Public methodWrite(array<Guid>[]()[][])
Writes a Guid[] into the stream. Notes: A null or empty array will take 1 byte.
Public methodWrite(array<Int16>[]()[][])
Writes an Int16[]or a null into the stream. Notes: A null or empty array will take 1 byte. Calls WriteOptimized(decimal[]).
Public methodWrite(array<Int32>[]()[][])
Writes an Int32[] into the stream. Notes: A null or empty array will take 1 byte.
Public methodWrite(array<Int64>[]()[][])
Writes an Int64[] into the stream. Notes: A null or empty array will take 1 byte.
Public methodWrite(array<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.
Public methodWrite(array<SByte>[]()[][])
Writes an SByte[] into the stream. Notes: A null or empty array will take 1 byte.
Public methodWrite(array<Single>[]()[][])
Writes a Single[] into the stream. Notes: A null or empty array will take 1 byte.
Public methodWrite(String)
Calls WriteOptimized(string). This override to hide base BinaryWriter.Write(string).
(Overrides BinaryWriter..::..Write(String).)
Public methodWrite(TimeSpan)
Writes a TimeSpan value into the stream. Stored Size: 8 bytes
Public methodWrite(array<TimeSpan>[]()[][])
Writes a TimeSpan[] into the stream. Notes: A null or empty array will take 1 byte.
Public methodWrite(array<UInt16>[]()[][])
Writes a UInt16[] into the stream. Notes: A null or empty array will take 1 byte.
Public methodWrite(array<UInt32>[]()[][])
Writes a UInt32[] into the stream. Notes: A null or empty array will take 1 byte.
Public methodWrite(array<UInt64>[]()[][])
Writes a UInt64[] into the stream. Notes: A null or empty array will take 1 byte.
Public methodWrite(Type, Boolean)
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.
Public methodWrite(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.
Public methodWrite<(Of <<'(T>)>>)(List<(Of <<'(T>)>>))
Writes a non-null generic List into the stream.
Public methodWrite<(Of <<'(K, V>)>>)(Dictionary<(Of <<'(K, V>)>>))
Writes a non-null generic Dictionary into the stream.
Public methodWriteBytesDirect
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
Public methodWriteNullable
Writes a Nullable type into the stream. Synonym for WriteObject().
Public methodWriteObject
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.
Public methodWriteOptimized(array<Boolean>[]()[][])
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.
Public methodWriteOptimized(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.
Public methodWriteOptimized(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.
Public methodWriteOptimized(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.
Public methodWriteOptimized(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.
Public methodWriteOptimized(array<DateTime>[]()[][])
Writes a DateTime[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.
Public methodWriteOptimized(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
Public methodWriteOptimized(array<Decimal>[]()[][])
Writes a Decimal[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.
Public methodWriteOptimized(Int32)
Write an Int32 value using the fewest number of bytes possible.

Only call this method if the value is known to be between 0 and 268,435,455 otherwise use Write(Int32 value)
Public methodWriteOptimized(array<Int32>[]()[][])
Writes an Int32[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.
Public methodWriteOptimized(Int64)
Write an Int64 value using the fewest number of bytes possible. 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)
Public methodWriteOptimized(array<Int64>[]()[][])
Writes an Int64[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.
Public methodWriteOptimized(array<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.
Public methodWriteOptimized(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!!!)
Public methodWriteOptimized(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.
Public methodWriteOptimized(array<TimeSpan>[]()[][])
Writes a TimeSpan[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.
Public methodWriteOptimized(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.
Public methodWriteOptimized(UInt32)
Write a UInt32 value using the fewest number of bytes possible. 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)
Public methodWriteOptimized(array<UInt32>[]()[][])
Writes a UInt32[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.
Public methodWriteOptimized(UInt64)
Write a UInt64 value using the fewest number of bytes possible. 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)
Public methodWriteOptimized(array<UInt64>[]()[][])
Writes a UInt64[] into the stream using the fewest possible bytes. Notes: A null or empty array will take 1 byte.
Public methodWriteOptimized(array<Object>[]()[][], array<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.
Public methodWriteStringDirect
Writes a non-null string directly to the stream without tokenization.
Public methodWriteTokenizedObject(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.
Public methodWriteTokenizedObject(Object, Boolean)
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.
Public methodWriteTypedArray
Writes a null or a typed array into the stream.

Fields

  NameDescription
Protected fieldStatic memberDateDayMask
Protected fieldStatic memberDateHasTimeOrKindMask
Protected fieldStatic memberDateMonthMask
Protected fieldStatic memberDateYearMask
Section masks used for packing DateTime values
Public fieldStatic memberDefaultCapacity
Default capacity for the underlying MemoryStream
Public fieldStatic memberDefaultOptimizeForSize
The Default setting for the OptimizeForSize property.
Protected fieldStatic memberHasDaysSection
Protected fieldStatic memberHasMillisecondsSection
Protected fieldStatic memberHasSecondsSection
Protected fieldStatic memberHasTimeSection
Public fieldStatic memberHighestOptimizable32BitValue
Holds the highest int that can be optimized into less than the normal 4 bytes
Public fieldStatic memberHighestOptimizable64BitValue
Holds the highest long that can be optimized into less than the normal 8 bytes
Protected fieldStatic memberHoursSection
Protected fieldStatic memberIsNegativeSection
Section masks used for packing TimeSpan values
Protected fieldStatic memberMillisecondsSection
Protected fieldStatic memberMinutesSection
Protected fieldStatic memberSecondsSection

Properties

  NameDescription
Public propertyOptimizeForSize
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.

See Also



Version 4.10.0 ( last generated Monday, March 7, 2016 )