refactor: move containers into separate directory

10 files changed, 922 insertions, 0 deletions

diff --git a/lib/nes/common/containers/CMakeLists.txt b/lib/nes/common/containers/CMakeLists.txt
new file mode 100644
index 0000000..351772f
--- /dev/null
+++ b/lib/nes/common/containers/CMakeLists.txt
@@ -0,0 +1,12 @@
+target_sources(
+	nes
+	PRIVATE
+		box.hh
+		list.hh
+		path-builder.hh
+		path-builder.cc
+		path-view.hh
+		path-view.cc
+		span.hh
+		string-builder.hh
+		string-builder.cc)
\ No newline at end of file
diff --git a/lib/nes/common/containers/box.hh b/lib/nes/common/containers/box.hh
new file mode 100644
index 0000000..7bf2848
--- /dev/null
+++ b/lib/nes/common/containers/box.hh
@@ -0,0 +1,78 @@
+#pragma once
+
+#include "nes/common/types.hh"
+#include "nes/common/debug.hh"
+
+namespace nes
+{
+	/// Wrapper around an object, allowing for it to be uninitialized or reassigned even if the object type doesn't
+	/// support it.
+	///
+	/// Basically a std::unique_ptr but stored in-place (and thus not movable).
+	template<typename T>
+	class box
+	{
+		bool initialized_{ false };
+		alignas(T) u8 buffer_[sizeof(T)];
+
+	public:
+		/// Create an empty box.
+		explicit box() = default;
+
+		~box()
+		{
+			clear();
+		}
+
+		box(box const&) = delete;
+		box(box&&) = delete;
+		auto operator=(box const&) -> box& = delete;
+		auto operator=(box&&) -> box& = delete;
+
+		auto operator*() -> T&
+		{
+			NES_ASSERT(has_value() && "expected box to be non-empty");
+			return *get();
+		}
+
+		auto operator*() const -> T const&
+		{
+			NES_ASSERT(has_value() && "expected box to be non-empty");
+			return *get();
+		}
+
+		auto operator->() -> T*
+		{
+			NES_ASSERT(has_value() && "expected box to be non-empty");
+			return get();
+		}
+
+		auto operator->() const -> T const*
+		{
+			NES_ASSERT(has_value() && "expected box to be non-empty");
+			return get();
+		}
+
+		operator bool() const { return has_value(); }
+
+		auto has_value() const -> bool { return initialized_; }
+		auto get() -> T* { return has_value() ? std::launder(reinterpret_cast<T*>(buffer_)) : nullptr; }
+		auto get() const -> T const* { return has_value() ? std::launder(reinterpret_cast<T const *>(buffer_)) : nullptr; }
+
+		/// Construct a new value in-place, potentially replacing the old value.
+		template<typename... Args>
+		auto emplace(Args&&... args) -> void
+		{
+			clear();
+			new (buffer_) T(std::forward<Args>(args)...);
+			initialized_ = true;
+		}
+
+		/// Clear the boxed value.
+		auto clear() -> void
+		{
+			if (initialized_) { (*this)->~T(); }
+			initialized_ = false;
+		}
+	};
+} // namespace nes
\ No newline at end of file
diff --git a/lib/nes/common/containers/list.hh b/lib/nes/common/containers/list.hh
new file mode 100644
index 0000000..46f7027
--- /dev/null
+++ b/lib/nes/common/containers/list.hh
@@ -0,0 +1,143 @@
+#pragma once
+
+#include "nes/common/debug.hh"
+
+namespace nes
+{
+	/// An intrusive doubly-linked list.
+	template<typename T>
+	class list
+	{
+	public:
+		/// Base class of nodes in the list.
+		class node
+		{
+			friend list;
+
+			list* list_{ nullptr };
+			T* prev_{ nullptr };
+			T* next_{ nullptr };
+
+		public:
+			virtual ~node() = default;
+
+			node(node const&) = delete;
+			node(node&&) = delete;
+			auto operator=(node const&) -> node& = delete;
+			auto operator=(node&&) -> node& = delete;
+
+		protected:
+			explicit node() = default;
+		};
+
+		/// An iterator for the linked list.
+		class iterator
+		{
+			friend list;
+
+			T* current_{ nullptr };
+
+		public:
+			auto operator==(iterator const& other) -> bool { return current_ == other.current_; }
+			auto operator!=(iterator const& other) -> bool { return current_ != other.current_; }
+
+			auto operator*() const -> T&
+			{
+				NES_ASSERT(current_ != nullptr && "invalid iterator");
+				return *current_;
+			}
+
+			auto operator->() const -> T*
+			{
+				NES_ASSERT(current_ != nullptr && "invalid iterator");
+				return current_;
+			}
+
+			auto operator++() -> iterator&
+			{
+				NES_ASSERT(current_ != nullptr && "invalid iterator");
+				node& current_node = *current_;
+				current_ = current_node.next_;
+				return *this;
+			}
+
+			auto operator++(int) -> iterator
+			{
+				auto res = *this;
+				++*this;
+				return res;
+			}
+
+		private:
+			explicit iterator() = default;
+			explicit iterator(T* current)
+				: current_{ current }
+			{
+			}
+		};
+
+	private:
+		T* head_{ nullptr };
+		T* tail_{ nullptr };
+
+	public:
+		explicit list() = default;
+
+		~list()
+		{
+			while (begin() != end()) { remove(begin()); }
+		}
+
+		list(list const&) = delete;
+		list(list&&) = delete;
+		auto operator=(list const&) -> list& = delete;
+		auto operator=(list&&) -> list& = delete;
+
+		auto begin() const -> iterator { return iterator{ head_ }; }
+		auto end() const -> iterator { return iterator{}; }
+
+		/// Add an item to the end of the list, removing it from any other list it may be in.
+		auto append(T& item) -> void
+		{
+			node& item_node = item;
+			if (item_node.list_) { item_node.list_->remove(item); }
+
+			item_node.list_ = this;
+			if (tail_)
+			{
+				item_node.prev_ = tail_;
+				tail_->next_ = &item;
+			}
+			else
+			{
+				head_ = &item;
+			}
+			tail_ = &item;
+		}
+
+		/// Remove an item from the list.
+		auto remove(T& item) -> bool
+		{
+			node& item_node = item;
+			if (!item_node.list_) { return false; }
+
+			if (head_ == &item) { head_ = item_node.next_; }
+			if (tail_ == &item) { tail_ = item_node.prev_; }
+			if (item_node.prev_) { item_node.prev_->next_ = item_node.next_; }
+			if (item_node.next_) { item_node.next_->prev_ = item_node.prev_; }
+
+			item_node.next_ = nullptr;
+			item_node.prev_ = nullptr;
+			item_node.list_ = nullptr;
+
+			return true;
+		}
+
+		/// Remove an item from the list by its iterator.
+		auto remove(iterator it) -> bool
+		{
+			if (it != end()) { return remove(*it); }
+			return false;
+		}
+	};
+} // namespace nes
\ No newline at end of file
diff --git a/lib/nes/common/containers/path-builder.cc b/lib/nes/common/containers/path-builder.cc
new file mode 100644
index 0000000..2e3ce07
--- /dev/null
+++ b/lib/nes/common/containers/path-builder.cc
@@ -0,0 +1,46 @@
+#include "nes/common/containers/path-builder.hh"
+
+namespace nes
+{
+	path_builder::path_builder(span<char> const buffer)
+		: buffer_{ buffer }
+	{
+		// Initialize the path to "/" if possible.
+		if (buffer_.get_length() > 0) { buffer_[length_++] = '/'; }
+	}
+
+	auto path_builder::push(std::string_view component) -> status
+	{
+		// Trim leading and trailing slashes
+		while (!component.empty() && component[0] == '/') { component = component.substr(1); }
+		while (!component.empty() && component[component.length() - 1] == '/') { component = component.substr(0, component.length() - 1); }
+		if (component.empty() || std::find(component.begin(), component.end(), '/') != component.end()) { return status::error_invalid_path; }
+
+		// Check if there is enough remaining capacity for "/<component>"
+		auto const add_leading_slash = length_ == 0 || buffer_[length_ - 1] != '/';
+		auto const length = component.length() + (add_leading_slash ? 1 : 0);
+		if (length_ + length > buffer_.get_length()) { return status::error_buffer_overflow; }
+
+		// Append "/<component>"
+		if (add_leading_slash) { buffer_[length_++] = '/'; }
+		for (auto i = u32{ 0 }; i < component.length(); ++i) { buffer_[length_++] = component[i]; }
+
+		return status::success;
+	}
+
+	auto path_builder::pop() -> status
+	{
+		if (length_ == 0 || buffer_[length_ - 1] == '/') { return status::error_invalid_path; }
+
+		// Find the start of the last component.
+		auto last_start = length_ - 1;
+		while (last_start > 0 && buffer_[last_start] != '/') { last_start -= 1; }
+
+		// Drop the slash if we are not at the root.
+		if (last_start == 0) { last_start += 1; }
+
+		// Drop everything including the trailing slash.
+		length_ = last_start;
+		return status::success;
+	}
+} // namespace nes
\ No newline at end of file
diff --git a/lib/nes/common/containers/path-builder.hh b/lib/nes/common/containers/path-builder.hh
new file mode 100644
index 0000000..2991a83
--- /dev/null
+++ b/lib/nes/common/containers/path-builder.hh
@@ -0,0 +1,55 @@
+#pragma once
+
+#include "nes/common/containers/span.hh"
+#include "nes/common/containers/path-view.hh"
+#include "nes/common/types.hh"
+#include "nes/common/status.hh"
+#include <string_view>
+
+namespace nes
+{
+	/// A mutable path with a fixed-length buffer.
+	class path_builder
+	{
+		template<u32 Capacity>
+		friend class path_buffer;
+
+		span<char> buffer_;
+		u32 length_{ 0 };
+
+	public:
+		explicit path_builder(span<char>);
+
+		auto get_components() const -> path_view { return path_view{ get_path() }; }
+		auto get_path() const -> std::string_view { return std::string_view{ buffer_.get_data(), length_ }; }
+
+		auto push(std::string_view) -> status;
+		auto pop() -> status;
+	};
+
+	/// A path builder with a buffer embedded into it.
+	template<u32 Capacity>
+	class path_buffer : public path_builder
+	{
+		char buffer_[Capacity];
+
+	public:
+		explicit path_buffer()
+			: path_builder{ buffer_ }
+		{
+		}
+
+		path_buffer(path_buffer const& other)
+			: path_builder{ buffer_ }
+		{
+			std::copy_n(other.buffer_, Capacity, buffer_);
+			length_ = other.length_;
+		}
+
+		auto operator=(path_buffer const& other)
+		{
+			std::copy_n(other.buffer_, Capacity, buffer_);
+			length_ = other.length_;
+		}
+	};
+} // namespace nes
\ No newline at end of file
diff --git a/lib/nes/common/containers/path-view.cc b/lib/nes/common/containers/path-view.cc
new file mode 100644
index 0000000..c81668b
--- /dev/null
+++ b/lib/nes/common/containers/path-view.cc
@@ -0,0 +1,51 @@
+#include "nes/common/containers/path-view.hh"
+#include "nes/common/debug.hh"
+
+namespace nes
+{
+	auto path_view::iterator::operator*() const -> std::string_view
+	{
+		NES_ASSERT(current_ != nullptr && component_length_ > 0 && "invalid iterator");
+		return std::string_view{ current_, component_length_ };
+	}
+
+	auto path_view::iterator::operator++() -> iterator&
+	{
+		// Move forward to next component
+		current_ += component_length_;
+		remaining_ -= component_length_;
+
+		// Skip over '/'.
+		while (remaining_ > 0 && *current_ == '/')
+		{
+			current_ += 1;
+			remaining_ -= 1;
+		}
+
+		// Scan until end of component to find its length.
+		component_length_ = 0;
+		while (component_length_ < remaining_ && current_[component_length_] != '/')
+		{
+			component_length_ += 1;
+		}
+
+		return *this;
+	}
+
+	auto path_view::iterator::operator++(int) -> iterator
+	{
+		auto const res = *this;
+		++*this;
+		return res;
+	}
+
+	auto path_view::begin() const -> iterator
+	{
+		return ++iterator{ path_.data(), 0, static_cast<u32>(path_.size()) };
+	}
+
+	auto path_view::end() const -> iterator
+	{
+		return iterator{ path_.data() + path_.size(), 0, 0 };
+	}
+} // namespace nes
\ No newline at end of file
diff --git a/lib/nes/common/containers/path-view.hh b/lib/nes/common/containers/path-view.hh
new file mode 100644
index 0000000..7741060
--- /dev/null
+++ b/lib/nes/common/containers/path-view.hh
@@ -0,0 +1,52 @@
+#pragma once
+
+#include "nes/common/types.hh"
+#include <string_view>
+
+namespace nes
+{
+	/// Non-owning copy of a path, useful for iterating over its components.
+	class path_view
+	{
+		std::string_view path_;
+
+	public:
+		/// An iterator for the path components.
+		class iterator
+		{
+			friend path_view;
+
+			char const* current_{ nullptr }; // Start of the current component
+			u32 component_length_{ 0 }; // Length of the current component
+			u32 remaining_{ 0 }; // Number of characters remaining in the buffer, including the current component.
+
+		public:
+			auto operator==(iterator const& other) -> bool { return current_ == other.current_; }
+			auto operator!=(iterator const& other) -> bool { return current_ != other.current_; }
+
+			auto operator*() const -> std::string_view;
+			auto operator++() -> iterator&;
+			auto operator++(int) -> iterator;
+
+		private:
+			explicit iterator(char const* current, u32 const component_length, u32 const remaining)
+				: current_{ current }
+				, component_length_{ component_length }
+				, remaining_{ remaining }
+			{
+			}
+		};
+
+		explicit path_view() = default;
+		explicit path_view(std::string_view const path)
+			: path_{ path }
+		{
+		}
+
+		auto get_path() const -> std::string_view { return path_; }
+
+		auto begin() const -> iterator;
+		auto end() const -> iterator;
+		auto is_empty() const -> bool { return begin() == end(); }
+	};
+} // namespace nes::app
\ No newline at end of file
diff --git a/lib/nes/common/containers/span.hh b/lib/nes/common/containers/span.hh
new file mode 100644
index 0000000..6779c37
--- /dev/null
+++ b/lib/nes/common/containers/span.hh
@@ -0,0 +1,105 @@
+#pragma once
+
+#include "nes/common/types.hh"
+#include "nes/common/debug.hh"
+
+namespace nes
+{
+	namespace detail
+	{
+		struct span_unchecked{};
+
+		inline constexpr auto span_dynamic_length = u32{ 0xFFFF };
+
+		template<typename T>
+		struct remove_const
+		{
+			using type = T;
+		};
+
+		template<typename T>
+		struct remove_const<T const>
+		{
+			using type = T;
+		};
+
+		template<typename T>
+		using remove_const_type = typename remove_const<T>::type;
+	} // namespace detail
+
+	/// Implementation of a container similar to std::span in C++20.
+	template<typename T, u32 Length = detail::span_dynamic_length>
+	class span
+	{
+		template<typename U, u32 OtherLength>
+		friend class span;
+
+		T* data_{ nullptr };
+		u32 length_{ 0 };
+
+	public:
+		using iterator = T*;
+
+		explicit span()
+		{
+			static_assert(Length == 0 || Length == detail::span_dynamic_length);
+		}
+
+		explicit span(T* data, u32 const length)
+			: span{ data, length, {} }
+		{
+			static_assert(Length == detail::span_dynamic_length);
+		}
+
+		template<u32 ActualLength>
+		span(T (&data)[ActualLength])
+			: span{ data, ActualLength, {} }
+		{
+			static_assert(Length == ActualLength || Length == detail::span_dynamic_length);
+		}
+
+		span(span<detail::remove_const_type<T>, Length> const other)
+			: span{ other.data_, other.length_, {} }
+		{
+		}
+
+		auto get_data() const -> T* { return data_; }
+		auto get_length() const -> u32 { return length_; }
+
+		auto begin() const -> iterator { return data_; }
+		auto end() const -> iterator { return data_ + length_; }
+
+		auto subspan(u32 const first, u32 const length) const -> span<T>
+		{
+			NES_ASSERT(first + length <= get_length() && "subspan out of bounds");
+			return span{ data_ + first, length };
+		}
+
+		auto subspan(u32 const first) const -> span<T>
+		{
+			NES_ASSERT(first <= get_length() && "subspan out of bounds");
+			return subspan(length_ - first);
+		}
+
+		template<u32 OtherLength>
+		auto subspan(u32 const first) const -> span<T, OtherLength>
+		{
+			static_assert(OtherLength < Length);
+			NES_ASSERT(first + OtherLength <= get_length() && "subspan out of bounds");
+			return span<T, OtherLength>{ data_ + first, OtherLength, {} };
+		}
+
+		auto operator[](u32 const index) const -> T&
+		{
+			NES_ASSERT(index < get_length() && "index out of bounds");
+			return data_[index];
+		}
+
+	private:
+		explicit span(T* data, u32 const length, detail::span_unchecked)
+			: data_{ data }
+			, length_{ length }
+		{
+		}
+	};
+} // namespace nes
\ No newline at end of file
diff --git a/lib/nes/common/containers/string-builder.cc b/lib/nes/common/containers/string-builder.cc
new file mode 100644
index 0000000..74d9548
--- /dev/null
+++ b/lib/nes/common/containers/string-builder.cc
@@ -0,0 +1,256 @@
+#include "nes/common/containers/string-builder.hh"
+
+namespace nes
+{
+	string_builder::string_builder(span<char> const buffer)
+		: buffer_{ buffer }
+	{
+	}
+
+	auto string_builder::append_char(char const value) -> status
+	{
+		if (length_ == buffer_.get_length()) { return status::error_buffer_overflow; }
+
+		buffer_[length_] = value;
+		length_ += 1;
+		return status::success;
+	}
+
+	auto string_builder::append_string(std::string_view const value) -> status
+	{
+		auto copy = *this;
+		for (auto const c : value)
+		{
+			if (auto const s = copy.append_char(c); s != status::success) { return s; }
+		}
+
+		*this = copy;
+		return status::success;
+	}
+
+	auto string_builder::append_int(i64 value, number_format const format) -> status
+	{
+		auto copy = *this;
+		if (value < 0)
+		{
+			if (auto const s = copy.append_char('-'); s != status::success) { return s; }
+			value += 1; // to prevent lossy conversion to unsigned
+			auto abs_value = static_cast<u64>(-value);
+			abs_value += 1; // to correct the previous offset
+			if (auto const s = copy.append_int(abs_value, format); s != status::success) { return s; }
+		}
+		else
+		{
+			if (auto const s = copy.append_int(static_cast<u64>(value), format); s != status::success) { return s; }
+		}
+
+		*this = copy;
+		return status::success;
+	}
+
+	auto string_builder::append_int(u64 value, number_format const format) -> status
+	{
+		constexpr auto max_string_length = u32{ 64 }; // worst case is a 64-bit integer in binary representation
+		constexpr auto digits = "0123456789abcdef";
+
+		auto copy = *this;
+		auto base = u64{ 10 };
+		auto prefix = "";
+		switch (format)
+		{
+			case number_format::binary:
+				prefix = "0b";
+				base = 2;
+				break;
+			case number_format::octal:
+				prefix = "0";
+				base = 8;
+				break;
+			case number_format::decimal:
+				break;
+			case number_format::hexadecimal:
+				prefix = "0x";
+				base = 16;
+				break;
+		}
+		if (auto const s = copy.append_string(prefix); s != status::success) { return s; }
+
+		char buf[max_string_length + 1] = {}; // null-terminated
+		auto pos = max_string_length;
+		// Go through each digit in reverse order by continuously dividing the integer by the base.
+		while (value)
+		{
+			pos--;
+
+			buf[pos] = digits[value % base]; // Convert digit to char representation
+			value /= base;
+		}
+		if (pos == max_string_length)
+		{
+			// Special case 0 would not print any character otherwise.
+			pos--;
+			buf[pos] = '0';
+		}
+
+		if (const auto s = copy.append_string(&buf[pos]); s != status::success) { return s; }
+
+		*this = copy;
+		return status::success;
+	}
+
+	auto string_builder::append_bool(bool const value) -> status
+	{
+		return append_string(value ? "true" : "false");
+	}
+
+	auto string_builder::append_format(std::string_view const fmt, format_arg const* args, u32 const arg_count) -> status
+	{
+		auto copy = *this;
+
+		// Go through the format string, inserting the arguments for the templates as necessary.
+		auto current_arg = u32{ 0 };
+		for (auto i = u32{ 0 }; i < fmt.length(); ++i)
+		{
+			if (fmt[i] == '{')
+			{
+				i += 1;
+
+				if (fmt[i] == '{') {
+					// escaped '{'
+					if (auto const s = copy.append_char('{'); s != status::success) { return s; }
+				}
+				else
+				{
+					// start of template
+					auto const params = &fmt[i]; // remember start position
+					auto params_length = u32{ 0 };
+					// skip to the end of the template
+					while (fmt[i] && fmt[i] != '}')
+					{
+						params_length++;
+						i++;
+					}
+					if (fmt[i] != '}')
+					{
+						// unmatched '{'
+						return status::error_invalid_format_string;
+					}
+
+					// end of template
+					auto const p = std::string_view{ params, params_length };
+					if (current_arg < arg_count)
+					{
+						if (auto const s = copy.append_format_arg(args[current_arg], p); s != status::success) { return s; }
+						current_arg += 1;
+					}
+					else
+					{
+						// missing argument in parameter pack
+						return status::error_invalid_format_string;
+					}
+				}
+			}
+			else if (fmt[i] == '}')
+			{
+				i += 1;
+
+				if (fmt[i] == '}')
+				{
+					// escaped '}'
+					if (auto const s = copy.append_char('}'); s != status::success) { return s; }
+				}
+				else
+				{
+					// unmatched '}'
+					return status::error_invalid_format_string;
+				}
+			}
+			else
+			{
+				// normal character in the template string
+				if (auto const s = copy.append_char(fmt[i]); s != status::success) { return s; }
+			}
+		}
+
+		if (current_arg < arg_count)
+		{
+			// not all supplied arguments were used
+			return status::error_invalid_format_string;
+		}
+
+		*this = copy;
+		return status::success;
+	}
+
+	auto string_builder::append_format_arg(format_arg const arg, std::string_view const params) -> status
+	{
+		auto const parse_params = [&]
+		{
+			if (!params.empty())
+			{
+				return status::error_invalid_format_string;
+			}
+
+			return status::success;
+		};
+
+		auto const parse_params_integer = [&](number_format& out_format)
+		{
+			if (params.empty() || params == "d")
+			{
+				out_format = number_format::decimal;
+			}
+			else if (params == "x")
+			{
+				out_format = number_format::hexadecimal;
+			}
+			else if (params == "o")
+			{
+				out_format = number_format::octal;
+			}
+			else if (params == "b")
+			{
+				out_format = number_format::binary;
+			}
+			else
+			{
+				return status::error_invalid_format_string;
+			}
+
+			return status::success;
+		};
+
+		switch (arg.type)
+		{
+			case format_arg_type::string:
+			{
+				if (auto const s = parse_params(); s != status::success) { return s; }
+				return append_string(arg.string);
+			}
+			case format_arg_type::character:
+			{
+				if (auto const s = parse_params(); s != status::success) { return s; }
+				return append_char(arg.character);
+			}
+			case format_arg_type::signed_integer:
+			{
+				auto format = number_format{};
+				if (auto const s = parse_params_integer(format); s != status::success) { return s; }
+				return append_int(arg.signed_integer, format);
+			}
+			case format_arg_type::unsigned_integer:
+			{
+				auto format = number_format{};
+				if (auto const s = parse_params_integer(format); s != status::success) { return s; }
+				return append_int(arg.unsigned_integer, format);
+			}
+			case format_arg_type::boolean:
+			{
+				if (auto const s = parse_params(); s != status::success) { return s; }
+				return append_bool(arg.character);
+			}
+		}
+
+		return status::error_invalid_format_string;
+	}
+} // namespace nes
\ No newline at end of file
diff --git a/lib/nes/common/containers/string-builder.hh b/lib/nes/common/containers/string-builder.hh
new file mode 100644
index 0000000..0f8a64c
--- /dev/null
+++ b/lib/nes/common/containers/string-builder.hh
@@ -0,0 +1,124 @@
+#pragma once
+
+#include "nes/common/types.hh"
+#include "nes/common/containers/span.hh"
+#include "nes/common/status.hh"
+#include <string_view>
+
+namespace nes
+{
+	enum class number_format
+	{
+		decimal,
+		hexadecimal,
+		octal,
+		binary,
+	};
+
+	/// Builds a string into a fixed-length buffer.
+	class string_builder
+	{
+		template<u32 Capacity>
+		friend class string_buffer;
+
+		span<char> buffer_;
+		u32 length_{ 0 };
+
+		enum class format_arg_type
+		{
+			string,
+			character,
+			signed_integer,
+			unsigned_integer,
+			boolean,
+		};
+
+		struct format_arg
+		{
+			format_arg_type type;
+			union
+			{
+				std::string_view string;
+				char character;
+				i64 signed_integer;
+				u64 unsigned_integer;
+				bool boolean;
+			};
+
+			format_arg() = delete;
+
+			explicit format_arg(char const* v) : type{ format_arg_type::string } { string = v; }
+			explicit format_arg(std::string_view const v) : type{ format_arg_type::string } { string = v; }
+			explicit format_arg(char const v) : type{ format_arg_type::character } { character = v; }
+			explicit format_arg(unsigned char const v) : format_arg{ static_cast<char>(v) } {}
+			explicit format_arg(long long const v) : type{ format_arg_type::signed_integer } { signed_integer = v; }
+			explicit format_arg(unsigned long long const v) : type{ format_arg_type::unsigned_integer } { unsigned_integer = v; }
+			explicit format_arg(short const v) : format_arg{ static_cast<signed long long>(v) } {}
+			explicit format_arg(unsigned short const v) : format_arg{ static_cast<unsigned long long>(v) } {}
+			explicit format_arg(int const v) : format_arg{ static_cast<signed long long>(v) } {}
+			explicit format_arg(unsigned int const v) : format_arg{ static_cast<unsigned long long>(v) } {}
+			explicit format_arg(long const v) : format_arg{ static_cast<signed long long>(v) } {}
+			explicit format_arg(unsigned long const v) : format_arg{ static_cast<unsigned long long>(v) } {}
+			explicit format_arg(bool const v) : type{ format_arg_type::boolean } { boolean = v; }
+		};
+
+	public:
+		explicit string_builder(span<char>);
+
+		/// Get the resulting string.
+		auto get_result() const -> std::string_view { return std::string_view{ buffer_.get_data(), length_ }; }
+
+		auto append_char(char) -> status;
+		auto append_string(std::string_view) -> status;
+		auto append_int(i64, number_format = number_format::decimal) -> status;
+		auto append_int(u64, number_format = number_format::decimal) -> status;
+		auto append_bool(bool) -> status;
+
+		/// Print a templated string.
+		///
+		/// Placeholders are signified by `{<params>}` where `params` contains optional formatting parameters:
+		///  - for integers either "d" (the default), "x", "o", or "b"
+		///  - for any other type, no parameters are supported.
+		///
+		/// Curly braces can be escaped by repeating them twice like {{this}}.
+		template<typename... Args>
+		auto append_format(std::string_view const fmt, Args... args) -> status
+		{
+			constexpr u32 arg_count = sizeof...(Args);
+			// Add another argument at the end so we don't have an empty array expression.
+			const format_arg arg_wrappers[arg_count + 1] = { format_arg{ args }..., format_arg(0) };
+
+			return append_format(fmt, arg_wrappers, arg_count);
+		}
+
+	private:
+		auto append_format(std::string_view fmt, format_arg const* args, u32 arg_count) -> status;
+		auto append_format_arg(format_arg, std::string_view params) -> status;
+	};
+
+	/// A string builder with a buffer embedded into it.
+	template<u32 Capacity>
+	class string_buffer : public string_builder
+	{
+		char buffer_[Capacity];
+
+	public:
+		explicit string_buffer()
+			: string_builder{ buffer_ }
+		{
+		}
+
+		string_buffer(string_buffer const& other)
+			: string_builder{ buffer_ }
+		{
+			std::copy_n(other.buffer_, Capacity, buffer_);
+			length_ = other.length_;
+		}
+
+		auto operator=(string_buffer const& other)
+		{
+			std::copy_n(other.buffer_, Capacity, buffer_);
+			length_ = other.length_;
+		}
+	};
+} // namespace nes
\ No newline at end of file