From d206499057ceaf6927be4fbc3f54e25dacd83034 Mon Sep 17 00:00:00 2001
From: "Claudius \"keldu\" Holeksa" <mail@keldu.de>
Date: Thu, 9 Nov 2023 15:29:49 +0100
Subject: core: Renaming tree and branch

---
 c++/core/tree.h | 108 ++++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 78 insertions(+), 30 deletions(-)

(limited to 'c++/core')

diff --git a/c++/core/tree.h b/c++/core/tree.h
index 0ed7fe1..6316a5e 100644
--- a/c++/core/tree.h
+++ b/c++/core/tree.h
@@ -7,23 +7,42 @@
 
 namespace saw {
 /**
- * Container with a simplistic approach to a tree
+ * Container with a simplistic approach to a branch
  */
 template<typename T>
-class tree;
+class branch;
 
 /**
- * Branch object holding sub trees
+ * Tree object holding branches.
+ *
+ * The name comes from the fact a tree is acting as a node while the branch class is the
+ * edge to a leaf or other nodes. A tree holds the branches while the branch either has
+ * a leaf or another sub tree.
  */
 template<typename T>
-class branch final {
+class tree final {
 private:
-	std::vector<tree<T>> children_;
+	/**
+	 * Object holding the treeed branch instances
+	 */
+	std::vector<branch<T>> children_;
 public:
-	branch() = default;
-
-	~branch() = default;
-
+	/**
+	 * Default constructor
+	 */
+	tree() = default;
+
+	/**
+	 * Destructor
+	 */
+	~tree() = default;
+
+	SAW_FORBID_COPY(tree);
+	SAW_DEFAULT_MOVE(tree);
+
+	/**
+	 * Reserve space for siz elements
+	 */
 	error_or<void> reserve(std::size_t siz){
 		try{
 			children_.reserve(siz);
@@ -36,10 +55,16 @@ public:
 		return void_t{};
 	}
 
+	/**
+	 * Add a branch with a leaf attached to the tree
+	 */
 	error_or<std::size_t> add(T leaf) {
 		std::size_t index = size();
 		try {
-			children_.push_back(std::move(leaf));
+			/**
+			 * Technically we're adding a leaf on a branch
+			 */
+			children_.emplace_back(std::move(leaf));
 		}catch(const std::exception& e){
 			(void)e;
 
@@ -49,10 +74,14 @@ public:
 		return index;
 	}
 
+	/**
+	 * Add a branch to the tree with a tree attached
+	 */
 	error_or<std::size_t> add() {
 		std::size_t index = size();
 		try {
-			children_.push_back(branch{});
+
+			children_.emplace_back(tree{});
 		}catch(const std::exception& e){
 			(void)e;
 
@@ -62,40 +91,59 @@ public:
 		return index;
 	}
 
+	/**
+	 * Returns the amount of branches contained within this tree level
+	 */
 	std::size_t size() const {
 		return children_.size();
 	}
 
-	tree<T>& at(std::size_t i){
+	/**
+	 * Returns the branch at i
+	 */
+	branch<T>& at(std::size_t i){
 		return children_.at(i);
 	}
 
-	const tree<T>& at(std::size_t i) const {
+	/**
+	 * Returns the branch at i
+	 */
+	const branch<T>& at(std::size_t i) const {
 		return children_.at(i);
 	}
 };
 
 template<typename T>
-class tree final {
+class branch final {
 private:
-	using type = std::variant<branch<T>,T>;
+	using type = std::variant<tree<T>,T>;
 	type tov_;
 
-	friend class branch<T>;
+	/**
+	 * We're friend classing the tree since it's way easier this way and the branch and tree
+	 * class are intertwined heavily anyway.
+	 */
+	friend class tree<T>;
 public:
-	tree():tov_{branch<T>{}}{}
+	/**
+	 * 
+	 */
+	branch():tov_{tree<T>{}}{}
+
+	branch(tree<T> nd):tov_{std::move(nd)}{}
 
-	tree(branch<T> nd):tov_{std::move(nd)}{}
+	branch(T val):tov_{std::move(val)}{}
 
-	tree(T val):tov_{std::move(val)}{}
+	SAW_FORBID_COPY(branch);
+	SAW_DEFAULT_MOVE(branch);
 
 	template<typename NT>
 	bool is() const {
 		return std::holds_alternative<NT>(tov_);
 	}
 
-	bool is_branch() const {
-		return std::holds_alternative<branch>(tov_);
+	bool is_tree() const {
+		return std::holds_alternative<tree>(tov_);
 	}
 
 	bool is_value() const {
@@ -112,12 +160,12 @@ public:
 		return std::get<NT>(tov_);
 	}
 
-	branch<T>& get_branch(){
-		return std::get<branch<T>>(tov_);
+	tree<T>& get_tree(){
+		return std::get<tree<T>>(tov_);
 	}
 
-	const branch<T>& get_branch() const {
-		return std::get<branch<T>>(tov_);
+	const tree<T>& get_tree() const {
+		return std::get<tree<T>>(tov_);
 	}
 
 	T& get_value(){
@@ -135,7 +183,7 @@ public:
 		}
 		
 		NT nd = std::move(std::get<NT>(tov_));
-		tov_ = branch<T>{};
+		tov_ = tree<T>{};
 
 		return nd;
 	}
@@ -152,12 +200,12 @@ public:
 		return eon;
 	}
 
-	error_or<branch<T>> extract_branch() {
-		return extract<branch<T>>();
+	error_or<tree<T>> extract_tree() {
+		return extract<tree<T>>();
 	}
 
-	error_or<branch<T>> replace_branch(type nd){
-		return replace<branch<T>>(std::move(nd));
+	error_or<tree<T>> replace_tree(type nd){
+		return replace<tree<T>>(std::move(nd));
 	}
 
 	error_or<T> extract_value() {
-- 
cgit v1.2.3