Table of Contents

TomlElement Struct

Definition

Namespace
Bodu.Text.Toml.Document
Assembly
Bodu.Text.Toml.dll
Package
Bodu.Text.Toml 1.0.0
Source
TomlElement.ArrayEnumerator.cs

Represents a single read-only value within a TomlDocument. The element is a lightweight view - a pair of the owning document and a row index - so copying it is cheap and never materializes a node.

public readonly struct TomlElement
Inherited Members
Extension Methods

Remarks

An element is valid only for the lifetime of its owning TomlDocument. After the document is disposed, any member access throws ObjectDisposedException.

TOML defines eight scalar value kinds - string, integer, float, Boolean, and four date/time forms - alongside arrays and tables. Each scalar accessor returns the value decoded once during parsing and throws InvalidOperationException when invoked on an element of a different kind. 

using TomlDocument document = TomlDocument.Parse("""
    name = "orders"
    port = 8080
    tags = ["a", "b"]
    """);

TomlElement root = document.RootElement;
var name = root.GetProperty("name").GetString();       // "orders"
var port = root.GetProperty("port").GetInt64();        // 8080

foreach (TomlElement tag in root.GetProperty("tags").EnumerateArray())
{
    // "a", "b"
}

Properties

this[int]

Gets the element at the supplied index within this array element.

public TomlElement this[int index] { get; }

Parameters

index int

The zero-based index of the element to retrieve.

Property Value

TomlElement

The element at index.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Array.

ArgumentOutOfRangeException

Thrown when index is negative or not less than the array length.

ValueKind

Gets the kind of this element.

public TomlValueKind ValueKind { get; }

Property Value

TomlValueKind

The value kind.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

Methods

EnumerateArray()

Returns an enumerator that iterates the elements of this array element in order.

public TomlElement.ArrayEnumerator EnumerateArray()

Returns

TomlElement.ArrayEnumerator

An TomlElement.ArrayEnumerator over the array's elements.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Array.

EnumerateObject()

Returns an enumerator that iterates the key/value pairs of this table element in stored order.

public TomlElement.ObjectEnumerator EnumerateObject()

Returns

TomlElement.ObjectEnumerator

An TomlElement.ObjectEnumerator over the table's properties.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not a Table.

GetArrayLength()

Gets the number of elements in this array element.

public int GetArrayLength()

Returns

int

The element count.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Array.

GetBoolean()

Gets the value of this Boolean element.

public bool GetBoolean()

Returns

bool

The decoded Boolean value.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not a Boolean.

GetDateOnly()

Gets the value of this local-date element.

public DateOnly GetDateOnly()

Returns

DateOnly

The decoded local date value.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not a LocalDate.

GetDateTime()

Gets the value of this local-date-time element.

public DateTime GetDateTime()

Returns

DateTime

The decoded local date-time value, whose Kind is Unspecified .

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not a LocalDateTime.

GetDateTimeOffset()

Gets the value of this offset-date-time element.

public DateTimeOffset GetDateTimeOffset()

Returns

DateTimeOffset

The decoded offset date-time value.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an OffsetDateTime.

GetDouble()

Gets the value of this float element as an IEEE 754 binary64 floating-point value.

public double GetDouble()

Returns

double

The decoded floating-point value.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not a Float.

GetInt64()

Gets the value of this integer element as a 64-bit signed integer.

public long GetInt64()

Returns

long

The decoded integer value.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not an Integer.

GetProperty(string)

Gets the value of the property with the supplied name within this table element.

public TomlElement GetProperty(string propertyName)

Parameters

propertyName string

The name of the property to retrieve.

Returns

TomlElement

The value element of the matching property.

Exceptions

ArgumentNullException

Thrown when propertyName is null.

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not a Table.

KeyNotFoundException

Thrown when no property named propertyName exists.

GetString()

Gets the value of this string element.

public string GetString()

Returns

string

The decoded string value.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not a String.

GetTimeOnly()

Gets the value of this local-time element.

public TimeOnly GetTimeOnly()

Returns

TimeOnly

The decoded local time value.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not a LocalTime.

ToString()

Returns a textual representation of this element.

public override string ToString()

Returns

string

The decoded value for a scalar element, or the literal name of the value kind for an array or table.

Remarks

Container values are not re-serialized; the kind name is returned instead to keep the operation allocation-light. Scalar values are formatted with the invariant culture.

Exceptions

ObjectDisposedException

Thrown when the owning document has been disposed.

TryGetProperty(string, out TomlElement)

Attempts to get the value of the property with the supplied name within this table element.

public bool TryGetProperty(string propertyName, out TomlElement value)

Parameters

propertyName string

The name of the property to retrieve.

value TomlElement

When this method returns, the value element of the matching property; otherwise the default element.

Returns

bool

true when a matching property was found; otherwise false.

Exceptions

ArgumentNullException

Thrown when propertyName is null.

ObjectDisposedException

Thrown when the owning document has been disposed.

InvalidOperationException

Thrown when this element is not a Table.

WriteTo(Utf8TomlWriter)

Writes this element's value to the supplied writer at the writer's current position.

public void WriteTo(Utf8TomlWriter writer)

Parameters

writer Utf8TomlWriter

The destination writer.

Remarks

A scalar element writes its decoded value, an array writes its elements in order, and a table writes its key/value pairs in stored order. The writer's own state machine governs where a value may be written, so a non-table element cannot be written at a TOML document root.

Exceptions

InvalidOperationException

Thrown when this element is the default value and belongs to no document.

ObjectDisposedException

Thrown when the owning document has been disposed.

Applies to

ProductVersions
.NET8, 10