Low-Level classes

Low-level classes in BinaryDOM API are HugeList, BinStorage and Variant.

Class HugeList<T>
This class provides base functionality for lists of nodes in BinaryDOM and TextDOM.

public class HugeList<T> : IEnumerable<T>, IEnumerable

This class also supports methods and properties declared in IList<T> and ICollection<T> interfaces, but does not implements these interfaces directly due to their length limitations.
To organize double-linked list, this class provides a special accessor class, HugeListNode<T>.
Constructor Parameters Description
HugeList None Default constructor. Creates an empty list.
HugeList IEnumerable<T> collection Creates a list and initializes it from the provided collection.
Property Type Description
Count long, get only Returns number of nodes in the list.
First HugeListNode<T>, get only Returns the first node in the list.
Last HugeListNode<T>, get only Returns the last node in the list.
Item (indexer) HugeListNode<T>, get only Returns a node from the list by index.
ReverseEnumerator IEnumerator<T>, get only Returns an enumerator which will enumerate items in reverse order.
Method Parameters Description
AddLast T node, returns void Appends node to the list.
AddFirst T node, returns void Inserts node before the beginning of the list.
AddAfter HugeListNode<T> node, T item, returns void Inserts item after the node specified by "node" parameter.
AddAfter T node, T item, returns void Inserts item after the "node", if "node" is found.
AddBefore HugeListNode<T> node, T item, returns void Inserts item before the node specified by "node" parameter.
AddBefore T node, T item, returns void Inserts item before the "node", if "node" is found.
Find T item, returns HugeListNode<T> Searches for the item, starting from the beginning if the list, and returns a node which points to the found node.
FindLast T item, returns HugeListNode<T> Finds an item (from the end) in the list, and returns a node which points to the found node.
Remove T item, returns bool Removes item from the list, if item is found. Returns true if removed successfully.
Remove HugeListNode<T> node, returns void Removes node from the list.
RemoveAll T item, returns void Removes all occurrences of the specified item from the list.
Clear returns void Removes all items from the list.
RemoveHead returns void Removes first item from the list.
RemoveTail returns void Removes last item from the list.
Contains T node, returns bool Returns true if the list contains specified node.
CopyTo T[] array, int arrayIndex, returns void Copies all list elements to an array starting from the arrayIndex.
Add T item, returns void Appends item to the list.
IndexOf T item, returns long Returns an index of the item in the list, if found. Otherwise, returns -1.
Insert long index, T item, returns long Inserts an item to the list at position specified by the "index".
RemoveAt long index, returns long Removes an item from the list at the position specified by "index".
AddRange IEnumerable<T> collection, returns void Appends collection contents to the list.
InsertRange long index, IEnumerable<T> collection, returns void Inserts collection contents to the list, at the position specified by "index".
RemoveRange long index, long count, returns void Removes multiple items from the list, starting from the element at "index" position.

Class HugeListNode<T>
public class HugeListNode<T>

This is an accessor class to organize doubly-linked list of nodes.
Constructor Parameters Description
HugeListNode<T> None Default constructor. Creates an empty list.
HugeListNode<T> HugeListNode<T> source Creates a list node and initializes it with a copy of the specified list node.
HugeListNode<T> HugeListNode<T> next, HugeListNode<T> previous, T value Creates a list node and include it into the specified list.
HugeListNode<T> T value Creates a list node and initialize it with T.
Property Type Description
Next HugeListNode<T>, get only Gets a next list node in the list.
Previous HugeListNode<T>, get only Gets a previous list node in the list.
Value T, get only Gets a value of list node.

Class BinStorage
public class BinStorage : ICloneable, IDisposable

