libcamera::ValueNode Class Reference

A class representing a tree structure of values. More...

Public Member Functions
template<typename T>
	ValueNode (T &&value)
	Construct a ValueNode instance with a value.
bool	isValue () const
	Return whether the ValueNode is a value.
bool	isList () const
	Return whether the ValueNode is a list.
bool	isDictionary () const
	Return whether the ValueNode is a dictionary.
bool	isEmpty () const
	Return whether the ValueNode is an empty.
	operator bool () const
	Return whether the ValueNode is a non-empty.
std::size_t	size () const
	Retrieve the number of elements in a dictionary or list ValueNode.
template<typename T>
std::optional< T >	get () const
	Parse the ValueNode as a T value.
template<typename T, typename U>
T	get (U &&defaultValue) const
	Parse the ValueNode as a T value.
template<typename T>
void	set (T &&value)
	Set the value of a ValueNode.
DictAdapter	asDict ()
	Wrap a dictionary ValueNode in an adapter that exposes iterators.
ListAdapter	asList ()
	Wrap a list ValueNode in an adapter that exposes iterators.
ConstDictAdapter	asDict () const
	Wrap a dictionary ValueNode in an adapter that exposes iterators.
ConstListAdapter	asList () const
	Wrap a list ValueNode in an adapter that exposes iterators.
ValueNode *	at (std::size_t index)
	Retrieve the element from list ValueNode by index.
const ValueNode &	operator[] (std::size_t index) const
	Retrieve the element from list ValueNode by index.
bool	contains (std::string_view key) const
	Check if an element of a dictionary exists.
ValueNode *	at (std::string_view key)
	Retrieve a member by key from the dictionary.
const ValueNode &	operator[] (std::string_view key) const
	Retrieve a member by key from the dictionary.
const ValueNode &	operator[] (std::initializer_list< std::string_view > path) const
	Retrieve a descendant node by path.
ValueNode *	add (std::unique_ptr< ValueNode > &&child)
	Add a child node to a list.
ValueNode *	add (std::string key, std::unique_ptr< ValueNode > &&child)
	Add a child node to a dictionary.
ValueNode *	add (std::initializer_list< std::string_view > path, std::unique_ptr< ValueNode > &&child)
	Add a child node at the given path.
void	erase (std::string_view key)
	Erase a child node in a dictionary.
void	erase (std::initializer_list< std::string_view > path)
	Erase the child node at the given path.

Friends
template<typename T>
struct	Accessor

Detailed Description

A class representing a tree structure of values.

The ValueNode class is designed to model a tree of values. Each node in the tree is represented by a ValueNode instance. Intermediate nodes store children either as an ordered list (sequence) or a string-indexed dictionary (mapping). Leaf nodes can be empty or store a string value.

Constructor & Destructor Documentation

ValueNode()

template<typename T>

libcamera::ValueNode::ValueNode ( T && value )

inline

Construct a ValueNode instance with a value.

Template Parameters

T	Type of the value

Parameters

[in]

value

The value

Member Function Documentation

add() [1/3]

ValueNode * libcamera::ValueNode::add	(	std::initializer_list< std::string_view >	path,
		std::unique_ptr< ValueNode > &&	child )

Add a child node at the given path.

Parameters

[in]	path	The path
[in]	child	The child node

Add the child node at the given path starting at this node. Missing nodes are created along the path. Nodes along the path must be empty (in which case they are converted to the Type::Dictionary type), be a dictionary, or be missing. Otherwise, the function returns a nullptr and the child is not modified.

Path elements are unique in the context of a parent node. If a child with the same key already exist at the end of the path, the function returns a nullptr and the child is not modified.

Note

Any node added along the path will remain even if this function returns a failure.

Returns

A pointer to the child node if successfully added, nullptr otherwise

add() [2/3]

ValueNode * libcamera::ValueNode::add	(	std::string	key,
		std::unique_ptr< ValueNode > &&	child )

Add a child node to a dictionary.

Parameters

[in]	key	The dictionary key
[in]	child	The child node

Add the child node with the given key to this node's children. This node must be empty, in which case it is converted to the Type::Dictionary type, or be a dictionary. Otherwise, the function returns a nullptr and the child is not modified.

Keys are unique. If a child with the same key already exists, the function returns a nullptr and the child is not modified.

Returns

A pointer to the child node if successfully added, nullptr otherwise

add() [3/3]

ValueNode * libcamera::ValueNode::add

(

std::unique_ptr< ValueNode > &&

child

)

