From 8d78727d6e7badca16ba7a1328643928a0039569 Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Mon, 18 Nov 2024 18:02:09 +0100
Subject: move utilities from loek/audio

---
 src/crepe/util/CMakeLists.txt  |  2 ++
 src/crepe/util/OptionalRef.h   | 41 ++++++++++++++++++++++++++
 src/crepe/util/OptionalRef.hpp | 67 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 110 insertions(+)
 create mode 100644 src/crepe/util/OptionalRef.h
 create mode 100644 src/crepe/util/OptionalRef.hpp

(limited to 'src/crepe/util')

diff --git a/src/crepe/util/CMakeLists.txt b/src/crepe/util/CMakeLists.txt
index 4be738a..94ed906 100644
--- a/src/crepe/util/CMakeLists.txt
+++ b/src/crepe/util/CMakeLists.txt
@@ -9,5 +9,7 @@ target_sources(crepe PUBLIC FILE_SET HEADERS FILES
 	Log.hpp
 	Proxy.h
 	Proxy.hpp
+	OptionalRef.h
+	OptionalRef.hpp
 )
 
diff --git a/src/crepe/util/OptionalRef.h b/src/crepe/util/OptionalRef.h
new file mode 100644
index 0000000..1ad3a6d
--- /dev/null
+++ b/src/crepe/util/OptionalRef.h
@@ -0,0 +1,41 @@
+#pragma once
+
+namespace crepe {
+
+/**
+ * \brief Optional reference utility
+ *
+ * This class doesn't need to know the full definition of \c T to be used.
+ *
+ * \tparam T Value type
+ */
+template <typename T>
+class OptionalRef {
+public:
+	OptionalRef() = default;
+	OptionalRef(T &);
+  OptionalRef<T> & operator=(T &);
+	explicit operator bool() const noexcept;
+
+	void set(T &) noexcept;
+	T & get() const;
+	void clear() noexcept;
+
+  OptionalRef(const OptionalRef<T> &);
+  OptionalRef(OptionalRef<T> &&);
+  OptionalRef<T> & operator=(const OptionalRef<T> &);
+  OptionalRef<T> & operator=(OptionalRef<T> &&);
+
+private:
+	/**
+	 * \brief Reference to the value of type \c T
+	 *
+	 * \note This raw pointer is *not* managed, and only used as a reference!
+	 */
+	T * ref = nullptr;
+};
+
+}
+
+#include "OptionalRef.hpp"
+
diff --git a/src/crepe/util/OptionalRef.hpp b/src/crepe/util/OptionalRef.hpp
new file mode 100644
index 0000000..7b201b0
--- /dev/null
+++ b/src/crepe/util/OptionalRef.hpp
@@ -0,0 +1,67 @@
+#pragma once
+
+#include <stdexcept>
+
+#include "OptionalRef.h"
+
+namespace crepe {
+
+template <typename T>
+OptionalRef<T>::OptionalRef(T & ref) {
+	this->set(ref);
+}
+
+template <typename T>
+OptionalRef<T>::OptionalRef(const OptionalRef<T> & other) {
+	this->ref = other.ref;
+}
+
+template <typename T>
+OptionalRef<T>::OptionalRef(OptionalRef<T> && other) {
+	this->ref = other.ref;
+	other.clear();
+}
+
+template <typename T>
+OptionalRef<T> & OptionalRef<T>::operator=(const OptionalRef<T> & other) {
+	this->ref = other.ref;
+	return *this;
+}
+
+template <typename T>
+OptionalRef<T> & OptionalRef<T>::operator=(OptionalRef<T> && other) {
+	this->ref = other.ref;
+	other.clear();
+	return *this;
+}
+
+template <typename T>
+T & OptionalRef<T>::get() const {
+	if (this->ref == nullptr)
+		throw std::runtime_error("OptionalRef: attempt to dereference nullptr");
+	return *this->ref;
+}
+
+template <typename T>
+void OptionalRef<T>::set(T & ref) noexcept {
+	this->ref = &ref;
+}
+
+template <typename T>
+void OptionalRef<T>::clear() noexcept {
+	this->ref = nullptr;
+}
+
+template <typename T>
+OptionalRef<T> & OptionalRef<T>::operator=(T & ref) {
+	this->set(ref);
+	return *this;
+}
+
+template <typename T>
+OptionalRef<T>::operator bool() const noexcept {
+	return this->ref != nullptr;
+}
+
+}
+
-- 
cgit v1.2.3


From 9770b548c5619821d7b6ea7a017df2b5a6898d0a Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Mon, 18 Nov 2024 18:10:31 +0100
Subject: add doxygen comments

---
 src/crepe/api/Asset.h        | 10 +++++++++-
 src/crepe/util/OptionalRef.h | 37 +++++++++++++++++++++++++++++++++++--
 2 files changed, 44 insertions(+), 3 deletions(-)

(limited to 'src/crepe/util')

diff --git a/src/crepe/api/Asset.h b/src/crepe/api/Asset.h
index 05dccba..685dd3a 100644
--- a/src/crepe/api/Asset.h
+++ b/src/crepe/api/Asset.h
@@ -1,7 +1,6 @@
 #pragma once
 
 #include <string>
-#include <unordered_map>
 
 namespace crepe {
 
@@ -52,7 +51,16 @@ private:
 
 namespace std {
 
+//! Hash helper struct
 template<> struct hash<const crepe::Asset> {
+	/**
+	 * \brief Hash operator for crepe::Asset
+	 *
+	 * This function hashes a crepe::Asset instance, allowing it to be used as a key in an \c
+	 * std::unordered_map.
+	 *
+	 * \returns Hash value
+	 */
 	size_t operator()(const crepe::Asset & asset) const noexcept;
 };
 
diff --git a/src/crepe/util/OptionalRef.h b/src/crepe/util/OptionalRef.h
index 1ad3a6d..8417a25 100644
--- a/src/crepe/util/OptionalRef.h
+++ b/src/crepe/util/OptionalRef.h
@@ -12,18 +12,51 @@ namespace crepe {
 template <typename T>
 class OptionalRef {
 public:
+	//! Initialize empty (nonexistant) reference
 	OptionalRef() = default;
-	OptionalRef(T &);
-  OptionalRef<T> & operator=(T &);
+	//! Initialize reference with value
+	OptionalRef(T & ref);
+	/**
+	 * \brief Assign new reference
+	 *
+	 * \param ref Reference to assign
+	 *
+	 * \return Reference to this (required for operator)
+	 */
+  OptionalRef<T> & operator=(T & ref);
+	/**
+	 * \brief Check if this reference is not empty
+	 *
+	 * \returns `true` if reference is set, or `false` if it is not
+	 */
 	explicit operator bool() const noexcept;
 
+	/**
+	 * \brief Assign new reference
+	 *
+	 * \param ref Reference to assign
+	 */
 	void set(T &) noexcept;
+	/**
+	 * \brief Retrieve this reference
+	 *
+	 * \returns Internal reference if it is set
+	 *
+	 * \throws std::runtime_error if this function is called while the reference it not set
+	 */
 	T & get() const;
+	/**
+	 * \brief Make this reference empty
+	 */
 	void clear() noexcept;
 
+	//! Copy constructor
   OptionalRef(const OptionalRef<T> &);
+	//! Move constructor
   OptionalRef(OptionalRef<T> &&);
+	//! Copy assignment
   OptionalRef<T> & operator=(const OptionalRef<T> &);
+	//! Move assignment
   OptionalRef<T> & operator=(OptionalRef<T> &&);
 
 private:
-- 
cgit v1.2.3