MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
CompositeForest.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "CompositeAccess.hpp"
4
6
7namespace MayaFlux::Kakshya {
8
9/**
10 * @brief Index the parent links of a Composite array.
11 * @param rows Array with a uint64_t parent field; a row without it present is a root.
12 * @param parent_field Name of the parent field.
13 * @param error Receives the reason when nullopt is returned.
14 * @param error_row Receives the failing row when given.
15 * @return The index, or nullopt when the field is missing or not uint64_t, or a
16 * parent does not precede its child.
17 */
18[[nodiscard]] MAYAFLUX_API std::optional<ForestIndex> index_composite_forest(
19 const CompositeArray& rows, std::string_view parent_field,
20 std::string& error, uint64_t* error_row = nullptr);
21
22/**
23 * @brief One-axis Region covering the subtree of row, inclusive.
24 *
25 * Any Region consumer then applies to a branch: CompositeContainer region
26 * copies and slices, and Yantra region inference.
27 *
28 * @return The Region, or nullopt when the rows are not preorder or row is out of range.
29 */
30[[nodiscard]] MAYAFLUX_API std::optional<Region> forest_subtree_region(
31 const ForestIndex& index, size_t row);
32
33/**
34 * @brief Copy the subtree of row into a self-contained array.
35 *
36 * Rows are copied in order and their parent links are rebased to the copy:
37 * the subtree root becomes a root and every other row points at its parent's
38 * new position. A copy made through a container Region keeps the original
39 * links instead, so it is not a forest on its own.
40 *
41 * @param rows Source array the index was built from.
42 * @param index Index of rows.
43 * @param parent_field Name of the uint64_t parent field.
44 * @param row Root of the subtree to copy.
45 * @param error Receives the reason when nullopt is returned.
46 * @return The copy, or nullopt when the rows are not preorder, row is out of
47 * range, or the field is missing or not uint64_t.
48 */
49[[nodiscard]] MAYAFLUX_API std::optional<CompositeArray> copy_forest_subtree(
50 const CompositeArray& rows, const ForestIndex& index,
51 std::string_view parent_field, size_t row, std::string& error);
52
53/**
54 * @class CompositeForest
55 * @brief A Composite array together with the index of its parent links.
56 *
57 * Owns both so a hierarchical document can be held, shared and walked without
58 * a separate reader or tree copy. Instances are immutable and shared, which
59 * keeps the array at a stable address for borrowed views.
60 *
61 * Usage:
62 * @code
63 * auto forest = CompositeForest::build(std::move(rows), "parent", error);
64 * auto traversal = forest->traversal();
65 * auto branch = forest->subtree_region(3);
66 * @endcode
67 */
68class MAYAFLUX_API CompositeForest {
69public:
70 /**
71 * @brief Index rows and take ownership of them.
72 * @param rows Array with a uint64_t parent field.
73 * @param parent_field Name of the parent field.
74 * @return The forest, or nullptr with the reason in error.
75 */
76 [[nodiscard]] static std::shared_ptr<const CompositeForest> build(
77 CompositeArray rows, std::string_view parent_field,
78 std::string& error, uint64_t* error_row = nullptr);
79
80 /** @brief The owned rows. */
81 [[nodiscard]] const CompositeArray& rows() const noexcept { return m_rows; }
82
83 /** @brief The index of the owned rows. */
84 [[nodiscard]] const ForestIndex& index() const noexcept { return m_index; }
85
86 /** @brief A traversal borrowing the owned rows and index. */
91
92 /** @brief Region covering the subtree of row, or nullopt as forest_subtree_region. */
93 [[nodiscard]] std::optional<Region> subtree_region(size_t row) const
94 {
95 return forest_subtree_region(m_index, row);
96 }
97
98 /** @brief Self-contained copy of the subtree of row, as copy_forest_subtree. */
99 [[nodiscard]] std::optional<CompositeArray> copy_subtree(
100 size_t row, std::string& error) const
101 {
102 return copy_forest_subtree(m_rows, m_index, m_parent_field, row, error);
103 }
104
105private:
107 : m_rows(std::move(rows))
108 , m_index(std::move(index))
109 , m_parent_field(std::move(parent_field))
110 {
111 }
112
115 std::string m_parent_field;
116};
117
118}
Owns a sequence of values that share a CompositeLayout.
std::optional< Region > subtree_region(size_t row) const
Region covering the subtree of row, or nullopt as forest_subtree_region.
CompositeForest(CompositeArray rows, ForestIndex index, std::string parent_field)
DataForestTraversal< CompositeArray > traversal() const noexcept
A traversal borrowing the owned rows and index.
const ForestIndex & index() const noexcept
The index of the owned rows.
std::optional< CompositeArray > copy_subtree(size_t row, std::string &error) const
Self-contained copy of the subtree of row, as copy_forest_subtree.
const CompositeArray & rows() const noexcept
The owned rows.
static std::shared_ptr< const CompositeForest > build(CompositeArray rows, std::string_view parent_field, std::string &error, uint64_t *error_row=nullptr)
Index rows and take ownership of them.
On-demand walks over the parent links of an indexed array.
Parent, child, depth and subtree structure over rows linked by parent index.
std::optional< ForestIndex > index_composite_forest(const CompositeArray &rows, std::string_view parent_field, std::string &error, uint64_t *error_row)
Index the parent links of a Composite array.
std::optional< Region > forest_subtree_region(const ForestIndex &index, size_t row)
One-axis Region covering the subtree of row, inclusive.
std::optional< CompositeArray > copy_forest_subtree(const CompositeArray &rows, const ForestIndex &index, std::string_view parent_field, size_t row, std::string &error)
Copy the subtree of row into a self-contained array.