This class represents a flexible raw data storage which can store virtually any volume of data.
When initialized with default constructor, or with size less than FileManager.PreswapSize, it keeps data in a memory array. As volume of the data grows, it saves all the data to a temporary file and continues working with this file.
Separate method of data storage (for data volumes larger than FileManager.PreswapSize) is mirrored read-only data, when BinStorage uses a slice of external Stream as data storage without storing actual data in a memory or file. To make it possible, external Stream must support reading and seeking, like file-based streams do. In this mode, BinStorage is already "filled" with data from the construction.
When you change mirrored storage, it dumps all the data into a temporary file and then works with that file rather than with the original stream.
Constructor Parameters Description
BinStorage None Default constructor. Creates memory-bound storage.
BinStorage long size Creates memory-bound or temporary file-bound storage depending on the size provided.
BinStorage Stream stream, long offset, long size Creates memory-bound or file mapped storage, depending on the size provided. Thic method could throw an exception if Stream does not support read and seek or offset/size is wrong.
This constructor fills BinStorage object with data if it creates mapped storage object.
Property Type Description
IsInMemory bool, get only Returns true if storage uses memory array.
IsMapped bool, get only Returns true if storage is mapped to document file.
Count long, get/set Length of the storage in bytes. In set operation, if storage grows, it could change storage type from memory to file.
And, if storage was mirrored, it will become file-bound.
Item (indexer) byte, get/set Provides random access to storage elements.
Method Parameters Description
GetStream returns Stream Returns contents of storage as a Stream.
GetValue long index, Variant node, returns void Fills a Variant value with data from internal storage. Index is measured in Variant-contained types, not bytes.
Add byte data, returns void Appends a byte to the internal storage.
AddRange byte[] data, returns void Appends contents of a byte array to the internal storage.
AddRange Stream data, returns void Appends contents of a Stream to the internal storage. Reads from a current position till the end of stream.
AddRange BinStorage bs, returns void Appends contents of a storage to the internal storage.
AddRangeLimited Stream data, long length, returns void Appends length bytes from a Stream to the internal storage.
GetRange long index, long length, returns byte[] Returns array of bytes filled with contents of the storage started from index, size is length.
Copy BinStorage destination, long index, long length, returns void Copies a portion of the data into another BinStorage.
ReadFrom Stream data, returns void Fills storage with data from the Stream. All previous storage contents will be deleted.
RemoveRange long index, long length, returns void Removes portion of data from the storage.
Clear returns void Deletes all the data from the internal storage.
WriteTo Stream data, returns void Writes all storage data to a Stream.
WriteTo Stream data, long index, long length, returns void Writes a slice of storage data to a Stream.

Class Variant
public class Variant : ICloneable, IComparable, IEquatable<Variant>

Variant is an atomic class for storing items of primitive data types.
It supports a full set of arithmetic, conversion, comparison and input/output operations.
When used in context of arithmetic operations, applicable autoconversion is performed automatically. However, not all the operations support all types of operands. For example, bitwise AND operation supports only unsigned integers and boolean. Subtraction does not support string operands. In such cases, exception will be thrown.
Variant supports the following data types:
  • TypeCode.String
  • TypeCode.Boolean
  • TypeCode.Byte
  • TypeCode.SByte
  • TypeCode.UInt16
  • TypeCode.Int16
  • TypeCode.UInt32
  • TypeCode.Int32
  • TypeCode.Single
  • TypeCode.UInt64
  • TypeCode.Int64
  • TypeCode.Double
