TomlArray Class
Definition
Represents a mutable TOML array as an ordered, index-addressable collection of child nodes.
public sealed class TomlArray : TomlNode, IList<TomlNode?>, ICollection<TomlNode?>, IEnumerable<TomlNode?>, IEnumerable
- Inheritance
-
TomlArray
- Implements
- Inherited Members
- Extension Methods
Remarks
Elements are kept in insertion order, which is also the order in which they are serialized. An element may be null in memory, but an array containing a null element cannot be written because TOML has no null token. Adding a node that already belongs to a container, this one included, or adding the array to itself or to one of its own descendants, throws an InvalidOperationException; removing or replacing an element detaches it, clearing its Parent so it can be added to another container.
var tags = new TomlArray(TomlValue.Create("a"), TomlValue.Create("b"));
tags.Add(TomlValue.Create("c"));
var root = new TomlObject { ["tags"] = tags };
byte[] utf8 = root.ToUtf8Bytes(); // tags = [ "a", "b", "c" ]
Constructors
TomlArray()
Initializes a new instance of the TomlArray class that is empty.
public TomlArray()
TomlArray(params TomlNode?[])
Initializes a new instance of the TomlArray class containing the supplied items in order.
public TomlArray(params TomlNode?[] items)
Parameters
itemsTomlNode[]The initial elements.
Remarks
When an item is rejected, construction fails and every item is left with the parent it had before, so the items can be added elsewhere.
Exceptions
- ArgumentNullException
Thrown when
itemsis null.- InvalidOperationException
Thrown when an element already belongs to a container, or appears in
itemsmore than once.
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[int]
Gets or sets the element at the specified index.
public TomlNode? this[int index] { get; set; }
Parameters
indexintThe zero-based index of the element.
Property Value
Remarks
Assigning over an existing element detaches the replaced node, clearing its Parent. Assigning an element over itself leaves the array unchanged.
Exceptions
- ArgumentOutOfRangeException
Thrown when
indexis outside the bounds of the list.- InvalidOperationException
Thrown when the assigned node already belongs to a container, this array included, and is not the element at
index; or when the assigned node is this array or one of its ancestors.
Methods
Add(TomlNode?)
Adds an item to the ICollection<T>.
public void Add(TomlNode? item)
Parameters
itemTomlNodeThe object to add to the ICollection<T>.
Exceptions
- NotSupportedException
The ICollection<T> is read-only.
Clear()
Removes all items from the ICollection<T>.
public void Clear()
Exceptions
- NotSupportedException
The ICollection<T> is read-only.
Contains(TomlNode?)
Determines whether the ICollection<T> contains a specific value.
public bool Contains(TomlNode? item)
Parameters
itemTomlNodeThe object to locate in the ICollection<T>.
Returns
- bool
true if
itemis found in the ICollection<T>; otherwise, false.
CopyTo(TomlNode?[], int)
Copies the elements of the ICollection<T> to an Array, starting at a particular Array index.
public void CopyTo(TomlNode?[] array, int arrayIndex)
Parameters
arrayTomlNode[]The one-dimensional Array that is the destination of the elements copied from ICollection<T>. The Array must have zero-based indexing.
arrayIndexintThe zero-based index in
arrayat which copying begins.
Exceptions
- ArgumentNullException
arrayis null.- ArgumentOutOfRangeException
arrayIndexis less than 0.- ArgumentException
The number of elements in the source ICollection<T> is greater than the available space from
arrayIndexto the end of the destinationarray.
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<TomlNode?> GetEnumerator()
Returns
- IEnumerator<TomlNode>
An enumerator that can be used to iterate through the collection.
GetValueKind()
Gets the kind of value this node represents.
public override TomlValueKind GetValueKind()
Returns
- TomlValueKind
The TomlValueKind of this node.
IndexOf(TomlNode?)
Determines the index of a specific item in the IList<T>.
public int IndexOf(TomlNode? item)
Parameters
Returns
- int
The index of
itemif found in the list; otherwise, -1.
Insert(int, TomlNode?)
Inserts an item to the IList<T> at the specified index.
public void Insert(int index, TomlNode? item)
Parameters
indexintThe zero-based index at which
itemshould be inserted.itemTomlNodeThe object to insert into the IList<T>.
Remarks
The item is attached only once it has been inserted, so an insert rejected because the index is outside the array leaves the item with the parent it had.
Exceptions
- ArgumentOutOfRangeException
indexis not a valid index in the IList<T>.- NotSupportedException
The IList<T> is read-only.
Remove(TomlNode?)
Removes the first occurrence of a specific object from the ICollection<T>.
public bool Remove(TomlNode? item)
Parameters
itemTomlNodeThe object to remove from the ICollection<T>.
Returns
- bool
true if
itemwas successfully removed from the ICollection<T>; otherwise, false. This method also returns false ifitemis not found in the original ICollection<T>.
Exceptions
- NotSupportedException
The ICollection<T> is read-only.
RemoveAt(int)
Removes the IList<T> item at the specified index.
public void RemoveAt(int index)
Parameters
indexintThe zero-based index of the item to remove.
Exceptions
- ArgumentOutOfRangeException
indexis not a valid index in the IList<T>.- NotSupportedException
The IList<T> is read-only.
ToString()
Returns a string representation of this node.
public override string ToString()
Returns
- string
A textual rendering of this node.
WriteTo(Utf8TomlWriter)
Writes the normalized TOML encoding of this node to the supplied writer.
public override void WriteTo(Utf8TomlWriter writer)
Parameters
writerUtf8TomlWriterThe 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
| Product | Versions |
|---|---|
| .NET | 8, 10 |