CompoundStorageBuilder Class

Definition

Namespace

Bodu.IO.Compound.Builders

Assembly

Bodu.IO.Compound.dll

Package

Bodu.IO.Compound 1.0.0

Source

CompoundStorageBuilder.Serialization.cs

Represents a storage entry in a mutable compound-file object model - a named container of child storages and streams.

public sealed class CompoundStorageBuilder : CompoundEntryBuilder, IDictionary<string, CompoundEntryBuilder>, ICollection<KeyValuePair<string, CompoundEntryBuilder>>, IEnumerable<KeyValuePair<string, CompoundEntryBuilder>>, IEnumerable

Inheritance

object

CompoundEntryBuilder

CompoundStorageBuilder

Implements

IDictionary<string, CompoundEntryBuilder>

ICollection<KeyValuePair<string, CompoundEntryBuilder>>

IEnumerable<KeyValuePair<string, CompoundEntryBuilder>>

IEnumerable

Inherited Members

CompoundEntryBuilder.AsStorage()

CompoundEntryBuilder.AsStream()

CompoundEntryBuilder.Name

CompoundEntryBuilder.Parent

CompoundEntryBuilder.Root

CompoundEntryBuilder.ClassId

CompoundEntryBuilder.CreationTime

CompoundEntryBuilder.ModifiedTime

CompoundEntryBuilder.StateBits

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Remarks

This is the authoring counterpart of CompoundStorage and the compound-file analogue of a JsonObject: children are keyed by name and a node belongs to at most one storage at a time. A storage with no parent is the root of a document; serialize a tree with its ToArray(CompoundBuildOptions) / WriteTo(Stream, CompoundBuildOptions) members.

Names are compared per CompoundStorageBuilderOptions (case-insensitive by default, matching the compound-file format). The serialization order of children is determined by the builder, not by insertion order.

Constructors

CompoundStorageBuilder()

Initializes a new instance of the CompoundStorageBuilder class with default options.

public CompoundStorageBuilder()

CompoundStorageBuilder(CompoundStorageBuilderOptions)

Initializes a new instance of the CompoundStorageBuilder class with the specified options.

public CompoundStorageBuilder(CompoundStorageBuilderOptions options)

Parameters

options CompoundStorageBuilderOptions

The options controlling name comparison.

Properties

Count

Gets the number of elements contained in the ICollection<T>.

public int Count { get; }

Property Value

int

The number of elements contained in the ICollection<T>.

EntryType

Gets the kind of entry this node represents.

public override CompoundEntryType EntryType { get; }

Property Value

CompoundEntryType

The CompoundEntryType of the node.

this[string]

Gets or sets the element with the specified key.

public CompoundEntryBuilder this[string key] { get; set; }

Parameters

key string

The key of the element to get or set.

Property Value

CompoundEntryBuilder

The element with the specified key.

Exceptions

ArgumentNullException

key is null.

KeyNotFoundException

The property is retrieved and key is not found.

NotSupportedException

The property is set and the IDictionary<TKey, TValue> is read-only.

ArgumentNullException

Thrown when the key or value is null.

CompoundFileSerializationException

Thrown when the name is invalid.

Keys

Gets an ICollection<T> containing the keys of the IDictionary<TKey, TValue>.

public ICollection<string> Keys { get; }

Property Value

ICollection<string>

An ICollection<T> containing the keys of the object that implements IDictionary<TKey, TValue>.

Values

Gets an ICollection<T> containing the values in the IDictionary<TKey, TValue>.

public ICollection<CompoundEntryBuilder> Values { get; }

Property Value

ICollection<CompoundEntryBuilder>

An ICollection<T> containing the values in the object that implements IDictionary<TKey, TValue>.

Methods

Add(string, CompoundEntryBuilder)

Adds an element with the provided key and value to the IDictionary<TKey, TValue>.

public void Add(string key, CompoundEntryBuilder value)

Parameters

key string

The object to use as the key of the element to add.

value CompoundEntryBuilder

The object to use as the value of the element to add.

Exceptions

ArgumentNullException

key is null.

ArgumentException