Add a child node to a list.

Parameters

[in]

child

The child node

Append the child node as the last element of this node's children list. This node must be empty, in which case it is converted to the Type::List type, or be a list. Otherwise, the function returns a nullptr and the child is not modified.

Returns

A pointer to the child node if successfully added, nullptr otherwise

asDict() [1/2]

DictAdapter libcamera::ValueNode::asDict ( )

inline

Wrap a dictionary ValueNode in an adapter that exposes iterators.

The ValueNode class doesn't directly implement iterators, as the iterator type depends on whether the node is a Dictionary or List. This function wraps a ValueNode of Dictionary type into an adapter that exposes iterators, as well as begin() and end() functions, allowing usage of range-based for loops with ValueNode. As mappings are not ordered, the iteration order is not specified.

The iterator's value_type is a std::pair<const std::string &, const ValueNode &>.

If the ValueNode is not of Dictionary type, the returned adapter operates as an empty container.

Returns

An adapter of unspecified type compatible with range-based for loops

asDict() [2/2]

ConstDictAdapter libcamera::ValueNode::asDict ( ) const

inline

Wrap a dictionary ValueNode in an adapter that exposes iterators.

The ValueNode class doesn't directly implement iterators, as the iterator type depends on whether the node is a Dictionary or List. This function wraps a ValueNode of Dictionary type into an adapter that exposes iterators, as well as begin() and end() functions, allowing usage of range-based for loops with ValueNode. As mappings are not ordered, the iteration order is not specified.

The iterator's value_type is a std::pair<const std::string &, const ValueNode &>.

If the ValueNode is not of Dictionary type, the returned adapter operates as an empty container.

Returns

An adapter of unspecified type compatible with range-based for loops

asList() [1/2]

ListAdapter libcamera::ValueNode::asList ( )

inline

Wrap a list ValueNode in an adapter that exposes iterators.

The ValueNode class doesn't directly implement iterators, as the iterator type depends on whether the node is a Dictionary or List. This function wraps a ValueNode of List type into an adapter that exposes iterators, as well as begin() and end() functions, allowing usage of range-based for loops with ValueNode. As lists are ordered, the iteration order matches the order in which child nodes have been added.

The iterator's value_type is a const ValueNode &.

If the ValueNode is not of List type, the returned adapter operates as an empty container.

Returns

An adapter of unspecified type compatible with range-based for loops

asList() [2/2]

ConstListAdapter libcamera::ValueNode::asList ( ) const

inline

Wrap a list ValueNode in an adapter that exposes iterators.

The ValueNode class doesn't directly implement iterators, as the iterator type depends on whether the node is a Dictionary or List. This function wraps a ValueNode of List type into an adapter that exposes iterators, as well as begin() and end() functions, allowing usage of range-based for loops with ValueNode. As lists are ordered, the iteration order matches the order in which child nodes have been added.

The iterator's value_type is a const ValueNode &.

If the ValueNode is not of List type, the returned adapter operates as an empty container.

Returns

An adapter of unspecified type compatible with range-based for loops

at() [1/2]

ValueNode * libcamera::ValueNode::at

(

std::size_t

index

)

Retrieve the element from list ValueNode by index.

Parameters

[in]

index

The element index

This function retrieves an element of the ValueNode. Only ValueNode instances of List type associate elements with an index, calling this function on other types of instances or with an invalid index returns a null pointer.

Returns

The ValueNode corresponding to index

at() [2/2]

ValueNode * libcamera::ValueNode::at

(

std::string_view

key

)

Retrieve a member by key from the dictionary.

Parameters

[in]

key

The element key

This function retrieves a member of a ValueNode by key. Only ValueNode instances of Dictionary type associate elements with keys, calling this function on other types of instances or with a nonexistent key returns a null pointer.

Returns

The ValueNode corresponding to the key member

contains()

bool libcamera::ValueNode::contains

(

std::string_view

key

)

const

Check if an element of a dictionary exists.

Parameters

[in]

key

The element key

This function checks if the ValueNode contains an element for the given key. Only ValueNode instances of Dictionary type associate elements with keys, calling this function on other types of instances is invalid and results in undefined behaviour.

Returns

True if an element exists, false otherwise

erase() [1/2]

void libcamera::ValueNode::erase

(

std::initializer_list< std::string_view >

path

)

Erase the child node at the given path.

Parameters

[in]

path

The path

Erase the child node at the given path. If no child node exists for the path, the function returns without performing any operation.

erase() [2/2]

void libcamera::ValueNode::erase

