libcamera: libcamera::ValueNode Class Reference

libcamera v0.7.1 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
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