rm::toml::Node类 参考

共享底层节点树所有权的只读节点句柄 更多...

#include <rmvl/core/toml.hpp>

rm::toml::Node 的协作图:

Public 成员函数
	Node () noexcept=default
	构造不关联任何节点树的无效节点
bool	valid () const noexcept
	operator bool () const noexcept
NodeType	type () const noexcept
bool	isTable () const noexcept
bool	isArray () const noexcept
std::size_t	size () const noexcept
bool	contains (std::string_view key) const noexcept
	判断表中是否存在指定键
Node	operator[] (std::string_view key) const noexcept
	查询表的子节点，不插入或修改节点
Node	operator[] (std::size_t index) const noexcept
	查询数组元素
std::vector< std::string_view >	keys () const
	获取表的全部键名
template<typename T>
bool	read (T &value) const
	读取节点并转换为指定的 C++ 类型
template<typename T>
std::optional< T >	as () const
	读取节点并返回可选的转换结果
template<typename T>
T	valueOr (T fallback) const
	读取节点，转换失败时使用默认值

友元
Node	loads (std::string_view source, Error *error=nullptr)
	从内存中的 UTF-8 文本解析 TOML 1.0 配置

详细描述

共享底层节点树所有权的只读节点句柄

• 拷贝仅共享节点树所有权，不复制节点树，子节点可独立于根句柄存活
• 默认构造、查找失败或移出后的句柄无效，可用 valid() 或显式布尔转换判断
• 布尔转换只判断节点有效性，保存 false 的布尔节点仍是有效节点
• 节点树不可修改，同一棵节点树支持多个线程并发只读访问
• keys() 返回的键名视图在底层节点树最后一个有效句柄销毁前有效

构造及析构函数说明

Node()

rm::toml::Node::Node ( )

defaultnoexcept

构造不关联任何节点树的无效节点

成员函数说明

as()

template<typename T>

std::optional< T > rm::toml::Node::as

(

)

const

读取节点并返回可选的转换结果

模板参数

T	目标类型，需能默认构造，支持范围和转换规则与 read() 相同

返回

成功时返回目标值，转换失败时返回 std::nullopt

注解

T 为 std::optional<U> 时，读取无效节点得到的是外层有值、内层无值的结果

函数调用图:

contains()

bool rm::toml::Node::contains ( std::string_view key ) const

noexcept

判断表中是否存在指定键

参数

[in]

key

字面键名，不解释点分路径

返回

当前节点为表且键存在时返回 true，否则返回 false

函数调用图:

isArray()

bool rm::toml::Node::isArray ( ) const

inlinenoexcept

返回

是否为数组节点，包含表数组，无效节点返回 false

函数调用图:

isTable()

bool rm::toml::Node::isTable ( ) const

inlinenoexcept

返回

是否为表节点，包含普通表和内联表，无效节点返回 false

函数调用图:

keys()

std::vector< std::string_view > rm::toml::Node::keys

(

)

const

获取表的全部键名

返回

键名视图数组，非表节点或无效节点返回空数组，不保证键的排列顺序

注解

返回的视图不持有节点树所有权，使用期间必须保留至少一个属于该节点树的有效 Node

函数调用图:

operator bool()

rm::toml::Node::operator bool ( ) const

inlineexplicitnoexcept

返回

与 valid() 相同，可用于 if、!、&& 等条件表达式

函数调用图:

operator[]() [1/2]

Node rm::toml::Node::operator[] ( std::size_t index ) const

noexcept

查询数组元素

参数

[in]

index

从 0 开始的元素下标

返回

当前节点为数组且下标有效时返回共享节点树所有权的子节点，否则返回无效节点

函数调用图:

operator[]() [2/2]

Node rm::toml::Node::operator[] ( std::string_view key ) const

noexcept

查询表的子节点，不插入或修改节点

参数

[in]

key

字面键名，例如 "a.b" 表示单个键，嵌套访问应使用 node["a"]["b"]

返回

当前节点为表且键存在时返回共享节点树所有权的子节点，否则返回无效节点

函数调用图:

read()

template<typename T>

bool rm::toml::Node::read

(

T &

value

)

const

读取节点并转换为指定的 C++ 类型

模板参数

T	支持 std::string、bool、整数、浮点、枚举、Date、Time、DateTime、std::optional、 std::vector、std::array、以 std::string 为键的 std::map/std::unordered_map，以及 ADL 自定义类型

参数

[out]

value

转换结果，返回 false 时保持其原值不变

返回

转换成功返回 true，节点类型不符、数值越界或容器元素转换失败返回 false

• 严格区分字符串、整数、浮点和布尔，不进行字符串到数字或整数到浮点的隐式转换
• 整数转换检查目标类型范围，枚举通过其底层整数类型转换，不检查是否为已声明的枚举项
• 浮点转换检查有限值是否超出目标类型范围，允许精度损失，保留无穷和 NaN
• std::array 要求节点数组长度完全匹配，容器元素递归使用相同的转换规则
• 无效节点读取为 std::optional 时会清空目标并返回 true，有效节点按其包含的类型转换
• 自定义类型需能默认构造，在其命名空间提供 bool toml_decode(const rm::toml::Node &, T &) 解码在临时对象上完成，返回 false 时不覆盖调用方对象

  注解

  本函数不捕获内存分配异常或用户自定义解码函数抛出的异常

函数调用图:

size()

std::size_t rm::toml::Node::size ( ) const

noexcept

返回

表的键数量或数组的元素数量，其他类型及无效节点返回 0

type()

NodeType rm::toml::Node::type ( ) const

noexcept

返回

节点类型，无效节点返回 NodeType::Undefined

valid()

bool rm::toml::Node::valid ( ) const

inlinenodiscardnoexcept

返回

是否关联有效节点，与节点保存的值无关

函数调用图:

valueOr()

template<typename T>

T rm::toml::Node::valueOr

(

T

fallback

)

const

读取节点，转换失败时使用默认值

模板参数

T	目标类型，需能默认构造，支持范围和转换规则与 read() 相同

参数

[in]

fallback

节点缺失、类型不符或数值越界等转换失败时使用的默认值

返回

成功时返回转换值，否则返回 fallback

注解

异常仍会向调用方传播，不会因发生异常而返回默认值

函数调用图:

友元及相关符号说明

loads

Node loads ( std::string_view source, Error * error = nullptr )

friend

从内存中的 UTF-8 文本解析 TOML 1.0 配置

参数

[in]	source	TOML 文本，不要求以空字符结尾
[out]	error	可选的错误输出，默认为 nullptr，成功时清空已有错误

返回

成功时返回共享节点树所有权的 Table 根节点，空文本返回空 Table，失败返回无效节点

编码或语法错误、重复键和非法表定义等问题通过返回值和 ErrorCode::Parse 报告，不抛出异常

注解

• 解析完成后不依赖 source 的内存，调用方可以释放或修改原始文本
• 内存分配失败等标准库异常不在此错误协议内，本函数不保证 noexcept

参见

load()