From 47b4a468523f9829ad0abd6402ee8dd34143ec25 Mon Sep 17 00:00:00 2001
From: Jan Travnicek <Jan.Travnicek@fit.cvut.cz>
Date: Sun, 8 Jul 2018 21:29:37 +0200
Subject: [PATCH] document map and list
---
alib2std/src/extensions/list.hpp | 141 +++++++++++++++++++++++++++++++
alib2std/src/extensions/map.hpp | 121 ++++++++++++++++++++++++++
2 files changed, 262 insertions(+)
diff --git a/alib2std/src/extensions/list.hpp b/alib2std/src/extensions/list.hpp
index b7bfe9f633..e8326f3a48 100644
--- a/alib2std/src/extensions/list.hpp
+++ b/alib2std/src/extensions/list.hpp
@@ -1,6 +1,22 @@
/*
* list.hpp
*
+ * This file is part of Algorithms library toolkit.
+ * Copyright (C) 2017 Jan Travnicek (jan.travnicek@fit.cvut.cz)
+
+ * Algorithms library toolkit is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+
+ * Algorithms library toolkit is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with Algorithms library toolkit. If not, see <http://www.gnu.org/licenses/>.
+ *
* Created on: Apr 1, 2013
* Author: Jan Travnicek
*/
@@ -18,24 +34,126 @@
namespace ext {
+/**
+ * Class extending the list class from the standard library. Original reason is to allow printing of the container with overloaded operator <<.
+ *
+ * The class mimics the behavior of the list from the standatd library.
+ *
+ * \tparam T the type of values inside the list
+ * \tparam Alloc the allocator of values of type T
+ */
template < class T, class Alloc = std::allocator < T > >
class list : public std::list < T, Alloc >, AllocFix < Alloc > {
public:
+ /**
+ * Inherit constructors of the standard list
+ */
using std::list < T, Alloc >::list;
+
+ /**
+ * Inherit operator = of the standard list
+ */
using std::list < T, Alloc >::operator =;
#ifndef __clang__
+
+ /**
+ * Default constructor needed by g++ since it is not inherited
+ */
list ( ) = default;
+ /**
+ * Copy constructor needed by g++ since it is not inherited
+ */
list ( const list & other ) = default;
+ /**
+ * Move constructor needed by g++ since it is not inherited
+ */
list ( list && other ) = default;
+ /**
+ * Copy operator = needed by g++ since it is not inherited
+ */
list & operator = ( list && other ) = default;
+ /**
+ * Move operator = needed by g++ since it is not inherited
+ */
list & operator = ( const list & other ) = default;
#endif
+
+ /**
+ * \brief
+ * Inherited behavior of begin for non-const instance.
+ *
+ * \return iterator the first element of list
+ */
+ auto begin ( ) & {
+ return std::list < T, Alloc >::begin ( );
+ }
+
+ /**
+ * \brief
+ * Inherited behavior of begin for const instance.
+ *
+ * \return const_iterator the first element of list
+ */
+ auto begin ( ) const & {
+ return std::list < T, Alloc >::begin ( );
+ }
+
+ /**
+ * \brief
+ * Inherited behavior of begin for rvalues.
+ *
+ * \return move_iterator the first element of list
+ */
+ auto begin ( ) && {
+ return make_move_iterator ( this->begin ( ) );
+ }
+
+ /**
+ * \brief
+ * Inherited behavior of end for non-const instance.
+ *
+ * \return iterator to one after the last element of list
+ */
+ auto end ( ) & {
+ return std::list < T, Alloc >::end ( );
+ }
+
+ /**
+ * \brief
+ * Inherited behavior of end for const instance.
+ *
+ * \return const_iterator to one after the last element of list
+ */
+ auto end ( ) const & {
+ return std::list < T, Alloc >::end ( );
+ }
+
+ /**
+ * \brief
+ * Inherited behavior of end for rvalues.
+ *
+ * \return move_iterator to one after the last element of list
+ */
+ auto end ( ) && {
+ return make_move_iterator ( this->end ( ) );
+ }
};
+/**
+ * Operator to print the list to the output stream.
+ *
+ * \param out the output stream
+ * \param list the list to print
+ *
+ * \tparam T the type of values inside the list
+ * \tparam Ts ... remaining unimportant template parameters of the list
+ *
+ * \return the output stream from the \p out
+ */
template< class T, class ... Ts >
std::ostream& operator<<(std::ostream& out, const ext::list<T, Ts ... >& list) {
out << "[";
@@ -51,8 +169,23 @@ std::ostream& operator<<(std::ostream& out, const ext::list<T, Ts ... >& list) {
return out;
}
+/**
+ * Specialisation of the compare structure implementing the three-way comparison
+ *
+ * \tparam T the type of values inside the list
+ * \tparam Ts ... remaining unimportant template parameters of the list
+ */
template < class T, class ... Ts >
struct compare < ext::list < T, Ts ... > > {
+
+ /**
+ * Implementation of the three-way comparison
+ *
+ * \param first the left operand of the comparison
+ * \param second the right operand of the comparison
+ *
+ * \return negative value of left < right, positive value if left > right, zero if left == right
+ */
int operator ( ) ( const ext::list < T, Ts ... > & first, const ext::list < T, Ts ... > & second) const {
if(first.size() < second.size()) return -1;
if(first.size() > second.size()) return 1;
@@ -66,6 +199,14 @@ struct compare < ext::list < T, Ts ... > > {
}
};
+/**
+ * Overload of to_string function.
+ *
+ * \param value the list to be converted to string
+ *
+ * \tparam T the type of values inside the list
+ * \tparam Ts ... remaining unimportant template parameters of the list
+ */
template < class T, class ... Ts >
std::string to_string ( const ext::list < T, Ts ... > & value ) {
std::stringstream ss;
diff --git a/alib2std/src/extensions/map.hpp b/alib2std/src/extensions/map.hpp
index 1d53f681b9..fe427ed03a 100644
--- a/alib2std/src/extensions/map.hpp
+++ b/alib2std/src/extensions/map.hpp
@@ -1,6 +1,22 @@
/*
* map.hpp
*
+ * This file is part of Algorithms library toolkit.
+ * Copyright (C) 2017 Jan Travnicek (jan.travnicek@fit.cvut.cz)
+
+ * Algorithms library toolkit is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+
+ * Algorithms library toolkit is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with Algorithms library toolkit. If not, see <http://www.gnu.org/licenses/>.
+ *
* Created on: Apr 1, 2013
* Author: Jan Travnicek
*/
@@ -21,20 +37,53 @@
namespace ext {
+/**
+ * Class extending the map class from the standard library. Original reason is to allow printing of the container with overloaded operator <<.
+ *
+ * The class mimics the behavior of the map from the standatd library.
+ *
+ * \tparam T the type of keys inside the map
+ * \tparam R the type of values inside the map
+ * \tparam Cmp the comparator type used to order keys
+ * \tparam Alloc the allocator of values of type T
+ */
template < typename T, typename R, typename Cmp = std::less < >, typename Alloc = std::allocator < std::pair < const T, R > > >
class map : public std::map < T, R, Cmp, Alloc >, AllocFix < Alloc > {
public:
+ /**
+ * Inherit constructors of the standard map
+ */
using std::map< T, R, Cmp, Alloc >::map;
+
+ /**
+ * Inherit operator = of the standard map
+ */
using std::map< T, R, Cmp, Alloc >::operator =;
#ifndef __clang__
+
+ /**
+ * Default constructor needed by g++ since it is not inherited
+ */
map ( ) = default;
+ /**
+ * Copy constructor needed by g++ since it is not inherited
+ */
map ( const map & other ) = default;
+ /**
+ * Move constructor needed by g++ since it is not inherited
+ */
map ( map && other ) = default;
+ /**
+ * Copy operator = needed by g++ since it is not inherited
+ */
map & operator = ( map && other ) = default;
+ /**
+ * Move operator = needed by g++ since it is not inherited
+ */
map & operator = ( const map & other ) = default;
#endif
using iterator = typename std::map<T, R, Cmp, Alloc>::iterator;
@@ -62,31 +111,79 @@ public:
return insert ( std::make_pair ( std::move ( key ), std::move ( value ) ) );
}*/
+ /**
+ * \brief
+ * Inherited behavior of begin for non-const instance.
+ *
+ * \return iterator the first element of map
+ */
auto begin ( ) & {
return std::map < T, R, Cmp, Alloc >::begin ( );
}
+ /**
+ * \brief
+ * Inherited behavior of begin for const instance.
+ *
+ * \return const_iterator the first element of map
+ */
auto begin ( ) const & {
return std::map < T, R, Cmp, Alloc >::begin ( );
}
+ /**
+ * \brief
+ * Inherited behavior of begin for rvalues.
+ *
+ * \return move_iterator the first element of map
+ */
auto begin ( ) && {
return make_map_move_iterator < T, R > ( this->begin ( ) );
}
+ /**
+ * \brief
+ * Inherited behavior of end for non-const instance.
+ *
+ * \return iterator to one after the last element of map
+ */
auto end ( ) & {
return std::map < T, R, Cmp, Alloc >::end ( );
}
+ /**
+ * \brief
+ * Inherited behavior of end for const instance.
+ *
+ * \return const_iterator to one after the last element of map
+ */
auto end ( ) const & {
return std::map < T, R, Cmp, Alloc >::end ( );
}
+ /**
+ * \brief
+ * Inherited behavior of end for rvalues.
+ *
+ * \return move_iterator to one after the last element of map
+ */
auto end ( ) && {
return make_map_move_iterator < T, R > ( this->end ( ) );
}
};
+/**
+ * Operator to print the map to the output stream.
+ *
+ * \param out the output stream
+ * \param map the map to print
+ *
+ * \tparam T the type of keys inside the map
+ * \tparam R the type of values inside the map
+ * \tparam Ts ... remaining unimportant template parameters of the map
+ *
+ * \return the output stream from the \p out
+ */
template< class T, class R, class ... Ts >
std::ostream& operator<<(std::ostream& out, const ext::map<T, R, Ts ... >& map) {
out << "{";
@@ -102,8 +199,24 @@ std::ostream& operator<<(std::ostream& out, const ext::map<T, R, Ts ... >& map)
return out;
}
+/**
+ * Specialisation of the compare structure implementing the three-way comparison
+ *
+ * \tparam T the type of keys inside the map
+ * \tparam R the type of values inside the map
+ * \tparam Ts ... remaining unimportant template parameters of the map
+ */
template < class T, class R, class ... Ts >
struct compare < ext::map < T, R, Ts ... > > {
+
+ /**
+ * Implementation of the three-way comparison
+ *
+ * \param first the left operand of the comparison
+ * \param second the right operand of the comparison
+ *
+ * \return negative value of left < right, positive value if left > right, zero if left == right
+ */
int operator ( ) ( const ext::map < T, R, Ts ... > & first, const ext::map < T, R, Ts ... > & second) const {
if(first.size() < second.size()) return -1;
if(first.size() > second.size()) return 1;
@@ -119,6 +232,14 @@ struct compare < ext::map < T, R, Ts ... > > {
}
};
+/**
+ * Overload of to_string function.
+ *
+ * \param value the map to be converted to string
+ *
+ * \tparam T the type of values inside the map
+ * \tparam Ts ... remaining unimportant template parameters of the map
+ */
template < class T, class R, class ... Ts >
std::string to_string ( const ext::map < T, R, Ts ... > & value ) {
std::stringstream ss;
--
GitLab