diff --git a/alib2common/src/base/CommonBase.hpp b/alib2common/src/base/CommonBase.hpp
index b9b4714796a20dd7840106377140bba86aae1346..4d657deed333edaa9d4417d2c81266cf7680876f 100644
--- a/alib2common/src/base/CommonBase.hpp
+++ b/alib2common/src/base/CommonBase.hpp
@@ -28,7 +28,7 @@ public:
};
/**
- * Middle common base specifying usual operations of all datatypes in algorithms library toolkit.
+ * Middle common base specifies usual operations of all datatypes in algorithms library toolkit.
*
* \tparam T type that inherits from the commmon base.
*/
@@ -46,7 +46,7 @@ public:
virtual T * plunder ( ) && = 0;
/**
- * Compares this object with other for inequality
+ * Compares this object with other for inequality.
*
* \returns true if this and other objects are not equal, false othervise
*/
@@ -55,7 +55,7 @@ public:
}
/**
- * Compares this object with other for equality
+ * Compares this object with other for equality.
*
* \returns true if this and other objects are equal, false othervise
*/
@@ -64,7 +64,7 @@ public:
}
/**
- * Determines whether this object is strictly smaller in relation to the other object
+ * Determines whether this object is strictly smaller in relation to the other object.
*
* \returns true if this object is strictly smaller than other object are not equal, false othervise
*/
@@ -73,7 +73,7 @@ public:
}
/**
- * Determines whether this object is smaller or equal in relation to the other object
+ * Determines whether this object is smaller or equal in relation to the other object.
*
* \returns true if this object is smaller or equal than other object are not equal, false othervise
*/
@@ -82,7 +82,7 @@ public:
}
/**
- * Determines whether this object is strictly bigger in relation to the other object
+ * Determines whether this object is strictly bigger in relation to the other object.
*
* \returns true if this object is strictly bigger than other object are not equal, false othervise
*/
@@ -91,7 +91,7 @@ public:
}
/**
- * Determines whether this object is bigger or equal in relation to the other object
+ * Determines whether this object is bigger or equal in relation to the other object.
*
* \returns true if this object is bigger or equal than other object are not equal, false othervise
*/
@@ -110,22 +110,30 @@ public:
*/
virtual int compare ( const T & other ) const = 0;
+ /**
+ * Print this object as raw representation to ostream.
+ *
+ * \param os ostream where to print
+ * \param instance object to print
+ *
+ * \returns modified output stream
+ */
friend std::ostream & operator <<( std::ostream & os, const T & instance ) {
instance >> os;
return os;
}
/**
- * Print this instance as raw representation to ostream
+ * Print this instance as raw representation to ostream.
*
- * @param os ostream where to print
+ * \param os ostream where to print
*/
virtual void operator >>( std::ostream & ) const = 0;
/**
- * Casts this instance to as compact as possible string representation
+ * Casts this instance to as compact as possible string representation.
*
- * \returns string representation of the grammar
+ * \returns string representation of the object
*/
virtual explicit operator std::string ( ) const = 0;
@@ -141,7 +149,9 @@ class CommonBase : public CommonBaseMiddle < T > {
public:
/**
- * @copydoc alib::CommonBaseMiddle<ObjectBase>::normalize ( )
+ * Helper for normalisation of templated datatypes in algorithms library toolkit to the same types but with default template parameters.
+ *
+ * \returns new instance of the grammar with default template parameters or unmodified instance if the template parameters were already default ones
*/
virtual T * normalize ( ) && = 0;
};
diff --git a/alib2common/src/base/WrapperBase.hpp b/alib2common/src/base/WrapperBase.hpp
index 21e2f1f6a153a9528ae942b996376a07ea4922de..1e74b861d47f84c252ce8d849e05b5adce459812 100644
--- a/alib2common/src/base/WrapperBase.hpp
+++ b/alib2common/src/base/WrapperBase.hpp
@@ -13,12 +13,23 @@
namespace alib {
+/**
+ * Most common base for every datatype wrapper in algorithms library toolkit.
+ */
class WrapperBaseBase {
public:
+ /**
+ * Virtual destructor just to have it.
+ */
virtual ~WrapperBaseBase ( ) noexcept { }
};
+/**
+ * Middle wrapper base specifies usual operations of all datatypes wrappers in algorithms library toolkit.
+ *
+ * \tparam T type that is a base class of the concrete wrapper that inherits from this.
+ */
template < typename T >
class WrapperBaseMiddle : public WrapperBaseBase {
protected:
@@ -33,25 +44,52 @@ private:
}
public:
+ /**
+ * Disable construction from integer so that it is not confused with other constructors.
+ */
WrapperBaseMiddle ( int ) = delete;
+ /**
+ * Constructor that wraps raw pointer. Takes ownership of the pointer.
+ */
explicit WrapperBaseMiddle ( T * data ) : m_data ( data ) {
}
+ /**
+ * Constructor that wraps an object given by constant reference. Uses clone of the parameter internally.
+ */
explicit WrapperBaseMiddle ( const T & data ) : m_data ( data.clone ( ) ) {
}
+ /**
+ * Constructor that wraps an object given by r-value reference. Uses plunder of the parameter internally.
+ */
explicit WrapperBaseMiddle ( T && data ) : m_data ( std::move ( data ).plunder ( ) ) {
}
+ /**
+ * Gets the wrapped object.
+ *
+ * \returns wrapped object.
+ */
const T & getData ( ) const {
return * m_data;
}
+ /**
+ * Gets the wrapped object.
+ *
+ * \returns wrapped object.
+ */
T & getData ( ) {
return * m_data;
}
+ /**
+ * Sets the wrapped object from raw pointer. Takes ownership of the pointer.
+ *
+ * Internally handles situation like storing the same value that is already wrapped. Usefull in normalisation.
+ */
void setData ( T * data ) {
if ( & getData ( ) == data )
return;
@@ -59,38 +97,82 @@ public:
this->m_data = std::cow_shared_ptr < T > ( data );
}
+ /**
+ * Sets the wrapped object from constant reference. Uses clone of the parameter internally.
+ */
void setData ( const T & data ) {
setData ( data.clone ( ) );
}
+ /**
+ * Sets the wrapped object from r-value reference. Uses plunder of the parameter internally.
+ */
void setData ( T && data ) {
setData ( std::move ( data ).plunder ( ) );
}
+ /**
+ * Determines whether this object is bigger or equal in relation to the other object.
+ *
+ * \returns true if this object is bigger or equal than other object are not equal, false othervise
+ */
bool operator >=( const WrapperBaseMiddle & other ) const {
return this->compare ( other ) >= 0;
}
+ /**
+ * Determines whether this object is smaller or equal in relation to the other object.
+ *
+ * \returns true if this object is smaller or equal than other object are not equal, false othervise
+ */
bool operator <=( const WrapperBaseMiddle & other ) const {
return this->compare ( other ) <= 0;
}
+ /**
+ * Determines whether this object is strictly bigger in relation to the other object.
+ *
+ * \returns true if this object is strictly bigger than other object are not equal, false othervise
+ */
bool operator >( const WrapperBaseMiddle & other ) const {
return this->compare ( other ) > 0;
}
+ /**
+ * Determines whether this object is strictly smaller in relation to the other object.
+ *
+ * \returns true if this object is strictly smaller than other object are not equal, false othervise
+ */
bool operator <( const WrapperBaseMiddle & other ) const {
return this->compare ( other ) < 0;
}
+ /**
+ * Compares this object with other for inequality.
+ *
+ * \returns true if this and other objects are not equal, false othervise
+ */
bool operator !=( const WrapperBaseMiddle & other ) const {
return this->compare ( other ) != 0;
}
+ /**
+ * Compares this object with other for equality.
+ *
+ * \returns true if this and other objects are equal, false othervise
+ */
bool operator ==( const WrapperBaseMiddle & other ) const {
return this->compare ( other ) == 0;
}
+ /**
+ * \brief Compares this wrapper with another, establishing relationship between them.
+ *
+ * \returns result of actual comparison of wrapped objects returning:
+ * value < 0 if this < other
+ * value == 0 if this == other
+ * value > 0 if this > other
+ */
int compare ( const WrapperBaseMiddle & other ) const {
if ( this->m_data.get ( ) == other.m_data.get ( ) ) return 0;
@@ -101,15 +183,33 @@ public:
return res;
}
+ /**
+ * Print the wrapped object as raw representation to ostream.
+ *
+ * \param os ostream where to print
+ * \param instance wrapper to print
+ *
+ * \returns modified output stream
+ */
friend std::ostream & operator <<( std::ostream & os, const WrapperBaseMiddle & instance ) {
- os << * ( instance.m_data );
+ os << instance.getData ( );
return os;
}
+ /**
+ * Casts the wrapped object to as compact as possible string representation.
+ *
+ * \returns string representation of the wrapped object
+ */
explicit operator std::string ( ) const {
return ( std::string ) * m_data;
}
+ /**
+ * Internaly increments the wrapped object by one to make different from the original one.
+ *
+ * \returns reference to this
+ */
WrapperBaseMiddle < T > & operator ++ ( ) {
T * res = std::move ( this->getData ( ) ).inc ( );
@@ -120,11 +220,21 @@ public:
}
};
+/**
+ * The actual wrapper base that is to be used as a base class for concrete type hierarchy object types.
+ *
+ * \tparam T type that is a base class of the concrete wrapper that inherits from this.
+ */
template < typename T >
class WrapperBase : public WrapperBaseMiddle < T > {
public:
using WrapperBaseMiddle < T >::WrapperBaseMiddle;
+ /**
+ * Helper for normalisation of wrapped templated datatypes in algorithms library toolkit to the same types but with default template parameters.
+ *
+ * This method actually changes the stored object to the normalized one.
+ */
void normalize ( ) {
this->setData ( std::move ( this->getData ( ) ).normalize ( ) );
}
@@ -135,8 +245,19 @@ public:
namespace std {
+/**
+ * Helper for comparing everything that inherits from WrapperBaseBase.
+ */
template < class T >
struct compare < T, typename std::enable_if < std::is_base_of < alib::WrapperBaseBase, T >::value >::type > {
+
+ /**
+ * Compare operator that determines relation between first and second object.
+ *
+ * \returns value < 0 if first < second
+ * value == 0 if first == second
+ * value > 0 if first > second
+ */
int operator ()( const T & first, const T & second ) const {
return first.getData ( ).compare ( second.getData ( ) );
}