From 35d508b1b934d36f3020748bb5cbefd58513a2b0 Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Mon, 19 Aug 2024 10:43:30 +0800 Subject: [PATCH] doc: finish XTypes documentation --- LibCmo/XContainer/XTypes.cpp | 6 +- LibCmo/XContainer/XTypes.hpp | 199 +++++++++++++++++++++-------------- 2 files changed, 123 insertions(+), 82 deletions(-) diff --git a/LibCmo/XContainer/XTypes.cpp b/LibCmo/XContainer/XTypes.cpp index 37ba8aa..3ffb658 100644 --- a/LibCmo/XContainer/XTypes.cpp +++ b/LibCmo/XContainer/XTypes.cpp @@ -41,7 +41,7 @@ namespace LibCmo::XContainer { } template - bool GeneralGetBitPosition(const XBitArray& ba, CKDWORD n, CKDWORD& got) { + static bool GeneralGetBitPosition(const XBitArray& ba, CKDWORD n, CKDWORD& got) { CKDWORD counter = 0; for (size_t i = 0; i < ba.size(); ++i) { if (ba[i] == _Cond) { @@ -82,11 +82,11 @@ namespace LibCmo::XContainer { } template - constexpr bool GeneralXArrayCheck_TypeCheck() { + static constexpr bool GeneralXArrayCheck_TypeCheck() { return std::is_same_v<_Ty, CK2::CK_ID> || std::is_same_v<_Ty, CK2::ObjImpls::CKObject*>; } template - bool GeneralXArrayCheck_ItemCheck(const _Ty& item, CK2::CKContext* ctx) { + static bool GeneralXArrayCheck_ItemCheck(const _Ty& item, CK2::CKContext* ctx) { static_assert(GeneralXArrayCheck_TypeCheck<_Ty>()); if (ctx == nullptr) return false; diff --git a/LibCmo/XContainer/XTypes.hpp b/LibCmo/XContainer/XTypes.hpp index f926f36..7bb383f 100644 --- a/LibCmo/XContainer/XTypes.hpp +++ b/LibCmo/XContainer/XTypes.hpp @@ -13,206 +13,247 @@ namespace LibCmo::XContainer { /** - @brief Class representation of a string (an array of character ended by NULL). - @remark This class now use std::string. + * @brief The representation of an UTF8 string (an array of UTF8 character ended by a '\0'). + * @remarks + * \li This class now is implemented by \c std::u8string. */ using XString = std::u8string; /** - @brief Set of bit flags. - @remark - + This class now use specialized std::vector. + * @brief The representation of a set of bit flags (memory optimized to reduce occupied size). + * @remarks + * \li This class is implemented by specialized \c std::vector. + * \li This class define a set of bit flags that may be treated as a virtual array but are stored in an efficient manner. + * \li The class has methods to set, clear and return the i-th bit, resize the array, etc. */ using XBitArray = std::vector; /** - @brief Class representation of an array. - @tparam T Element Type. - @remark - + This class now use std::vector. - + XSArray, XClassArray now redirect to this. + * @brief The representation of an array. + * @tparam T Element type. + * @remarks + * \li This class now use \c std::vector. + * \li XSArray now redirect to this. Because XSArray behaves exactly like the XArray, + * but it only occupies less memory. This feature also can be done by executing \c std::vector::shrink_to_fit(). + * \li XClassArray now redirect to this. Because it is designed to hold structure or class + * which have something specific to do on the construction, deletion or recopy. + * However this feature can be resolved by writing proper ctor, copy ctor, move ctor and dtor. */ template using XArray = std::vector; /** - * @brief Double-linked list. - * @tparam T Element Type. + * @brief The representation of an double-linked list. + * @tparam T Element type. */ template using XList = std::list; /** - @brief Container class for CKObject Id's. - @remark - + This class use the template container XArray to contain object CK_ID's. - + Supports for Check, Load, Save, Add, Remove, Find functions in the Object CK_ID array. - + XSObjectArray now redirect to this. - @todo May independ this class to implement the functions introduced in remarks. + * @brief The representation of an CKObject ID array. + * @remarks + * \li This class is implemented as \c XArray + * \li Supports for Check, Load, Save, Add, Remove, Find functions in the Object CK_ID array. + * \li XSObjectArray now redirect to this. See the relation between XArray and XSArray for more reason. + * \li CKObjectArray now redirect to this according to its requirements (use pointer or use ID). + * @see XObjectPointerArray + * @todo Add implementations of functions introduced in remarks to the patch namespace. */ using XObjectArray = XArray; /** - @brief Container class for CKObject pointers. - @remark - + Exactly same as XObjectArray class, but uses XArray (Pre-allocated items) - for storing pointers, and not IDs (more efficient to retrieve the objects). - + Supports for Check, Load, Save, Add, Remove, Find functions in the CKObject Pointer array. - + XSObjectPointerArray now redirect to this. - @todo May independ this class to implement the functions introduced in remarks. - @see XObjectArray, CKObjectArray + * @brief The representation of an CKObject pointer array. + * @remarks + * \li This class is implemented as \c XArray + * \li Exactly same as XObjectArray class, but stores pointers, not IDs (more efficient to retrieve the objects). + * \li Supports for Check, Load, Save, Add, Remove, Find functions in the CKObject pointer array. + * \li XSObjectPointerArray now redirect to this. See the relation between XArray and XSArray for more reason. + * \li CKObjectArray now redirect to this according to its requirements (use pointer or use ID). + * @see XObjectArray + * @todo Add implementations of functions introduced in remarks to the patch namespace. */ using XObjectPointerArray = XArray; /** - @brief Class representation of an Hash Table container. - @tparam K The type of the key - @tparam T The type of element to insert - @tparam H The hash function to hash the key - @tparam Eq The equal function to the key - @remark - + This class now use std::unordered_map. - + XNHashTable, XSHashTable now redirect to this. + * @brief The representation of an hash table container. + * @tparam K The type of the key + * @tparam T The type of element to insert + * @tparam H The hash function to hash the key + * @tparam Eq The equal function to the key + * @remarks + * \li This class now is implemented by \c std::unordered_map. + * \li XNHashTable now redirect to this. Because it seems like the old version of XHashTable. + * \li XSHashTable now redirect to this. See the relation between XArray and XSArray for more reason. */ template, class Eq = std::equal_to> using XHashTable = std::unordered_map; // ========== Patch Section ========== + /** + * @brief The patch namespace for XBitArray + * @details This namespace provides XBitArray functions which presented in original Virtools SDK, + * because XBitArray use standard library container as its implementation. + */ namespace NSXBitArray { /** * @brief Resize XBitArray to the new size. Initial value is false. - * @param ba The XBitArray - * @param newsize New Size + * @param[in] ba The XBitArray to be resized. + * @param[in] newsize New size (the count of bit flags, \b not the space in byte). */ void Resize(XBitArray& ba, CKDWORD newsize); /** - * @brief Merge other XBitArray to this XBitArray with OR condition. + * @brief Merge 2 XBitArray like performing thisba | thatba for each flags. + * @details * This XBitArray will be resized at least equal with merged XBitArray if its size is lower than merged XBitArray - * @param thisba This XBitArray - * @param thatba Other XBitArray will be merged. + * @param[in] thisba The merging XBitArray. + * If this XBitArray will be resized at least equal with merged XBitArray before merging. + * @param[in] thatba Other XBitArray will be merged. */ void Or(XBitArray& thisba, const XBitArray& thatba); /** * @brief Check whether bit flag is set. - * @param ba The XBitArray - * @param n The check position. + * @param[in] ba The XBitArray for checking + * @param[in] n The position for checking. * @return True if set. False if not set or out of range. */ bool IsSet(const XBitArray& ba, CKDWORD n); /** * @brief Set specified position to true in XBitArray. Auto resize if no space to set. - * @param ba The XBitArray - * @param n The set position. + * @param[in] ba The XBitArray for setting. + * @param[in] n The position for setting. */ void Set(XBitArray& ba, CKDWORD n); /** - * @brief Unset specified position to true in XBitArray. If out of range, simply return. - * @param ba The XBitArray - * @param n The unset position. + * @brief Unset specified position to true in XBitArray. Do nothing if out of range. + * @param[in] ba The XBitArray for unsetting. + * @param[in] n The position for unsetting. */ void Unset(XBitArray& ba, CKDWORD n); /** - * @brief Returns the position of the n-th set(1) bit - * @return false if not found. + * @brief Find the n-th bit which is set(1) bit from the lowest position. + * @param[in] ba The The XBitArray for finding. + * @param[in] n N-th + * @param[out] got The position we found. + * @return True if we found, otherwise false. */ bool GetSetBitPosition(const XBitArray& ba, CKDWORD n, CKDWORD& got); /** - * @brief Returns the position of the n-th unset(0) bit - * @return false if not found. + * @brief Find the n-th bit which is unset(0) bit from the lowest position. + * @param[in] ba The The XBitArray for finding. + * @param[in] n N-th + * @param[out] got The position we found. + * @return True if we found, otherwise false. */ bool GetUnsetBitPosition(const XBitArray& ba, CKDWORD n, CKDWORD& got); } - + + /** + * @brief The patch namespace for XString + * @details This namespace provides XString functions which presented in original Virtools SDK, + * because XString use standard library container as its implementation. + */ namespace NSXString { /** - * @brief Return CKSTRING statement of XString. - * @param strl The XString need to be output. - * @return Return the CKSTRING format of XString. if XString is blank, return nullptr. + * @brief Return CKSTRING representation of XString. + * @param[in] strl The XString need to be output. + * @return Return the CKSTRING representation of XString. + * If XString is blank, return nullptr instead. */ CKSTRING ToCKSTRING(const XString& strl); /** - * @brief Copy CKSTRING to XString. - * @param strl The string dest. - * @param s The CKSTRING need to be copied. Pass nullptr will clear string dest. + * @brief Copy CKSTRING representation to XString. + * @param[in] strl The string dest. + * @param[in] s The CKSTRING need to be copied. nullptr will clear string dest. */ void FromCKSTRING(XString& strl, CKSTRING s); } - + + /** + * @brief The patch namespace for XObjectArray + * @details This namespace provides XObjectArray functions which presented in original Virtools SDK, + * because XObjectArray use standard library container as its implementation. + */ namespace NSXObjectArray { /** * @brief Check Object ID validation and remove invalid IDs before deletion. - * @param objarray - * @param ctx + * @param[in] objarray The array to be checked. + * @param[in] ctx Associated CKContext. */ void PreDeletedCheck(XObjectArray& objarray, CK2::CKContext* ctx); /** * @brief Check Object ID validation and remove invalid IDs after deletion. - * @param objarray - * @param ctx + * @param[in] objarray The array to be checked. + * @param[in] ctx Associated CKContext. + * @warning The performance of this function is extremely bad. Use this carefully. */ void PostDeletedCheck(XObjectArray& objarray, CK2::CKContext* ctx); /** * @brief Check Object pointer validation and remove invalid pointers before deletion. - * @param objarray - * @param ctx + * @param[in] objarray The array to be checked. + * @param[in] ctx Associated CKContext. */ void PreDeletedCheck(XList& objarray, CK2::CKContext* ctx); /** * @brief Check Object pointer validation and remove invalid pointers after deletion. - * @param objarray - * @param ctx - * @remark The performance of this function is extremely low. Use it carefully. + * @param[in] objarray The array to be checked. + * @param[in] ctx Associated CKContext. + * @warning The performance of this function is extremely bad. Use this carefully. */ void PostDeletedCheck(XList& objarray, CK2::CKContext* ctx); } + /** + * @brief The patch namespace for XObjectPointer + * @details This namespace provides XObjectPointer functions which presented in original Virtools SDK, + * because XObjectPointer use standard library container as its implementation. + */ namespace NSXObjectPointerArray { /** * @brief Inserts the object at the end of the array, if it is not yet present. - * @param objarray - * @param obj + * @param[in] objarray The array for adding. + * @param[in] obj The CKObject to be added. * @return True if the object was already present, false otherwise */ bool AddIfNotHere(XObjectPointerArray& objarray, CK2::ObjImpls::CKObject* obj); /** * @brief Check Object pointer validation and remove invalid pointers before deletion. - * @param objarray - * @param ctx + * @param objarray The array to be checked. + * @param ctx Associated CKContext. */ void PreDeletedCheck(XObjectPointerArray& objarray, CK2::CKContext* ctx); /** * @brief Check Object pointer validation and remove invalid pointers after deletion. - * @param objarray - * @param ctx - * @remark The performance of this function is extremely low. Use it carefully. + * @param objarray The array to be checked. + * @param ctx Associated CKContext. + * @warning The performance of this function is extremely bad. Use this carefully. */ void PostDeletedCheck(XObjectPointerArray& objarray, CK2::CKContext* ctx); /** * @brief Check Object pointer validation and remove invalid pointers before deletion. - * @param objarray - * @param ctx + * @param objarray The array to be checked. + * @param ctx Associated CKContext. */ void PreDeletedCheck(XList& objarray, CK2::CKContext* ctx); /** * @brief Check Object pointer validation and remove invalid pointers after deletion. - * @param objarray - * @param ctx - * @remark The performance of this function is extremely low. Use it carefully. + * @param objarray The array to be checked. + * @param ctx Associated CKContext. + * @warning The performance of this function is extremely bad. Use this carefully. */ void PostDeletedCheck(XList& objarray, CK2::CKContext* ctx);