An element with the same key already exists in the IDictionary<TKey, TValue>.

NotSupportedException

The IDictionary<TKey, TValue> is read-only.

CompoundFileSerializationException

Thrown when the name is invalid or already present.

AddStorage(string)

Adds a new child storage with the specified name.

public CompoundStorageBuilder AddStorage(string name)

Parameters

name string

The storage name.

Returns

CompoundStorageBuilder

The created CompoundStorageBuilder.

Exceptions

CompoundFileSerializationException

Thrown when the name is invalid or already present.

AddStream(string, Func<Stream>, long)

Adds a new deferred child stream whose payload is read on demand from a re-openable source.

public CompoundStreamBuilder AddStream(string name, Func<Stream> openRead, long length)

Parameters

name string

The stream name.

openRead Func<Stream>

A factory that opens a readable stream over the payload each time it is invoked.

length long

The payload length, in bytes.

Returns

CompoundStreamBuilder

The created CompoundStreamBuilder.

Exceptions

CompoundFileSerializationException

Thrown when the name is invalid or already present.

AddStream(string, ReadOnlyMemory<byte>)

Adds a new child stream with the specified name and payload.

public CompoundStreamBuilder AddStream(string name, ReadOnlyMemory<byte> content)

Parameters

name string

The stream name.

content ReadOnlyMemory<byte>

The payload bytes.

Returns

CompoundStreamBuilder

The created CompoundStreamBuilder.

Exceptions

CompoundFileSerializationException

Thrown when the name is invalid or already present.

AddStreamFromFile(string, string)

Adds a new deferred child stream whose payload is read on demand from a file.

public CompoundStreamBuilder AddStreamFromFile(string name, string path)

Parameters

name string

The stream name.

path string

The path of the file providing the payload.

Returns

CompoundStreamBuilder

The created CompoundStreamBuilder.

Exceptions

CompoundFileSerializationException

Thrown when the name is invalid or already present.

Clear()

Removes all items from the ICollection<T>.

public void Clear()

Exceptions

NotSupportedException

The ICollection<T> is read-only.

ContainsKey(string)

Determines whether the IDictionary<TKey, TValue> contains an element with the specified key.

public bool ContainsKey(string key)

Parameters

key string

The key to locate in the IDictionary<TKey, TValue>.

Returns

bool

true if the IDictionary<TKey, TValue> contains an element with the key; otherwise, false.

Exceptions

ArgumentNullException

key is null.

ContainsName(string)

Determines whether the storage contains a child with the specified name.

public bool ContainsName(string name)

Parameters

name string

The name to look up.

Returns

bool

true when a child with the name exists; otherwise false.

CreateRoot()

Creates a new, detached root storage node named Root Entry.

public static CompoundStorageBuilder CreateRoot()

Returns

CompoundStorageBuilder

A root CompoundStorageBuilder ready for authoring.

CreateRoot(CompoundStorageBuilderOptions)

Creates a new, detached root storage node with the specified options.

public static CompoundStorageBuilder CreateRoot(CompoundStorageBuilderOptions options)

Parameters

options CompoundStorageBuilderOptions

The options controlling name comparison.

Returns

CompoundStorageBuilder

A root CompoundStorageBuilder ready for authoring.

DeepClone()

Creates a deep, detached copy of this node and its descendants.

public override CompoundEntryBuilder DeepClone()

Returns

CompoundEntryBuilder

An independent copy with no parent.

EnumerateStorages()

Enumerates the direct child storages of this storage.

public IEnumerable<CompoundStorageBuilder> EnumerateStorages()

Returns

IEnumerable<CompoundStorageBuilder>

The child storages.

EnumerateStreams()

Enumerates the direct child streams of this storage.

public IEnumerable<CompoundStreamBuilder> EnumerateStreams()

Returns

IEnumerable<CompoundStreamBuilder>

The child streams.

FromFile(CompoundFile, bool)

Creates a root storage tree that mirrors the contents of an open compound file.

public static CompoundStorageBuilder FromFile(CompoundFile file, bool lazy = false)

Parameters

file CompoundFile

The compound file to copy.