(

std::string_view

key

)

Erase a child node in a dictionary.

Parameters

[in]

key

The dictionary key

Erase the child node referenced by key in a dictionary node. If the key does not exist, or if this node is not a dictionary, the function returns without performing any operation.

get() [1/2]

template<typename T>

std::optional< T > libcamera::ValueNode::get ( ) const

inline

Parse the ValueNode as a T value.

Template Parameters

T	Type of the value

This function parses the value of the ValueNode as a T object, and returns the value. If parsing fails (usually because the ValueNode doesn't store a T value), std::nullopt is returned.

If the type T is an std::vector, the ValueNode will be parsed as a list of values.

Returns

The ValueNode value, or std::nullopt if parsing failed

get() [2/2]

template<typename T, typename U>

T libcamera::ValueNode::get ( U && defaultValue ) const

inline

Parse the ValueNode as a T value.

Template Parameters

T	Type of the value
U	Type of the default value

Parameters

[in]

defaultValue

The default value when failing to parse

This function parses the value of the ValueNode as a T object, and returns the value. If parsing fails (usually because the ValueNode doesn't store a T value), the defaultValue is returned. Type U must be convertible to type T.

Unlike the get() function, this overload does not support std::vector for the type T.

Returns

The ValueNode value, or defaultValue if parsing failed

isDictionary()

bool libcamera::ValueNode::isDictionary ( ) const

inline

Return whether the ValueNode is a dictionary.

Returns

True if the ValueNode is a dictionary, false otherwise

isEmpty()

bool libcamera::ValueNode::isEmpty ( ) const

inline

Return whether the ValueNode is an empty.

Returns

True if the ValueNode is empty, false otherwise

isList()

bool libcamera::ValueNode::isList ( ) const

inline

Return whether the ValueNode is a list.

Returns

True if the ValueNode is a list, false otherwise

isValue()

bool libcamera::ValueNode::isValue ( ) const

inline

Return whether the ValueNode is a value.

Returns

True if the ValueNode is a value, false otherwise

operator bool()

libcamera::ValueNode::operator bool ( ) const

inlineexplicit

Return whether the ValueNode is a non-empty.

Returns

False if the ValueNode is empty, true otherwise

operator[]() [1/3]

const ValueNode & libcamera::ValueNode::operator[]

(

std::initializer_list< std::string_view >

path

)

const

Retrieve a descendant node by path.

Parameters

[in]

path

The path

This function retrieves a descendant of a ValueNode by following a path. The path is a list of keys that index nested dictionary nodes. If any node along the path is not a Dictionary node, an empty node is returned.

Returns

The ValueNode corresponding to the path

operator[]() [2/3]

const ValueNode & libcamera::ValueNode::operator[]

(

std::size_t

index

)

const

Retrieve the element from list ValueNode by index.

Parameters

[in]

index

The element index

This function retrieves an element of the ValueNode. Only ValueNode instances of List type associate elements with index, calling this function on other types of instances or with an invalid index results in an empty node.

Returns

The ValueNode as an element of the list

operator[]() [3/3]

const ValueNode & libcamera::ValueNode::operator[]

(

std::string_view

key

)

const

Retrieve a member by key from the dictionary.

Parameters

[in]

key

The element key

This function retrieves a member of a ValueNode by key. Only ValueNode instances of Dictionary type associate elements with keys, calling this function on other types of instances or with a nonexistent key results in an empty node.

Returns

The ValueNode corresponding to the key member

set()

template<typename T>

void libcamera::ValueNode::set ( T && value )

inline

Set the value of a ValueNode.

Template Parameters

T	Type of the value

Parameters

[in]

value

The value

This function sets the value stored in a ValueNode to value. The value is converted to a string in an implementation-specific way that guarantees that subsequent calls to get<T>() will return the same value.

Todo

Implement the conversion guarantee for floating point types

Values can only be set on ValueNode of Type::Value type or empty ValueNode. Attempting to set a value on a node of type Type::Dict or Type::List does not modify the ValueNode.

size()

std::size_t libcamera::ValueNode::size

(

)

const

Retrieve the number of elements in a dictionary or list ValueNode.

This function retrieves the size of the ValueNode, defined as the number of child elements it contains. Only ValueNode instances of Dictionary or List types have a size, calling this function on other types of instances is invalid and results in undefined behaviour.

Returns

The size of the ValueNode

---

The documentation for this class was generated from the following files:

• include/libcamera/internal/value_node.h
• src/libcamera/value_node.cpp