From 97311adf60d56b3f8226e6aee507bbbb399251a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vicente=20Mataix=20Ferr=C3=A1ndiz?= Date: Thu, 5 Oct 2023 13:27:56 +0200 Subject: [PATCH] [Core][Documentation] Adding documentation to `DataValueContainer` --- kratos/containers/data_value_container.cpp | 99 ++++---- kratos/containers/data_value_container.h | 277 +++++++++++++++------ 2 files changed, 252 insertions(+), 124 deletions(-) diff --git a/kratos/containers/data_value_container.cpp b/kratos/containers/data_value_container.cpp index 193d9e2887dd..276f6122bb23 100644 --- a/kratos/containers/data_value_container.cpp +++ b/kratos/containers/data_value_container.cpp @@ -4,37 +4,33 @@ // _|\_\_| \__,_|\__|\___/ ____/ // Multi-Physics // -// License: BSD License -// Kratos default license: kratos/license.txt +// License: BSD License +// Kratos default license: kratos/license.txt // -// Main authors: Pooyan Dadvand, Daniel Diez +// Main authors: Pooyan Dadvand +// Daniel Diez // -// - // System includes - // External includes - // Project includes #include "containers/data_value_container.h" - namespace Kratos { - KRATOS_CREATE_LOCAL_FLAG(DataValueContainer, OVERWRITE_OLD_VALUES, 0); - +KRATOS_CREATE_LOCAL_FLAG(DataValueContainer, OVERWRITE_OLD_VALUES, 0); - void DataValueContainer::Merge( - const DataValueContainer& rOther, - const Flags Options) - { - const bool overwrite_values = Options.Is(OVERWRITE_OLD_VALUES); +void DataValueContainer::Merge( + const DataValueContainer& rOther, + const Flags Options + ) +{ + const bool overwrite_values = Options.Is(OVERWRITE_OLD_VALUES); - if (overwrite_values) { - for (const_iterator i = rOther.mData.begin(); i != rOther.mData.end(); ++i) { + if (overwrite_values) { + for (const_iterator i = rOther.mData.begin(); i != rOther.mData.end(); ++i) { bool variable_already_exist = false; for (iterator j = mData.begin(); j != mData.end(); ++j) { if (i->first == j->first) { @@ -43,58 +39,55 @@ namespace Kratos j->second = i->first->Clone(i->second); } } - if (!variable_already_exist) mData.push_back(ValueType(i->first, i->first->Clone(i->second))); + if (!variable_already_exist) { + mData.push_back(ValueType(i->first, i->first->Clone(i->second))); } } - - else { - for (const_iterator i = rOther.mData.begin(); i != rOther.mData.end(); ++i) { + } else { + for (const_iterator i = rOther.mData.begin(); i != rOther.mData.end(); ++i) { bool variable_already_exist = false; for (iterator j = mData.begin(); j != mData.end(); ++j) { if (i->first == j->first) { variable_already_exist = true; } } - if (!variable_already_exist) mData.push_back(ValueType(i->first, i->first->Clone(i->second))); + if (!variable_already_exist) { + mData.push_back(ValueType(i->first, i->first->Clone(i->second))); } } } +} - void DataValueContainer::save(Serializer& rSerializer) const - { - KRATOS_TRY - - std::size_t size = mData.size(); - rSerializer.save("Size", size); - for (std::size_t i = 0; i < size; i++) - { - rSerializer.save("Variable Name", mData[i].first->Name()); - mData[i].first->Save(rSerializer, mData[i].second); - } +void DataValueContainer::save(Serializer& rSerializer) const +{ + KRATOS_TRY - KRATOS_CATCH("") + std::size_t size = mData.size(); + rSerializer.save("Size", size); + for (std::size_t i = 0; i < size; i++) { + rSerializer.save("Variable Name", mData[i].first->Name()); + mData[i].first->Save(rSerializer, mData[i].second); } - void DataValueContainer::load(Serializer& rSerializer) - { - KRATOS_TRY - - std::size_t size; - rSerializer.load("Size", size); - mData.resize(size); - std::string name; - for (std::size_t i = 0; i < size; i++) - { - rSerializer.load("Variable Name", name); - mData[i].first = KratosComponents::pGet(name); - mData[i].first->Allocate(&(mData[i].second)); - mData[i].first->Load(rSerializer, mData[i].second); - } + KRATOS_CATCH("") +} - KRATOS_CATCH("") +void DataValueContainer::load(Serializer& rSerializer) +{ + KRATOS_TRY + + std::size_t size; + rSerializer.load("Size", size); + mData.resize(size); + std::string name; + for (std::size_t i = 0; i < size; i++) { + rSerializer.load("Variable Name", name); + mData[i].first = KratosComponents::pGet(name); + mData[i].first->Allocate(&(mData[i].second)); + mData[i].first->Load(rSerializer, mData[i].second); } + KRATOS_CATCH("") +} -} // namespace Kratos. - - +} // namespace Kratos. \ No newline at end of file diff --git a/kratos/containers/data_value_container.h b/kratos/containers/data_value_container.h index e0d81e010309..2b6a791f460d 100644 --- a/kratos/containers/data_value_container.h +++ b/kratos/containers/data_value_container.h @@ -4,17 +4,13 @@ // _|\_\_| \__,_|\__|\___/ ____/ // Multi-Physics // -// License: BSD License -// Kratos default license: kratos/license.txt +// License: BSD License +// Kratos default license: kratos/license.txt // // Main authors: Pooyan Dadvand // - -#if !defined(KRATOS_DATA_VALUE_CONTAINER_H_INCLUDED ) -#define KRATOS_DATA_VALUE_CONTAINER_H_INCLUDED - - +#pragma once // System includes #include @@ -22,10 +18,8 @@ #include #include - // External includes - // Project includes #include "includes/define.h" #include "containers/variable.h" @@ -36,7 +30,6 @@ #include "utilities/openmp_utils.h" #endif - namespace Kratos { @@ -59,34 +52,39 @@ namespace Kratos ///@name Kratos Classes ///@{ -/// Short class definition. -/** Detail class definition. -*/ +/** + * @class DataValueContainer + * @ingroup KratosCore + * @brief Container for storing data values associated with variables. + * @details This class provides a container for storing data values associated with variables. + * @author Pooyan Dadvand + */ class KRATOS_API(KRATOS_CORE) DataValueContainer { - public: ///@name Type Definitions ///@{ + + /// Define local flag KRATOS_DEFINE_LOCAL_FLAG(OVERWRITE_OLD_VALUES); /// Pointer definition of DataValueContainer KRATOS_CLASS_POINTER_DEFINITION(DataValueContainer); /// Type of the container used for variables - typedef std::pair ValueType; + using ValueType = std::pair; /// Type of the container used for variables - typedef std::vector ContainerType; + using ContainerType = std::vector; /// Type of the container used for variables - typedef std::vector::iterator iterator; + using iterator = ContainerType::iterator; /// Type of the container used for variables - typedef std::vector::const_iterator const_iterator; + using const_iterator = ContainerType::const_iterator; /// Type of the container used for variables - typedef std::vector::size_type SizeType; + using SizeType = ContainerType::size_type; ///@} ///@name Life Cycle @@ -109,67 +107,143 @@ class KRATOS_API(KRATOS_CORE) DataValueContainer i->first->Delete(i->second); } - ///@} ///@name Operators ///@{ - template const TDataType& operator()(const VariableData& rThisVariable) const + /** + * @brief Accessor operator for retrieving a data value by a VariableData. + * @details This operator allows you to retrieve a data value by providing a VariableData object. + * @tparam TDataType The data type of the value to retrieve. + * @param rThisVariable The VariableData object specifying the variable. + * @return A reference to the data value. + */ + template + const TDataType& operator()(const VariableData& rThisVariable) const { return GetValue(rThisVariable); } - template TDataType& operator()(const Variable& rThisVariable) + /** + * @brief Accessor operator for retrieving a data value by a Variable. + * @details This operator allows you to retrieve a data value by providing a Variable object. + * @tparam TDataType The data type of the value to retrieve. + * @param rThisVariable The Variable object specifying the variable. + * @return A reference to the data value. + */ + template + TDataType& operator()(const Variable& rThisVariable) { return GetValue(rThisVariable); } - template const TDataType& operator()(const Variable& rThisVariable) const + /** + * @brief Accessor operator for retrieving a data value by a Variable (const version). + * @details This operator allows you to retrieve a data value by providing a Variable object. + * @tparam TDataType The data type of the value to retrieve. + * @param rThisVariable The Variable object specifying the variable. + * @return A reference to the data value. + */ + template + const TDataType& operator()(const Variable& rThisVariable) const { return GetValue(rThisVariable); } - template TDataType& operator[](const VariableData& rThisVariable) + /** + * @brief Index operator for retrieving a data value by a VariableData. + * @details This operator allows you to retrieve a data value by providing a VariableData object. + * @tparam TDataType The data type of the value to retrieve. + * @param rThisVariable The VariableData object specifying the variable. + * @return A reference to the data value. + */ + template + TDataType& operator[](const VariableData& rThisVariable) { return GetValue(rThisVariable); } - template const TDataType& operator[](const VariableData& rThisVariable) const + /** + * @brief Index operator for retrieving a data value by a VariableData (const version). + * @details This operator allows you to retrieve a data value by providing a VariableData object. + * @tparam TDataType The data type of the value to retrieve. + * @param rThisVariable The VariableData object specifying the variable. + * @return A reference to the data value. + */ + template + const TDataType& operator[](const VariableData& rThisVariable) const { return GetValue(rThisVariable); } - template TDataType& operator[](const Variable& rThisVariable) + /** + * @brief Index operator for retrieving a data value by a Variable. + * @details This operator allows you to retrieve a data value by providing a Variable object. + * @tparam TDataType The data type of the value to retrieve. + * @param rThisVariable The Variable object specifying the variable. + * @return A reference to the data value. + */ + template + TDataType& operator[](const Variable& rThisVariable) { return GetValue(rThisVariable); } - template const TDataType& operator[](const Variable& rThisVariable) const + /** + * @brief Index operator for retrieving a data value by a Variable (const version). + * @details This operator allows you to retrieve a data value by providing a Variable object. + * @tparam TDataType The data type of the value to retrieve. + * @param rThisVariable The Variable object specifying the variable. + * @return A reference to the data value. + */ + template + const TDataType& operator[](const Variable& rThisVariable) const { return GetValue(rThisVariable); } + /** + * @brief Iterator pointing to the beginning of the container. + * @return An iterator pointing to the beginning of the container. + */ iterator begin() { return mData.begin(); } + /** + * @brief Const iterator pointing to the beginning of the container. + * @return A const iterator pointing to the beginning of the container. + */ const_iterator begin() const { return mData.begin(); } + /** + * @brief Iterator pointing to the end of the container. + * @return An iterator pointing to the end of the container. + */ iterator end() { return mData.end(); } + /** + * @brief Const iterator pointing to the end of the container. + * @return A const iterator pointing to the end of the container. + */ const_iterator end() const { return mData.end(); } - /// Assignment operator. + /** + * @brief Assignment operator for copying data from another DataValueContainer. + * @details This operator allows you to assign the contents of another DataValueContainer to this container. + * @param rOther The DataValueContainer to copy data from. + * @return A reference to the modified DataValueContainer. + */ DataValueContainer& operator=(const DataValueContainer& rOther) { Clear(); @@ -184,7 +258,14 @@ class KRATOS_API(KRATOS_CORE) DataValueContainer ///@name Operations ///@{ - template TDataType& GetValue(const Variable& rThisVariable) + /** + * @brief Gets the value associated with a given variable. + * @tparam TDataType The data type of the variable. + * @param rThisVariable The variable for which the value is to be retrieved. + * @return Reference to the value of the provided variable. + */ + template + TDataType& GetValue(const Variable& rThisVariable) { typename ContainerType::iterator i; @@ -202,8 +283,15 @@ class KRATOS_API(KRATOS_CORE) DataValueContainer return *(static_cast(mData.back().second) + rThisVariable.GetComponentIndex()); } - //TODO: make the variable of the constant version consistent with the one of the "classical" one - template const TDataType& GetValue(const Variable& rThisVariable) const + /** + * @brief Gets the value associated with a given variable (const version). + * @tparam TDataType The data type of the variable. + * @param rThisVariable The variable for which the value is to be retrieved. + * @return Const reference to the value of the provided variable. + * @todo Make the variable of the constant version consistent with the one of the "classical" one + */ + template + const TDataType& GetValue(const Variable& rThisVariable) const { typename ContainerType::const_iterator i; @@ -213,12 +301,23 @@ class KRATOS_API(KRATOS_CORE) DataValueContainer return rThisVariable.Zero(); } + /** + * @brief Gets the size of the data container. + * @return Size of the data container. + */ SizeType Size() { return mData.size(); } - template void SetValue(const Variable& rThisVariable, TDataType const& rValue) + /** + * @brief Sets the value for a given variable. + * @tparam TDataType The data type of the variable. + * @param rThisVariable The variable for which the value is to be set. + * @param rValue The value to be set for the variable. + */ + template + void SetValue(const Variable& rThisVariable, TDataType const& rValue) { typename ContainerType::iterator i; @@ -231,17 +330,25 @@ class KRATOS_API(KRATOS_CORE) DataValueContainer } } - template void Erase(const Variable& rThisVariable) + /** + * @brief Erases the value associated with a given variable. + * @tparam TDataType The data type of the variable. + * @param rThisVariable The variable whose associated value is to be erased. + */ + template + void Erase(const Variable& rThisVariable) { typename ContainerType::iterator i; - if ((i = std::find_if(mData.begin(), mData.end(), IndexCheck(rThisVariable.SourceKey()))) != mData.end()) - { + if ((i = std::find_if(mData.begin(), mData.end(), IndexCheck(rThisVariable.SourceKey()))) != mData.end()) { i->first->Delete(i->second); mData.erase(i); } } + /** + * @brief Clears the entire data container. + */ void Clear() { for(ContainerType::iterator i = mData.begin() ; i != mData.end() ; i++) @@ -250,22 +357,37 @@ class KRATOS_API(KRATOS_CORE) DataValueContainer mData.clear(); } + /** + * @brief Merges this data container with another data container. + * @param rOther The other data container to be merged. + * @param Options Flags for the merging options. + */ void Merge(const DataValueContainer& rOther, const Flags Options); ///@} ///@name Access ///@{ - ///@} ///@name Inquiry ///@{ - template bool Has(const Variable& rThisVariable) const + /** + * @brief Checks if the data container has a value associated with a given variable. + * @tparam TDataType The data type of the variable. + * @param rThisVariable The variable for which the check is to be made. + * @return True if the variable has an associated value in the container, otherwise false. + */ + template + bool Has(const Variable& rThisVariable) const { return (std::find_if(mData.begin(), mData.end(), IndexCheck(rThisVariable.SourceKey())) != mData.end()); } + /** + * @brief Checks if the data container is empty. + * @return True if the container is empty, otherwise false. + */ bool IsEmpty() const { return mData.empty(); @@ -275,52 +397,55 @@ class KRATOS_API(KRATOS_CORE) DataValueContainer ///@name Input and output ///@{ - /// Turn back information as a string. + /** + * @brief Retrieves a string representation of the data value container. + * @return A string that describes the data value container. + */ virtual std::string Info() const { return std::string("data value container"); } - /// Print information about this object. + /** + * @brief Outputs a brief description of the data value container to a given stream. + * @param rOStream The output stream to which the information should be printed. + */ virtual void PrintInfo(std::ostream& rOStream) const { rOStream << "data value container"; } - /// Print object's data. + /** + * @brief Outputs the detailed data contents of the data value container to a given stream. + * @details For each data entry, it prints the variable type and its associated value. + * @param rOStream The output stream to which the data should be printed. + */ virtual void PrintData(std::ostream& rOStream) const { - for(const_iterator i = mData.begin() ; i != mData.end() ; ++i) - { + for(const_iterator i = mData.begin() ; i != mData.end() ; ++i) { rOStream <<" "; i->first->Print(i->second, rOStream); rOStream << std::endl; } } - ///@} ///@name Friends ///@{ - ///@} - protected: ///@name Protected static Member Variables ///@{ - ///@} ///@name Protected member Variables ///@{ - ///@} ///@name Protected Operators ///@{ - ///@} ///@name Protected Operations ///@{ @@ -329,47 +454,59 @@ class KRATOS_API(KRATOS_CORE) DataValueContainer ///@name Protected Access ///@{ - ///@} ///@name Protected Inquiry ///@{ - ///@} ///@name Protected LifeCycle ///@{ - ///@} - private: + ///@{ + /** + * @brief Functor class used to check if a `ValueType` has a specific index key. + * @details The `IndexCheck` class is designed to be used with algorithms like `std::find_if` to search for a `ValueType` with a specific source key. + */ class IndexCheck { - std::size_t mI; + std::size_t mI; /// The source key index to be checked against. + public: + + /** + * @brief Constructor that initializes the functor with a specific source key index. + * @param I The source key index to be checked against. + */ explicit IndexCheck(std::size_t I) : mI(I) {} + + /** + * @brief Overloaded function call operator to compare the `ValueType`'s source key with the stored index. + * @param I The `ValueType` whose source key is to be compared. + * @return True if the `ValueType`'s source key matches the stored index, otherwise false. + */ bool operator()(const ValueType& I) { return I.first->SourceKey() == mI; } }; + ///@} ///@name Static Member Variables ///@{ - ///@} ///@name Member Variables ///@{ - ContainerType mData; + ContainerType mData; /// The data container considered ///@} ///@name Private Operators ///@{ - ///@} ///@name Private Operations ///@{ @@ -378,44 +515,47 @@ class KRATOS_API(KRATOS_CORE) DataValueContainer ///@name Serialization ///@{ + /** + * @class Serializer + * @brief A fried class responsible for handling the serialization process. + */ friend class Serializer; + /** + * @brief Extract the object's state and uses the Serializer to store it. + * @param rSerializer Serializer instance to be used for saving. + */ virtual void save(Serializer& rSerializer) const; + /** + * @brief Set the object's state based on data provided by the Serializer. + * @param rSerializer Serializer instance to be used for loading. + */ virtual void load(Serializer& rSerializer); - ///@} ///@name Private Access ///@{ - ///@} ///@name Private Inquiry ///@{ - ///@} ///@name Un accessible methods ///@{ - ///@} - }; // Class DataValueContainer - ///@} - ///@name Type Definitions ///@{ - ///@} ///@name Input and output ///@{ - /// input stream function inline std::istream& operator >> (std::istream& rIStream, DataValueContainer& rThis); @@ -432,9 +572,4 @@ inline std::ostream& operator << (std::ostream& rOStream, } ///@} - -} // namespace Kratos. - -#endif // KRATOS_DATA_VALUE_CONTAINER_H_INCLUDED defined - - +} // namespace Kratos. \ No newline at end of file