BinaryDOM library does not use string and boolean as an item types in data description language. However, these values could appear as a result of expression calculations.
Multi-byte integer values could be big endian. Endianness affects input/output operations.
Default type is TypeCode.Int64 (long).
Constructor Parameters Description
Variant None Default constructor. Creates Variant of default type.
Variant TypeCode type Creates Variant of a specific type.
Variant Variant var Creates a copy of a given Variant.
Property Type Description
BigEndian bool, get/set Get/Set endianness of the value.
VarType TypeCode, get only Returns type of the value.
TypeSize int, get only Returns size of the value in bytes.
TypeName string, get only Returns type name of the value.
Method Parameters Description
Assign various types (see description), returns void Assigns Varaint a value. This is overloaded method. It accepts Variant, bool, byte, sbyte, short, ushort, int, uint, long, ulong, float, double, string. Variant type changes to match the assignes type.
Assign Object obj, returns void Assigns Varaint a value, but does not change its type, except the case when obj is Variant. It accepts Variant, numeric values (bool, byte, sbyte, short, ushort, int, uint, long, ulong, float, double) as boxed objects, and string.
If this Variant has a different type, unboxing exception will be thrown.
Clear returns void Initializes Variant with 0 of appropriate type (empty String in case of string Variant), does not change the type of Variant.
CompareTo Variant var, returns int Compares two Variants, performing autoconversion if needed.
Returns -1 if this Variant less then a given one, 0 if equals, 1 - if more.
Variants will not be changed or converted after this operation.
Convert TypeCode type, returns void Convert Variant into given type.
SetValue List<byte> lst, int startIndex, returns void Fills Variant value from the List of bytes, starting from startIndex.
GetValue List<byte> lst, int startIndex, returns void Dumps Variant value into a List of bytes, starting from startIndex. If the List does not have enough elements, all required extra elements will be added.
SetValueArray byte[] array, returns void Fills Variant value from the array of bytes.
GetValueArray returns byte[] Dumps Variant value to array of bytes and returns it.
ReadFrom Stream stream, returns void Fills Variant value from the Stream. If stream does not contain enough data, exception will be thrown.
WriteTo Stream stream, returns void Dumps Variant value to the Stream.
ToNumber string data, int radix, returns void Assigns a number value converted from string. Possible values for radix are 2, 8, 10, 16. If radix is 0, this method will autodetect radix by prefixes (0x for hexadecimal, 0 for octal).
ToString int radix, returns string Returns string representation of value. Radix parameter works only for integer value. Possible values for radix are 2, 8, 10, 16.
Operator Description
Conversion operators:
public static explicit operator type(Variant var) - see description. 		Represents a Variant as value of appropriate type. The Variant itself will not be changed.
The following conversion types supported: bool, byte, sbyte, short, ushort, int, uint, long, ulong, float, double, string.
Comparison operators:
public static bool operator equality(Variant v1, Variant v2) - see description. 		Compares two Variants values.
The following comparison operators supported: ==, !=, <, >, <=, >=.
public static bool operator false(Variant var) Checks is value equals to false. Needed to use && and || operators with Variants.
public static bool operator true(Variant var) Checks is value equals to true. Needed to use && and || operators with Variants.
public static bool operator true(Variant var) Checks is value equals to true. Needed to use && and || operators with Variants.
public static Variant operator +(Variant v1, Variant v2) Addition operation. Supports all allowed data types except boolean, for strings means concatenation.
public static Variant operator -(Variant v1, Variant v2) Subtraction operation. Supports all allowed data types except string and boolean.
public static Variant operator *(Variant v1, Variant v2) Multiplication operation. Supports all allowed data types except string and boolean.
public static Variant operator /(Variant v1, Variant v2) Division operation. Supports all allowed data types except string and boolean.
public static Variant operator %(Variant v1, Variant v2) Reminder operation. Supports all integer data types.
public static Variant operator &(Variant v1, Variant v2) Bitwise And operation. Supports all unsigned integer data types and boolean.
public static Variant operator |(Variant v1, Variant v2) Bitwise Or operation. Supports all unsigned integer data types and boolean.
public static Variant operator ^(Variant v1, Variant v2) Bitwise Xor operation. Supports all unsigned integer data types and boolean.
public static Variant operator >>(Variant v1, Variant v2) Shift Right operation. Supports all integer data types.
public static Variant operator <<(Variant v1, Variant v2) Shift Left operation. Supports all integer data types.
public static Variant operator ~(Variant v1) Bitwise Not unary operation. Supports all unsigned integer data types and boolean.
public static Variant operator -(Variant v1) Unary Minus operation. Supports all signed integer data types, float and double.

See also: