Documentation for ParameterList

Former-commit-id: 5b8752a1d20eb894e17b271a019c379d867a4eb5

src/Nazara/Core/ParameterList.cpp

@@ -12,16 +12,33 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::ParameterList
+	* \brief Core class that represents a list of parameters
+	*/
+
+	/*!
+	* \brief Constructs a ParameterList object by copy
+	*/
+
 	ParameterList::ParameterList(const ParameterList& list)
 	{
 		operator=(list);
 	}
 
+	/*!
+	* \brief Destructs the object and clears
+	*/
+
 	ParameterList::~ParameterList()
 	{
 		Clear();
 	}
 
+	/*!
+	* \brief Clears the list of parameters
+	*/
+
 	void ParameterList::Clear()
 	{
 		for (auto it = m_parameters.begin(); it != m_parameters.end(); ++it)
@@ -30,8 +47,22 @@ namespace Nz
 		m_parameters.clear();
 	}
 
+	/*!
+	* \brief Gets the boolean parameter by name
+	* \return true if success
+	*
+	* \param name Name of the variable
+	* \param value Value to set
+	*
+	* \remark Produces a NazaraAssert if pointer is invalid
+	* \remark Produces a NazaraError if name is not a variable
+	* \remark Produces a NazaraError if value could not be convertible
+	*/
+
 	bool ParameterList::GetBooleanParameter(const String& name, bool* value) const
 	{
+		NazaraAssert(value, "Invalid pointer");
+
 		auto it = m_parameters.find(name);
 		if (it == m_parameters.end())
 		{
@@ -50,16 +81,16 @@ namespace Nz
 				return true;
 
 			case ParameterType_String:
-			{
-				bool converted;
-				if (it->second.value.stringVal.ToBool(&converted, String::CaseInsensitive))
 				{
-					*value = converted;
+					bool converted;
-					return true;
+					if (it->second.value.stringVal.ToBool(&converted, String::CaseInsensitive))
-				}
+					{
+						*value = converted;
+						return true;
+					}
 
-				break;
+					break;
-			}
+				}
 
 			case ParameterType_Float:
 			case ParameterType_None:
@@ -72,8 +103,22 @@ namespace Nz
 		return false;
 	}
 
+	/*!
+	* \brief Gets the float parameter by name
+	* \return true if success
+	*
+	* \param name Name of the variable
+	* \param value Value to set
+	*
+	* \remark Produces a NazaraAssert if pointer is invalid
+	* \remark Produces a NazaraError if name is not a variable
+	* \remark Produces a NazaraError if value could not be convertible
+	*/
+
 	bool ParameterList::GetFloatParameter(const String& name, float* value) const
 	{
+		NazaraAssert(value, "Invalid pointer");
+
 		auto it = m_parameters.find(name);
 		if (it == m_parameters.end())
 		{
@@ -92,16 +137,16 @@ namespace Nz
 				return true;
 
 			case ParameterType_String:
-			{
-				double converted;
-				if (it->second.value.stringVal.ToDouble(&converted))
 				{
-					*value = static_cast<float>(converted);
+					double converted;
-					return true;
+					if (it->second.value.stringVal.ToDouble(&converted))
-				}
+					{
+						*value = static_cast<float>(converted);
+						return true;
+					}
 
-				break;
+					break;
-			}
+				}
 
 			case ParameterType_Boolean:
 			case ParameterType_None:
@@ -114,8 +159,22 @@ namespace Nz
 		return false;
 	}
 
+	/*!
+	* \brief Gets the integer parameter by name
+	* \return true if success
+	*
+	* \param name Name of the variable
+	* \param value Value to set
+	*
+	* \remark Produces a NazaraAssert if pointer is invalid
+	* \remark Produces a NazaraError if name is not a variable
+	* \remark Produces a NazaraError if value could not be convertible
+	*/
+
 	bool ParameterList::GetIntegerParameter(const String& name, int* value) const
 	{
+		NazaraAssert(value, "Invalid pointer");
+
 		auto it = m_parameters.find(name);
 		if (it == m_parameters.end())
 		{
@@ -138,18 +197,18 @@ namespace Nz
 				return false;
 
 			case ParameterType_String:
-			{
-				long long converted;
-				if (it->second.value.stringVal.ToInteger(&converted))
 				{
-					if (converted <= std::numeric_limits<int>::max() && converted >= std::numeric_limits<int>::min())
+					long long converted;
+					if (it->second.value.stringVal.ToInteger(&converted))
 					{
-						*value = static_cast<int>(converted);
+						if (converted <= std::numeric_limits<int>::max() && converted >= std::numeric_limits<int>::min())
-						return true;
+						{
+							*value = static_cast<int>(converted);
+							return true;
+						}
 					}
+					break;
 				}
-				break;
-			}
 
 			case ParameterType_None:
 			case ParameterType_Pointer:
@@ -161,8 +220,22 @@ namespace Nz
 		return false;
 	}
 
+	/*!
+	* \brief Gets the parameter by name
+	* \return true if success
+	*
+	* \param name Name of the variable
+	* \param type Type to set
+	*
+	* \remark Produces a NazaraAssert if pointer is invalid
+	* \remark Produces a NazaraError if name is not a variable
+	* \remark Produces a NazaraError if value could not be convertible
+	*/
+
 	bool ParameterList::GetParameterType(const String& name, ParameterType* type) const
 	{
+		NazaraAssert(type, "Invalid pointer");
+
 		auto it = m_parameters.find(name);
 		if (it == m_parameters.end())
 			return false;
@@ -172,8 +245,22 @@ namespace Nz
 		return true;
 	}
 
+	/*!
+	* \brief Gets the pointer parameter by name
+	* \return true if success
+	*
+	* \param name Name of the variable
+	* \param value Value to set
+	*
+	* \remark Produces a NazaraAssert if pointer is invalid
+	* \remark Produces a NazaraError if name is not a variable
+	* \remark Produces a NazaraError if value could not be convertible
+	*/
+
 	bool ParameterList::GetPointerParameter(const String& name, void** value) const
 	{
+		NazaraAssert(value, "Invalid pointer");
+
 		auto it = m_parameters.find(name);
 		if (it == m_parameters.end())
 		{
@@ -203,8 +290,22 @@ namespace Nz
 		return false;
 	}
 
+	/*!
+	* \brief Gets the string parameter by name
+	* \return true if success
+	*
+	* \param name Name of the variable
+	* \param value Value to set
+	*
+	* \remark Produces a NazaraAssert if pointer is invalid
+	* \remark Produces a NazaraError if name is not a variable
+	* \remark Produces a NazaraError if value could not be convertible
+	*/
+
 	bool ParameterList::GetStringParameter(const String& name, String* value) const
 	{
+		NazaraAssert(value, "Invalid pointer");
+
 		auto it = m_parameters.find(name);
 		if (it == m_parameters.end())
 		{
@@ -247,8 +348,22 @@ namespace Nz
 		return false;
 	}
 
+	/*!
+	* \brief Gets the user parameter by name
+	* \return true if success
+	*
+	* \param name Name of the variable
+	* \param value Value to set
+	*
+	* \remark Produces a NazaraAssert if pointer is invalid
+	* \remark Produces a NazaraError if name is not a variable
+	* \remark Produces a NazaraError if value could not be convertible
+	*/
+
 	bool ParameterList::GetUserdataParameter(const String& name, void** value) const
 	{
+		NazaraAssert(value, "Invalid pointer");
+
 		auto it = m_parameters.find(name);
 		if (it == m_parameters.end())
 		{
@@ -268,11 +383,26 @@ namespace Nz
 		}
 	}
 
+	/*!
+	* \brief Checks whether the parameter list has a parameter with that name
+	* \return true if found
+	*
+	* \param name Name of the parameter
+	*/
+
 	bool ParameterList::HasParameter(const String& name) const
 	{
 		return m_parameters.find(name) != m_parameters.end();
 	}
 
+	/*!
+	* \brief Removes the parameter with that name
+	*
+	* Removes the parameter with that name, if not found, nothing is done
+	*
+	* \param name Name of the parameter
+	*/
+
 	void ParameterList::RemoveParameter(const String& name)
 	{
 		auto it = m_parameters.find(name);
@@ -283,6 +413,12 @@ namespace Nz
 		}
 	}
 
+	/*!
+	* \brief Sets the parameter with the name to ParameterType_None
+	*
+	* \param name Name of the parameter
+	*/
+
 	void ParameterList::SetParameter(const String& name)
 	{
 		std::pair<ParameterMap::iterator, bool> pair = m_parameters.insert(std::make_pair(name, Parameter()));
@@ -294,6 +430,13 @@ namespace Nz
 		parameter.type = ParameterType_None;
 	}
 
+	/*!
+	* \brief Sets the parameter with the name to the value
+	*
+	* \param name Name of the parameter
+	* \param value Value of the parameter
+	*/
+
 	void ParameterList::SetParameter(const String& name, const String& value)
 	{
 		std::pair<ParameterMap::iterator, bool> pair = m_parameters.insert(std::make_pair(name, Parameter()));
@@ -307,6 +450,13 @@ namespace Nz
 		PlacementNew<String>(&parameter.value.stringVal, value);
 	}
 
+	/*!
+	* \brief Sets the parameter with the name to the value
+	*
+	* \param name Name of the parameter
+	* \param value Value of the parameter
+	*/
+
 	void ParameterList::SetParameter(const String& name, const char* value)
 	{
 		std::pair<ParameterMap::iterator, bool> pair = m_parameters.insert(std::make_pair(name, Parameter()));
@@ -320,6 +470,13 @@ namespace Nz
 		PlacementNew<String>(&parameter.value.stringVal, value);
 	}
 
+	/*!
+	* \brief Sets the parameter with the name to the value
+	*
+	* \param name Name of the parameter
+	* \param value Value of the parameter
+	*/
+
 	void ParameterList::SetParameter(const String& name, void* value)
 	{
 		std::pair<ParameterMap::iterator, bool> pair = m_parameters.insert(std::make_pair(name, Parameter()));
@@ -332,6 +489,14 @@ namespace Nz
 		parameter.value.ptrVal = value;
 	}
 
+	/*!
+	* \brief Sets the parameter with the name to the value
+	*
+	* \param name Name of the parameter
+	* \param value Value of the parameter
+	* \param destructor Destructor for dynamic variable
+	*/
+
 	void ParameterList::SetParameter(const String& name, void* value, Destructor destructor)
 	{
 		std::pair<ParameterMap::iterator, bool> pair = m_parameters.insert(std::make_pair(name, Parameter()));
@@ -344,6 +509,13 @@ namespace Nz
 		parameter.value.userdataVal = new Parameter::UserdataValue(destructor, value);
 	}
 
+	/*!
+	* \brief Sets the parameter with the name to the value
+	*
+	* \param name Name of the parameter
+	* \param value Value of the parameter
+	*/
+
 	void ParameterList::SetParameter(const String& name, bool value)
 	{
 		std::pair<ParameterMap::iterator, bool> pair = m_parameters.insert(std::make_pair(name, Parameter()));
@@ -356,6 +528,13 @@ namespace Nz
 		parameter.value.boolVal = value;
 	}
 
+	/*!
+	* \brief Sets the parameter with the name to the value
+	*
+	* \param name Name of the parameter
+	* \param value Value of the parameter
+	*/
+
 	void ParameterList::SetParameter(const String& name, float value)
 	{
 		std::pair<ParameterMap::iterator, bool> pair = m_parameters.insert(std::make_pair(name, Parameter()));
@@ -368,6 +547,13 @@ namespace Nz
 		parameter.value.floatVal = value;
 	}
 
+	/*!
+	* \brief Sets the parameter with the name to the value
+	*
+	* \param name Name of the parameter
+	* \param value Value of the parameter
+	*/
+
 	void ParameterList::SetParameter(const String& name, int value)
 	{
 		std::pair<ParameterMap::iterator, bool> pair = m_parameters.insert(std::make_pair(name, Parameter()));
@@ -380,6 +566,13 @@ namespace Nz
 		parameter.value.intVal = value;
 	}
 
+	/*!
+	* \brief Assigns the content of the other parameter list to this
+	* \return A reference to this
+	*
+	* \param list List to assign
+	*/
+
 	ParameterList& ParameterList::operator=(const ParameterList& list)
 	{
 		Clear();
@@ -418,6 +611,12 @@ namespace Nz
 		return *this;
 	}
 
+	/*!
+	* \brief Destroys the value for the parameter
+	*
+	* \param parameter Parameter to destroy
+	*/
+
 	void ParameterList::DestroyValue(Parameter& parameter)
 	{
 		switch (parameter.type)
@@ -427,15 +626,15 @@ namespace Nz
 				break;
 
 			case ParameterType_Userdata:
-			{
-				Parameter::UserdataValue* userdata = parameter.value.userdataVal;
-				if (--userdata->counter == 0)
 				{
-					userdata->destructor(userdata->ptr);
+					Parameter::UserdataValue* userdata = parameter.value.userdataVal;
-					delete userdata;
+					if (--userdata->counter == 0)
+					{
+						userdata->destructor(userdata->ptr);
+						delete userdata;
+					}
+					break;
 				}
-				break;
-			}
 
 			case ParameterType_Boolean:
 			case ParameterType_Float:

tests/Engine/Core/ParameterList.cpp

@@ -0,0 +1,52 @@
+#include <Nazara/Core/ParameterList.hpp>
+#include <Catch/catch.hpp>
+
+#include <Nazara/Core/String.hpp>
+
+SCENARIO("ParameterList", "[CORE][PARAMETERLIST]")
+{
+	GIVEN("An empty ParameterList")
+	{
+		Nz::ParameterList parameterList;
+
+		WHEN("We add String 'string'")
+		{
+			Nz::String string("string");
+			parameterList.SetParameter("string", string);
+
+			THEN("We can get it back")
+			{
+				Nz::String newString;
+				REQUIRE(parameterList.GetStringParameter("string", &newString));
+				REQUIRE(newString == string);
+			}
+		}
+
+		WHEN("We add Float '3.f'")
+		{
+			float fl = 3.f;
+			parameterList.SetParameter("float", fl);
+
+			THEN("We can get it back")
+			{
+				float newFl;
+				REQUIRE(parameterList.GetFloatParameter("float", &newFl));
+				REQUIRE(newFl == fl);
+			}
+		}
+
+		WHEN("We add Pointer to stack value")
+		{
+			int stackValue = 3;
+			void* ptrToStackValue = &stackValue; // Ugly conversion
+			parameterList.SetParameter("ptr", ptrToStackValue);
+
+			THEN("We can get it back")
+			{
+				void* newPtrToStackValue = nullptr;
+				REQUIRE(parameterList.GetPointerParameter("ptr", &newPtrToStackValue));
+				REQUIRE(newPtrToStackValue == ptrToStackValue);
+			}
+		}
+	}
+}