TomlNode Class
Definition
Represents a single node in a mutable TOML document object model, serving as the base for the three concrete node kinds - TomlObject, TomlArray, and TomlValue.
public abstract class TomlNode- Inheritance
-
TomlNode
- Derived
- Inherited Members
- Extension Methods
Examples
// Parse a document, edit it in place, add a nested table, then serialize the result.
TomlObject config = TomlNode.Parse("name = \"app\"\nport = 8080\n"u8)!.AsObject();
config["port"] = 9090; // replace a scalar
config["debug"] = true; // add a scalar
var server = new TomlObject();
server["host"] = "localhost";
config["server"] = server; // add a nested table
// Emits the scalar members as key/value lines, then the nested table as a [server] block.
string toml = config.ToString();Remarks
A node tree is editable in place: containers expose the standard collection surfaces, scalar values can be replaced, and any node can be re-serialized to normalized TOML through WriteTo(Utf8TomlWriter) or ToUtf8Bytes(). TOML defines eight scalar value kinds - a string, a 64-bit integer, a float, a Boolean, and the four date-time kinds - and has no null token, so the model defines no null node; a tree that still contains a null entry cannot be written.
A TOML document's root is always a table, so a document cannot be a bare scalar or array. Parse(ReadOnlySpan<byte>) therefore yields a TomlObject root, and serializing a node whose root is not a table throws.
Each node has at most one parent. Adding a node that already belongs to another container throws an InvalidOperationException.
Properties
this[int]
Gets or sets the element at the specified index, treating this node as a TomlArray.
public TomlNode? this[int index] { get; set; }Parameters
indexintThe zero-based index of the element.
Property Value
- TomlNode
The element at
index.
Exceptions
- InvalidOperationException
Thrown when this node is not a TomlArray.
- ArgumentOutOfRangeException
Thrown when
indexis outside the bounds of the array.
this[string]
Gets or sets the value associated with the specified property name, treating this node as a TomlObject.
public TomlNode? this[string propertyName] { get; set; }Parameters
propertyNamestringThe property name to look up.
Property Value
- TomlNode
The value associated with
propertyName.
Exceptions
- InvalidOperationException
Thrown when this node is not a TomlObject.
- ArgumentNullException
Thrown when
propertyNameis null.
Parent
Gets the node that contains this node, or null when this node is the root of its tree.
public TomlNode? Parent { get; }Property Value
Root
Gets the topmost node of the tree this node belongs to.
public TomlNode Root { get; }Property Value
Methods
AsArray()
Returns this node as a TomlArray.
public TomlArray AsArray()Returns
Exceptions
- InvalidOperationException
Thrown when this node is not a TomlArray.
AsObject()
Returns this node as a TomlObject.
public TomlObject AsObject()Returns
- TomlObject
This node cast to TomlObject.
Exceptions
- InvalidOperationException
Thrown when this node is not a TomlObject.
AsValue()
Returns this node as a TomlValue.
public TomlValue AsValue()Returns
Exceptions
- InvalidOperationException
Thrown when this node is not a TomlValue.
DeepClone()
Creates a deep copy of this node and its entire subtree.
public abstract TomlNode DeepClone()Returns
- TomlNode
An independent clone with no parent.
DeepEquals(TomlNode?, TomlNode?)
Determines whether two node trees are structurally equal.
public static bool DeepEquals(TomlNode? node1, TomlNode? node2)Parameters
node1TomlNodeThe first node, which may be null.
node2TomlNodeThe second node, which may be null.
Returns
- bool
true when both nodes are null or represent the same value kind with equal content; otherwise false.
Remarks
Scalars compare by kind and value. Arrays compare element-wise in order, and tables compare by key set with equal values, independently of in-memory key order.
GetValueKind()
Gets the kind of value this node represents.
public abstract TomlValueKind GetValueKind()Returns
- TomlValueKind
The TomlValueKind of this node.
GetValue<T>()
Returns the scalar value of this node converted to the requested type, treating this node as a TomlValue.
public T GetValue<T>()Returns
- T
The converted scalar value.
Type Parameters
TThe type to convert the scalar value to.
Exceptions
- InvalidOperationException
Thrown when this node is not a TomlValue, or its stored value cannot be converted to
T.
Parse(ReadOnlySpan<byte>)
Parses a single TOML document into a node tree.
public static TomlNode? Parse(ReadOnlySpan<byte> utf8Toml)Parameters
utf8TomlReadOnlySpan<byte>The UTF-8 TOML source bytes.
Returns
- TomlNode
The root node of the parsed tree, which is always a TomlObject.
Exceptions
- TomlFormatException
Thrown when
utf8Tomlis not a valid TOML document.
Parse(ReadOnlySpan<byte>, TomlNodeOptions)
Parses a single TOML document into a node tree, using the supplied options for every table created while parsing.
public static TomlNode? Parse(ReadOnlySpan<byte> utf8Toml, TomlNodeOptions options)Parameters
utf8TomlReadOnlySpan<byte>The UTF-8 TOML source bytes.
optionsTomlNodeOptionsThe node options controlling property-name case sensitivity.
Returns
- TomlNode
The root node of the parsed tree, which is always a TomlObject.
Remarks
Every TomlObject materialized while parsing adopts the comparison selected by
options, so a case-insensitive parse yields a tree whose table lookups ignore case.
Exceptions
- TomlFormatException
Thrown when
utf8Tomlis not a valid TOML document.
ToString()
Returns a string representation of this node.
public override abstract string ToString()Returns
- string
A textual rendering of this node.
ToUtf8Bytes()
Serializes this node to a new normalized TOML byte array.
public byte[] ToUtf8Bytes()Returns
- byte[]
The UTF-8 TOML encoding of this node.
Exceptions
- TomlSerializationException
Thrown when this node's root is not a TomlObject, or the subtree rooted at this node contains a null entry, which has no TOML representation.
WriteTo(Utf8TomlWriter)
Writes the normalized TOML encoding of this node to the supplied writer.
public abstract 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.
Operators
explicit operator bool(TomlNode)
Reads the scalar value of the supplied node as a Boolean.
public static explicit operator bool(TomlNode node)Parameters
nodeTomlNodeThe node to read.
Returns
Exceptions
- ArgumentNullException
Thrown when
nodeis null.- InvalidOperationException
Thrown when
nodeis not a Boolean-valued TomlValue.
explicit operator DateOnly(TomlNode)
Reads the scalar value of the supplied node as a local date.
public static explicit operator DateOnly(TomlNode node)Parameters
nodeTomlNodeThe node to read.
Returns
Exceptions
- ArgumentNullException
Thrown when
nodeis null.- InvalidOperationException
Thrown when
nodeis not a local-date-valued TomlValue.
explicit operator DateTime(TomlNode)
Reads the scalar value of the supplied node as a local date-time.
public static explicit operator DateTime(TomlNode node)Parameters
nodeTomlNodeThe node to read.
Returns
Exceptions
- ArgumentNullException
Thrown when
nodeis null.- InvalidOperationException
Thrown when
nodeis not a local-date-time-valued TomlValue.
explicit operator DateTimeOffset(TomlNode)
Reads the scalar value of the supplied node as an offset date-time.
public static explicit operator DateTimeOffset(TomlNode node)Parameters
nodeTomlNodeThe node to read.
Returns
Exceptions
- ArgumentNullException
Thrown when
nodeis null.- InvalidOperationException
Thrown when
nodeis not an offset-date-time-valued TomlValue.
explicit operator double(TomlNode)
Reads the scalar value of the supplied node as a floating-point value.
public static explicit operator double(TomlNode node)Parameters
nodeTomlNodeThe node to read.
Returns
Exceptions
- ArgumentNullException
Thrown when
nodeis null.- InvalidOperationException
Thrown when
nodeis not a float-valued TomlValue.
explicit operator int(TomlNode)
Reads the scalar value of the supplied node as a 32-bit integer.
public static explicit operator int(TomlNode node)Parameters
nodeTomlNodeThe node to read.
Returns
Exceptions
- ArgumentNullException
Thrown when
nodeis null.- InvalidOperationException
Thrown when
nodeis not an integer-valued TomlValue whose value fits a 32-bit integer.
explicit operator long(TomlNode)
Reads the scalar value of the supplied node as a 64-bit integer.
public static explicit operator long(TomlNode node)Parameters
nodeTomlNodeThe node to read.
Returns
Exceptions
- ArgumentNullException
Thrown when
nodeis null.- InvalidOperationException
Thrown when
nodeis not an integer-valued TomlValue.
explicit operator string(TomlNode)
Reads the scalar value of the supplied node as a string.
public static explicit operator string(TomlNode node)Parameters
nodeTomlNodeThe node to read.
Returns
Exceptions
- ArgumentNullException
Thrown when
nodeis null.- InvalidOperationException
Thrown when
nodeis not a string-valued TomlValue.
explicit operator TimeOnly(TomlNode)
Reads the scalar value of the supplied node as a local time.
public static explicit operator TimeOnly(TomlNode node)Parameters
nodeTomlNodeThe node to read.
Returns
Exceptions
- ArgumentNullException
Thrown when
nodeis null.- InvalidOperationException
Thrown when
nodeis not a local-time-valued TomlValue.
implicit operator TomlNode(bool)
Creates a TomlValue that wraps the supplied Boolean value.
public static implicit operator TomlNode(bool value)Parameters
valueboolThe Boolean value to wrap.
Returns
implicit operator TomlNode(DateOnly)
Creates a TomlValue that wraps the supplied local date value.
public static implicit operator TomlNode(DateOnly value)Parameters
valueDateOnlyThe local date value to wrap.
Returns
implicit operator TomlNode(DateTime)
Creates a TomlValue that wraps the supplied local date-time value.
public static implicit operator TomlNode(DateTime value)Parameters
valueDateTimeThe local date-time value to wrap.
Returns
implicit operator TomlNode(DateTimeOffset)
Creates a TomlValue that wraps the supplied offset date-time value.
public static implicit operator TomlNode(DateTimeOffset value)Parameters
valueDateTimeOffsetThe offset date-time value to wrap.
Returns
implicit operator TomlNode(double)
Creates a TomlValue that wraps the supplied floating-point value.
public static implicit operator TomlNode(double value)Parameters
valuedoubleThe floating-point value to wrap.
Returns
implicit operator TomlNode(int)
Creates a TomlValue that wraps the supplied 32-bit integer.
public static implicit operator TomlNode(int value)Parameters
valueintThe integer to wrap.
Returns
implicit operator TomlNode(long)
Creates a TomlValue that wraps the supplied 64-bit integer.
public static implicit operator TomlNode(long value)Parameters
valuelongThe integer to wrap.
Returns
implicit operator TomlNode(string)
Creates a TomlValue that wraps the supplied string.
public static implicit operator TomlNode(string value)Parameters
valuestringThe string to wrap.
Returns
implicit operator TomlNode(TimeOnly)
Creates a TomlValue that wraps the supplied local time value.
public static implicit operator TomlNode(TimeOnly value)Parameters
valueTimeOnlyThe local time value to wrap.
Returns
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |