From f20b55b0d5542cb358a8218dcb251c3a14084e00 Mon Sep 17 00:00:00 2001 From: Deukhoofd Date: Thu, 24 Sep 2020 20:40:21 +0200 Subject: [PATCH] Lots more documentation. --- src/Assert.hpp | 18 +++++++++-- src/Memory/BorrowedPtr.hpp | 3 ++ src/Memory/UniquePtrList.hpp | 52 +++++++++++++++++++++++++++++--- src/String/StringView.hpp | 32 +++++++++++++++++++- src/String/StringViewLiteral.hpp | 25 +++++++++++---- 5 files changed, 117 insertions(+), 13 deletions(-) diff --git a/src/Assert.hpp b/src/Assert.hpp index 7cf53b2..19bfe7d 100644 --- a/src/Assert.hpp +++ b/src/Assert.hpp @@ -1,3 +1,4 @@ +/** @file */ #include #include #include @@ -5,7 +6,13 @@ #define __FILENAME__ (strrchr(__FILE__, '/') ? strrchr(__FILE__, '/') + 1 : __FILE__) +/// \defgroup Asserts Asserts +/// \brief Group of non-editable strings with faster hashing. + + #ifndef NO_ASSERT +/// @brief Asserts an expression is true. Throws an exception if the assertion fails. +/// @ingroup Asserts #define Assert(expr) \ if (!(expr)) { \ std::stringstream ss; \ @@ -13,9 +20,12 @@ ss << #expr << "\""; \ throw ArbUt::Exception(ss.str()); \ } + +/// @brief Asserts an expression is true for a range. The value in the range can be retrieved using ``item``. +/// @ingroup Asserts #define AssertForEach(iterator, assertion) \ { \ - for (auto item : iterator) \ + for (auto item : (iterator)) \ Assert(assertion) \ } #else @@ -24,5 +34,9 @@ #define AssertForEach(iterator, assertion) ; #endif -#define AssertNotNull(value) Assert(value != nullptr) +/// @brief Asserts a pointer is not null. +/// @ingroup Asserts +#define AssertNotNull(value) Assert((value) != nullptr) +/// @brief Asserts a range is not null. +/// @ingroup Asserts #define AssertAllNotNull(iterator) AssertForEach(iterator, item != nullptr) diff --git a/src/Memory/BorrowedPtr.hpp b/src/Memory/BorrowedPtr.hpp index 202f121..9430e70 100644 --- a/src/Memory/BorrowedPtr.hpp +++ b/src/Memory/BorrowedPtr.hpp @@ -80,6 +80,9 @@ namespace ArbUt { namespace std { /// @brief Helper class for allowing hashing of BorrowedPtr. template struct hash> { + /// @brief Returns a hash of for a borrowed Pointer. Effectively just the raw memory address. + /// @param k A borrowed pointer. + /// @return The hash of the borrowed pointer. std::size_t operator()(const ArbUt::BorrowedPtr& k) const { return (size_t)k.GetRaw(); } }; } diff --git a/src/Memory/UniquePtrList.hpp b/src/Memory/UniquePtrList.hpp index 1f6e0c3..b6fd7d3 100644 --- a/src/Memory/UniquePtrList.hpp +++ b/src/Memory/UniquePtrList.hpp @@ -17,21 +17,34 @@ namespace ArbUt { public: inline UniquePtrList() noexcept : _vector() {} + /// @brief Initialises a UniquePtrList from a std::vector of raw pointers. + /// @param vec A std::vector of raw pointers. inline UniquePtrList(const std::vector& vec) noexcept : _vector(vec) {} + /// @brief Initialises a UniquePtrList with a certain capacity reserved for use. This does not set immediate size. + /// @param capacity The desired capacity. explicit inline UniquePtrList(size_t capacity) : _vector() { _vector.reserve(capacity); } + /// @brief Initialises a UniquePtrList from a initialiser_list. + /// @param l A initialiser_list inline UniquePtrList(const std::initializer_list& l) noexcept : _vector(l) {} + /// @brief Initialises a UniquePtrList from a raw pointer range. + /// @param begin The raw pointer to the start of the list. + /// @param end The raw pointer to the end of the list. inline UniquePtrList(ValueT* const* begin, ValueT* const* end) noexcept : _vector(begin, end) {} UniquePtrList(const UniquePtrList&) = delete; UniquePtrList& operator=(const UniquePtrList&) = delete; ~UniquePtrList() noexcept { Clear(); } + /// @brief Clears the UniquePtrList, and run the destructor on all containing pointers. inline void Clear() noexcept { for (auto& i : _vector) { delete i; } } + /// @brief Borrow a pointer at a certain index. + /// @param index The index to retrieve. + /// @return A borrowed pointer reference to the containing raw pointer. inline BorrowedPtr At(size_t index) const { #ifndef NO_ASSERT if (index >= _vector.size()) { @@ -42,21 +55,32 @@ namespace ArbUt { #endif return _vector[index]; } + /// @brief Returns a raw pointer at an index, and releases ownership. Proper handling of the memory is assumed to be done by the taker. + /// @param index The index to get the pointer from. + /// @return A raw pointer. ValueT* TakeOwnership(size_t index) { auto p = _vector[index]; _vector[index] = nullptr; return p; } + /// @brief Swaps two pointers at indices with each other. + /// @param indexA The first index to swap from. + /// @param indexB The second index to swap from void Swap(size_t indexA, size_t indexB) { auto temp = _vector[indexA]; _vector[indexA] = _vector[indexB]; _vector[indexB] = temp; } + /// @brief Sets a pointer to a certain index. If an item already existed at that index, it's destructor will be called. + /// @param index The index to set the pointer to. + /// @param ptr The pointer to store. void Set(size_t index, ValueT* ptr) { delete _vector[index]; _vector[index] = ptr; } + /// @brief Removes a pointer at a certain index. It's destructor will be called. + /// @param index The index to remove. inline void Remove(size_t index) { #ifndef NO_ASSERT if (index >= _vector.size()) { @@ -69,13 +93,16 @@ namespace ArbUt { _vector.erase(_vector.begin() + index); } + /// @brief Check whether a pointer is contained in the list. + /// @param value The value to check for. + /// @return True if the list contains the pointer, false otherwise. inline bool Contains(const BorrowedPtr& value) const noexcept { return std::find(_vector.begin(), _vector.end(), value) != _vector.end(); } - /// Find the index of the first occurrence of a value in the list, return -1 if none is found. - /// \param value The value we want the index for. - /// \return The index of the first occurrence of the value in the list, or -1 if none is found. + /// @brief Find the index of the first occurrence of a value in the list, return -1 if none is found. + /// @param value The value we want the index for. + /// @return The index of the first occurrence of the value in the list, or -1 if none is found. inline size_t IndexOf(const BorrowedPtr& value) const noexcept { const auto& it = std::find(_vector.begin(), _vector.end(), value); if (it == _vector.end()) @@ -83,19 +110,36 @@ namespace ArbUt { return std::distance(_vector.begin(), it); } + /// @brief Append a pointer to the list. + /// @param value The pointer to push to the list. inline void Append(ValueT* value) { _vector.push_back(value); } + /// @brief Borrow a pointer at a certain index. + /// @param index The index to retrieve. + /// @return A borrowed pointer reference to the containing raw pointer. inline BorrowedPtr operator[](size_t index) const { return At(index); } - inline size_t Count() const noexcept { return _vector.size(); } + /// @brief Returns the number of pointers contained. + /// @return The number of pointers contained. + [[nodiscard]] inline size_t Count() const noexcept { return _vector.size(); } + /// @brief returns an iterator to the beginning of the specified bucket iterator begin() noexcept { return _vector.begin(); } + /// @brief returns an iterator to the beginning of the specified bucket iterator end() noexcept { return _vector.end(); } + /// @brief returns an iterator to the end of the specified bucket const_iterator begin() const noexcept { return _vector.begin(); } + /// @brief returns an iterator to the end of the specified bucket const_iterator end() const noexcept { return _vector.end(); } + /// @brief Return a raw pointer to the beginning of the list. + /// @return A raw array pointer to the beginning of the list. ValueT* const* RawData() const noexcept { return _vector.data(); } + /// @brief Returns a std::vector representation of the current list. + /// @return A std::vector representation of the current list. const std::vector& GetStdList() const noexcept { return _vector; } + /// @brief Returns a std::vector representation of the current list. + /// @return A std::vector representation of the current list. std::vector& GetStdList() noexcept { return _vector; } }; } diff --git a/src/String/StringView.hpp b/src/String/StringView.hpp index 0327165..722d286 100644 --- a/src/String/StringView.hpp +++ b/src/String/StringView.hpp @@ -47,19 +47,33 @@ namespace ArbUt { std::shared_ptr<__ConstStringCharHolder> _str = GetEmptyString(); public: + /// @brief Instantiate a StringView using a C string. + /// @param str A null-terminated C string. StringView(const char* str) noexcept : BasicStringView(CalcLength(str), Hash(str)), _str(new __ConstStringCharHolder(str, CalcLength(str))) {} + /// @brief Instantiate a StringView using a C string, as well as it's length. + /// @param str A null-terminated C string. + /// @param length The length of the C string StringView(const char* str, size_t length) noexcept : BasicStringView(length, Hash(str)), _str(new __ConstStringCharHolder(str, length)) {} StringView() noexcept : BasicStringView(0, Hash("")) {} /* Copy operators */ + /// @brief Copy operator + /// @param other Other StringView StringView(const StringView& other) noexcept : BasicStringView(other._length, other._hash), _str(other._str) {} + /// @brief Special constructor of stringview, specifically designed for use of conversion from StringViewLiteral to StringView. + /// @param other Other StringView + /// @param c A null-terminated C string. + /// @param length The length of the C string. StringView(const BasicStringView& other, const char* c, size_t length) noexcept : BasicStringView(length, other.GetHash()), _str(new __ConstStringCharHolder(c, length)) {} + /// @brief Assignment operator. + /// @param other Stringview to assign. + /// @return current stringview. StringView& operator=(const StringView& other) noexcept { - if (_str == other._str) { + if (this == &other || _str == other._str) { return *this; } _str = other._str; @@ -68,7 +82,11 @@ namespace ArbUt { return *this; } + /// @brief Returns null-terminated C string. + /// @return Null-terminated C string. [[nodiscard]] inline const char* c_str() const noexcept override { return _str->GetValue(); } + /// @brief Returns std string_view of internal C string. + /// @return std::string_view. [[nodiscard]] inline std::string_view std_str() const noexcept override { return _str->GetValue(); } inline constexpr bool operator==(const std::string_view& rhs) const noexcept override { @@ -80,14 +98,23 @@ namespace ArbUt { inline constexpr bool operator==(const char* rhs) const noexcept override { return _hash == Hash(rhs); } inline constexpr bool operator!=(const char* rhs) const noexcept override { return _hash != Hash(rhs); } + /// @brief Calculates the hash for a given C string. + /// @param val A null-terminated C string. + /// @return A hash of the given string. [[maybe_unused]] [[nodiscard]] inline static constexpr uint32_t CalculateHash(const char* val) noexcept { return Hash(val); } + + /// @brief Calculates the hash for a given std string. + /// @param val A std string. + /// @return A hash of the given string. [[maybe_unused]] [[nodiscard]] inline static constexpr uint32_t CalculateHash(const std::string_view& val) noexcept { return Hash(val.data()); } + /// @brief Returns an empty string. + /// @return An empty string. static const StringView& EmptyString(); }; } @@ -95,6 +122,9 @@ namespace ArbUt { namespace std { /// @brief Helper class for hashing string views. template <> struct hash { + /// @brief Returns the hash of a stringview. + /// @param s a StringView. + /// @return The hash of the StringView. constexpr std::size_t operator()(ArbUt::StringView const& s) const noexcept { return s.GetHash(); } }; } diff --git a/src/String/StringViewLiteral.hpp b/src/String/StringViewLiteral.hpp index d7d4fd7..d2ae427 100644 --- a/src/String/StringViewLiteral.hpp +++ b/src/String/StringViewLiteral.hpp @@ -13,14 +13,24 @@ namespace ArbUt { const char* _str; public: - constexpr StringViewLiteral(const char* str, size_t size) noexcept + /// @brief Compile time initialisation of a StringViewLiteral. + /// @param str A null terminated C string. + /// @param size A The length of the string. + consteval StringViewLiteral(const char* str, size_t size) noexcept : BasicStringView(size, Hash(str)), _str(str) {} - constexpr StringViewLiteral(const char* str) noexcept : StringViewLiteral(str, CalcLength(str)){}; + /// @brief Compile time initialisation of a StringViewLiteral. Length is calculated at compile. + /// @param str A null terminated C string. + consteval StringViewLiteral(const char* str) noexcept : StringViewLiteral(str, CalcLength(str)){}; [[nodiscard]] inline constexpr const char* c_str() const noexcept override { return _str; } [[nodiscard]] constexpr std::string_view std_str() const noexcept override { return std::string_view(_str, _length); } - constexpr std::size_t operator()(StringViewLiteral const& s) const noexcept { return s.GetHash(); } + /// @brief Returns the hash of a s.tringview literal. + /// @param s A stringview literal. + /// @return The hash of the stringview literal. + consteval std::size_t operator()(StringViewLiteral const& s) const noexcept { return s.GetHash(); } + /// @brief Converts stringview literal into non-literal (for use during runtime). + /// @return A normal StringView. inline operator StringView() const noexcept { return StringView(*this, _str, _length); } inline constexpr bool operator==(const std::string_view& rhs) const noexcept override { @@ -37,14 +47,17 @@ namespace ArbUt { namespace std { /// @brief Helper class for getting the hash of a string view literal. template <> struct hash { - constexpr std::size_t operator()(ArbUt::StringViewLiteral const& s) const noexcept { return s.GetHash(); } + /// @brief Returns the hash of a stringview. + /// @param s a StringView. + /// @return The hash of the StringView. + consteval std::size_t operator()(ArbUt::StringViewLiteral const& s) const noexcept { return s.GetHash(); } }; } -inline constexpr ArbUt::StringViewLiteral operator"" _const_nocase(const char* c, size_t l) { +inline consteval ArbUt::StringViewLiteral operator"" _const_nocase(const char* c, size_t l) { return ArbUt::StringViewLiteral(c, l); } -inline constexpr ArbUt::StringViewLiteral operator"" _cnc(const char* c, size_t l) { +inline consteval ArbUt::StringViewLiteral operator"" _cnc(const char* c, size_t l) { return ArbUt::StringViewLiteral(c, l); }