lazy bool

false (the default) to copy every stream payload into memory, producing a fully detached tree; true to build deferred stream nodes that read their payloads on demand from file. When true the file must remain open for as long as the tree (or any clone of its nodes) is read or serialized.

Returns

CompoundStorageBuilder

A root CompoundStorageBuilder that mirrors the file's contents.

Exceptions

ArgumentNullException

Thrown when file is null.

CompoundFileFormatException

Thrown when a stream's sector chain is malformed.

GetEnumerator()

Returns an enumerator that iterates through the collection.

public IEnumerator<KeyValuePair<string, CompoundEntryBuilder>> GetEnumerator()

Returns

IEnumerator<KeyValuePair<string, CompoundEntryBuilder>>

An enumerator that can be used to iterate through the collection.

Load(Stream)

Creates a root storage tree that mirrors the contents of a compound file read from a stream.

public static CompoundStorageBuilder Load(Stream source)

Parameters

source Stream

The stream containing the compound file; read from its current position to the end.

Returns

CompoundStorageBuilder

A root CompoundStorageBuilder that mirrors the file's contents.

Exceptions

ArgumentNullException

Thrown when source is null.

CompoundFileFormatException

Thrown when the stream is not a well-formed compound file.

Remove(string)

Removes the element with the specified key from the IDictionary<TKey, TValue>.

public bool Remove(string key)

Parameters

key string

The key of the element to remove.

Returns

bool

true if the element is successfully removed; otherwise, false. This method also returns false if key was not found in the original IDictionary<TKey, TValue>.

Exceptions

ArgumentNullException

key is null.

NotSupportedException

The IDictionary<TKey, TValue> is read-only.

Rename(string, string)

Renames a child entry.

public void Rename(string oldName, string newName)

Parameters

oldName string

The current name of the child.

newName string

The new name.

Exceptions

CompoundFileSerializationException

Thrown when newName is invalid or already present, or when no child named oldName exists.

Save(string, CompoundBuildOptions)

Serializes this storage tree to a new file at the supplied path, overwriting any existing file.

public void Save(string path, CompoundBuildOptions options = default)

Parameters

path string

The path of the file to create.

options CompoundBuildOptions

The options controlling the output layout.

Exceptions

ArgumentNullException

Thrown when path is null.

CompoundFileSerializationException

Thrown when the tree cannot be represented.

ToArray(CompoundBuildOptions)

Serializes this storage tree to a compound-file byte array.

public byte[] ToArray(CompoundBuildOptions options = default)

Parameters

options CompoundBuildOptions

The options controlling the output layout.

Returns

byte[]

The complete compound-file content.

Exceptions

CompoundFileSerializationException

Thrown when the tree cannot be represented.

TryGetStorage(string, out CompoundStorageBuilder)

Attempts to get the child storage with the specified name.

public bool TryGetStorage(string name, out CompoundStorageBuilder storage)

Parameters

name string

The storage name.

storage CompoundStorageBuilder

When this method returns true, the matching storage; otherwise null.

Returns

bool

true when a child storage with the name exists; otherwise false.

TryGetStream(string, out CompoundStreamBuilder)

Attempts to get the child stream with the specified name.

public bool TryGetStream(string name, out CompoundStreamBuilder stream)

Parameters

name string

The stream name.

stream CompoundStreamBuilder

When this method returns true, the matching stream; otherwise null.

Returns

bool

true when a child stream with the name exists; otherwise false.

TryGetValue(string, out CompoundEntryBuilder)

Gets the value associated with the specified key.

public bool TryGetValue(string key, out CompoundEntryBuilder value)

Parameters

key string

The key whose value to get.

value CompoundEntryBuilder

When this method returns, the value associated with the specified key, if the key is found; otherwise, the default value for the type of the value parameter. This parameter is passed uninitialized.

Returns

bool

true if the object that implements IDictionary<TKey, TValue> contains an element with the specified key; otherwise, false.

Exceptions

ArgumentNullException

key is null.

WriteTo(IBufferWriter<byte>, CompoundBuildOptions)

Serializes this storage tree to the supplied buffer writer.

