Table of Contents

TomlObject Class

Definition

Namespace
Bodu.Text.Toml.Nodes
Assembly
Bodu.Text.Toml.dll
Package
Bodu.Text.Toml 1.0.0
Source
TomlObject.cs

Represents a mutable TOML table as a string-keyed collection of child nodes.

public sealed class TomlObject : TomlNode, IDictionary<string, TomlNode?>, ICollection<KeyValuePair<string, TomlNode?>>, IEnumerable<KeyValuePair<string, TomlNode?>>, IEnumerable
Inheritance
TomlObject
Implements
Inherited Members
Extension Methods

Remarks

Entries are kept in insertion order - including across removals - which is also the order in which they are serialized: the TOML writer emits a table's members in document order rather than re-sorting them. A value may be null in memory, but a table containing a null value cannot be written because TOML has no null token. Adding a node that already belongs to another container throws an InvalidOperationException; removing or replacing a value detaches it, clearing its Parent so it can be added to another container.

var table = new TomlObject
{
    ["name"] = TomlValue.Create("orders"),
    ["port"] = TomlValue.Create(8080),
};
table.Add("enabled", TomlValue.Create(true));

// The mutable tree serializes straight back to TOML text.
byte[] utf8 = table.ToUtf8Bytes();

Constructors

TomlObject()

Initializes a new instance of the TomlObject class that is empty.

public TomlObject()

TomlObject(TomlNodeOptions)

Initializes a new instance of the TomlObject class that is empty, using the supplied options to select the property-name comparison.

public TomlObject(TomlNodeOptions options)

Parameters

options TomlNodeOptions

The node options controlling property-name case sensitivity.

Remarks

When PropertyNameCaseInsensitive is true, in-memory property-name lookups use OrdinalIgnoreCase; otherwise they use Ordinal. The option does not affect serialization.

TomlObject(IEnumerable<KeyValuePair<string, TomlNode?>>)

Initializes a new instance of the TomlObject class containing the supplied entries.

public TomlObject(IEnumerable<KeyValuePair<string, TomlNode?>> items)

Parameters

items IEnumerable<KeyValuePair<string, TomlNode>>

The initial entries.

Exceptions

ArgumentNullException

Thrown when items is null.

InvalidOperationException

Thrown when a value already belongs to another container.

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>.

IsReadOnly

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

public bool IsReadOnly { get; }

Property Value

bool

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

this[string]

Gets or sets the value associated with the specified property name.

public TomlNode? this[string key] { get; set; }

Parameters

key string

The property name.

Property Value

TomlNode

The value associated with key.

Remarks

Assigning over an existing entry detaches the replaced node, clearing its Parent.

Exceptions

ArgumentNullException

Thrown when key is null.

KeyNotFoundException

Thrown by the getter when key is not present.

InvalidOperationException

Thrown when the assigned node already belongs to another container.

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>.

Remarks

The collection is a read-only snapshot in insertion order.

Values

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

public ICollection<TomlNode?> Values { get; }

Property Value

ICollection<TomlNode>

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

Remarks

The collection is a read-only snapshot in insertion order.

Methods

Add(KeyValuePair<string, TomlNode?>)

Adds an item to the ICollection<T>.

public void Add(KeyValuePair<string, TomlNode?> item)

Parameters

item KeyValuePair<string, TomlNode>

The object to add to the ICollection<T>.

Exceptions

NotSupportedException

The ICollection<T> is read-only.

Add(string, TomlNode?)

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

public void Add(string key, TomlNode? value)

Parameters

key string

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

value TomlNode

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.

Clear()

Removes all items from the ICollection<T>.

public void Clear()

Exceptions

NotSupportedException

The ICollection<T> is read-only.

Contains(KeyValuePair<string, TomlNode?>)

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

public bool Contains(KeyValuePair<string, TomlNode?> item)

Parameters

item KeyValuePair<string, TomlNode>

The object to locate in the ICollection<T>.

Returns

bool

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

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.

CopyTo(KeyValuePair<string, TomlNode?>[], int)

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

public void CopyTo(KeyValuePair<string, TomlNode?>[] array, int arrayIndex)

Parameters

array KeyValuePair<string, TomlNode>[]

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.

DeepClone()

Creates a deep copy of this node and its entire subtree.

public override TomlNode DeepClone()

Returns

TomlNode

An independent clone with no parent.

GetEnumerator()

Returns an enumerator that iterates through the collection.

public IEnumerator<KeyValuePair<string, TomlNode?>> GetEnumerator()

Returns

IEnumerator<KeyValuePair<string, TomlNode>>

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

Remarks

Entries are enumerated in insertion order.

GetValueKind()

Gets the kind of value this node represents.

public override TomlValueKind GetValueKind()

Returns

TomlValueKind

The TomlValueKind of this node.

Remove(KeyValuePair<string, TomlNode?>)

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

public bool Remove(KeyValuePair<string, TomlNode?> item)

Parameters

item KeyValuePair<string, TomlNode>

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.

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.

ToString()

Returns a string representation of this node.

public override string ToString()

Returns

string

A textual rendering of this node.

TryGetPropertyValue(string, out TomlNode?)

Attempts to get the value associated with the specified property name.

public bool TryGetPropertyValue(string propertyName, out TomlNode? value)

Parameters

propertyName string

The property name to look up.

value TomlNode

When this method returns true, the value associated with propertyName; otherwise null.

Returns

bool

true when a value is associated with propertyName; otherwise false.

TryGetValue(string, out TomlNode?)

Gets the value associated with the specified key.

public bool TryGetValue(string key, out TomlNode? value)

Parameters

key string

The key whose value to get.

value TomlNode

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(Utf8TomlWriter)

Writes the normalized TOML encoding of this node to the supplied writer.

public override void WriteTo(Utf8TomlWriter writer)

Parameters

writer Utf8TomlWriter

The destination writer.

Remarks

Because a TOML document's root must be a table, the writer produces a document only when the outermost node is a TomlObject. Writing a node whose root is a scalar or array yields no document; use ToUtf8Bytes() to obtain the normalized bytes, which validates the table-root rule.

Exceptions

TomlSerializationException

Thrown when the subtree rooted at this node contains a null entry, which has no TOML representation.

Explicit Interface Implementations

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

ProductVersions
.NET8, 10