public void WriteTo(IBufferWriter<byte> output, CompoundBuildOptions options = default)

Parameters

output IBufferWriter<byte>

The buffer writer to write the compound file to.

options CompoundBuildOptions

The options controlling the output layout.

Exceptions

ArgumentNullException

Thrown when output is null.

CompoundFileSerializationException

Thrown when the tree cannot be represented.

WriteTo(Stream, CompoundBuildOptions)

Serializes this storage tree to the supplied stream.

public void WriteTo(Stream destination, CompoundBuildOptions options = default)

Parameters

destination Stream

The stream to write the compound file to.

options CompoundBuildOptions

The options controlling the output layout.

Exceptions

ArgumentNullException

Thrown when destination is null.

CompoundFileSerializationException

Thrown when the tree cannot be represented.

Explicit Interface Implementations

ICollection<KeyValuePair<string, CompoundEntryBuilder>>.Add(KeyValuePair<string, CompoundEntryBuilder>)

Adds an item to the ICollection<T>.

void ICollection<KeyValuePair<string, CompoundEntryBuilder>>.Add(KeyValuePair<string, CompoundEntryBuilder> item)

Parameters

item KeyValuePair<string, CompoundEntryBuilder>

The object to add to the ICollection<T>.

Exceptions

NotSupportedException

The ICollection<T> is read-only.

ICollection<KeyValuePair<string, CompoundEntryBuilder>>.Contains(KeyValuePair<string, CompoundEntryBuilder>)

Determines whether the ICollection<T> contains a specific value.

bool ICollection<KeyValuePair<string, CompoundEntryBuilder>>.Contains(KeyValuePair<string, CompoundEntryBuilder> item)

Parameters

item KeyValuePair<string, CompoundEntryBuilder>

The object to locate in the ICollection<T>.

Returns

bool

true if item is found in the ICollection<T>; otherwise, false.

ICollection<KeyValuePair<string, CompoundEntryBuilder>>.CopyTo(KeyValuePair<string, CompoundEntryBuilder>[], int)

Copies the elements of the ICollection<T> to an Array, starting at a particular Array index.

void ICollection<KeyValuePair<string, CompoundEntryBuilder>>.CopyTo(KeyValuePair<string, CompoundEntryBuilder>[] array, int arrayIndex)

Parameters

array KeyValuePair<string, CompoundEntryBuilder>[]

The one-dimensional Array that is the destination of the elements copied from ICollection<T>. The Array must have zero-based indexing.

arrayIndex int

The zero-based index in array at which copying begins.

Exceptions

ArgumentNullException

array is null.

ArgumentOutOfRangeException

arrayIndex is less than 0.

ArgumentException

The number of elements in the source ICollection<T> is greater than the available space from arrayIndex to the end of the destination array.

ICollection<KeyValuePair<string, CompoundEntryBuilder>>.IsReadOnly

Gets a value indicating whether the ICollection<T> is read-only.

bool ICollection<KeyValuePair<string, CompoundEntryBuilder>>.IsReadOnly { get; }

Returns

bool

true if the ICollection<T> is read-only; otherwise, false.

ICollection<KeyValuePair<string, CompoundEntryBuilder>>.Remove(KeyValuePair<string, CompoundEntryBuilder>)

Removes the first occurrence of a specific object from the ICollection<T>.

bool ICollection<KeyValuePair<string, CompoundEntryBuilder>>.Remove(KeyValuePair<string, CompoundEntryBuilder> item)

Parameters

item KeyValuePair<string, CompoundEntryBuilder>

The object to remove from the ICollection<T>.

Returns

bool

true if item was successfully removed from the ICollection<T>; otherwise, false. This method also returns false if item is not found in the original ICollection<T>.

Exceptions

NotSupportedException

The ICollection<T> is read-only.

IEnumerable.GetEnumerator()

Returns an enumerator that iterates through a collection.

IEnumerator IEnumerable.GetEnumerator()

Returns

IEnumerator

An IEnumerator object that can be used to iterate through the collection.

Applies to

Product	Versions
.NET	8, 10