From a8388cfdc47386dcb61f1b5bb9190ce382bf3f1d Mon Sep 17 00:00:00 2001 From: Syndamia Date: Sun, 8 May 2022 19:50:18 +0300 Subject: Fully documented generic classes --- src/Generic/List/List.hpp | 98 ++++++++++++++++++++++++++++++++++++++-- src/Generic/List/OrderedList.hpp | 29 ++++++++++-- 2 files changed, 117 insertions(+), 10 deletions(-) (limited to 'src/Generic/List') diff --git a/src/Generic/List/List.hpp b/src/Generic/List/List.hpp index c0ed51b..0b53033 100644 --- a/src/Generic/List/List.hpp +++ b/src/Generic/List/List.hpp @@ -1,9 +1,23 @@ #ifndef HEADER_LIST #define HEADER_LIST +/*! \file List.hpp + * \brief Stores declaration and definition of templated class List + */ + #include #include +/*! \brief Templated class that stores an array of elements in dynamic memory + * + * \warning findIndex(), contain(), read(), write(), operator<<() and operator>>() require the type to have defined a couple of functions. + * \sa findIndex() + * \sa contain() + * \sa read() + * \sa write() + * \sa operator<<() + * \sa operator>>() + */ template class List { protected: @@ -16,21 +30,33 @@ protected: void copyFrom(const List& other); public: + //! Copies all elements in given array List(const T* elements, unsigned elementsCount); - void add(T element); - void insertAt(T element, unsigned index); + //! Adds an element + void add(const T& element); + //! Inserts element at given index + void insertAt(const T& element, unsigned index); + //! Removes element at index bool removeAt(unsigned index); + //! Finds the index of element unsigned findIndex(const T& element) const; bool contain(const T& element) const; + //! Returns reference to element at index T& operator[](unsigned index); + //! Returns constant reference to element at index const T& operator[](unsigned index) const; + //! Appends elements from other list List& operator+=(const List other); + //! Reads from stream std::istream& read(std::istream& istr); + //! Writes to stream std::ostream& write(std::ostream& ostr) const; + //! Returns the length unsigned get_length() const; + //! Returns the count unsigned get_count() const; List(); @@ -42,8 +68,10 @@ public: List& operator=(List&& other); }; +//! Reads List from stream with >> operator template std::istream& operator>>(std::istream& istr, List& obj); +//! Writes List to stream with << operator template std::ostream& operator<<(std::ostream& ostr, const List& obj); @@ -84,15 +112,24 @@ List::List(const T* elements, unsigned elementsCount) { this->elements[i] = elements[i]; } +/*! + * Resizes internal array if there is no space for additional elements. + */ template -void List::add(T element) { +void List::add(const T& element) { if (length == count) resize(); elements[count++] = element; } +/*! + * If index is after the last element, the element is just added. + * Otherwise all elements after the index are shifted right and element is put in place. + * + * Resizes internal array if there is no space for additional elements. + */ template -void List::insertAt(T element, unsigned index) { +void List::insertAt(const T& element, unsigned index) { if (index >= count) { add(element); return; @@ -106,6 +143,11 @@ void List::insertAt(T element, unsigned index) { count++; } +/*! \returns Wether element could be removed + * + * If index is after that of the last element, nothing is done and false is returned. + * Otherwise elements after index are shifted right and count is reduced. + */ template bool List::removeAt(unsigned index) { if (index >= count) return false; @@ -116,6 +158,11 @@ bool List::removeAt(unsigned index) { return true; } +/*! \returns Index of element. If element isn't found, returns the count of element. + * + * \warning The function depends on the type having a function "compare" defined, which takes two elements and returns a number <0 if elem1 < elem2, >0 if elem1 > elem2, 0 if elem1 == elem2 + * \note Searching is done linearly + */ template unsigned List::findIndex(const T& element) const { unsigned ind = 0; @@ -124,6 +171,11 @@ unsigned List::findIndex(const T& element) const { return ind; } +/*! \returns Whether the element is contained in the current List + * + * \warning Function depends on findIndex(), which means the same "compare" function must be defined in the type + * \sa findIndex() + */ template bool List::contain(const T& element) const { return findIndex(element) < count; @@ -146,6 +198,15 @@ List& List::operator+=(const List other) { return *this; } +/*! \param istr An input stream + * + * Directly reads bytes from stream (calls read() function). + * Any stored values are deleted and replaced with those from the stream. + * + * \warning The function depends on the type having a function "read" defined, which takes an std::istream& and writes it's data to it. Return type doesn't matter. + * \remark Doesn't alter the stream in any other way. + * \note Best used with binary ifstream + */ template std::istream& List::read(std::istream& istr) { istr.read((char*)&length, sizeof(length)); @@ -160,6 +221,14 @@ std::istream& List::read(std::istream& istr) { return istr; } +/*! \param ostr An output stream + * + * Directly writes bytes to stream (calls write() function). + * + * \warning The function depends on the type having a function "write" defined, which takes an std::ostream& and writes it's data to it. Return type doesn't matter. + * \remark Doesn't alter the stream in any other way. + * \note Best used with binary ofstream + */ template std::ostream& List::write(std::ostream& ostr) const { ostr.write((const char*)&length, sizeof(length)); @@ -171,11 +240,17 @@ std::ostream& List::write(std::ostream& ostr) const { return ostr; } +/*! + * Length is the size of the underlying array (allocated memory). + */ template unsigned List::get_length() const { return length; } +/*! + * Count is the amount of elements that are stored. + */ template unsigned List::get_count() const { return count; @@ -227,8 +302,15 @@ List& List::operator=(List&& other) { return *this; } -/* Friend functions */ +/* Outside of class */ +/*! + * Uses the stream's >> operator to read and parse the elements. + * The first item in the stream should be the count. + * + * \warning The function depends on the type having the operator >> defined, which takes an std::istream& and writes it's data to it. Return type doesn't matter. + * \note Best used with std::cin or text std::ifstream + */ template std::istream& operator>>(std::istream& istr, List& obj) { List newObj; @@ -244,6 +326,12 @@ std::istream& operator>>(std::istream& istr, List& obj) { return istr; } +/*! + * Uses the stream's << operator to write the count and then all objects. + * + * \warning The function depends on the type having the operator << defined, which takes an std::ostream& and writes it's data to it. Return type doesn't matter. + * \note Best used with std::cout or text std::ofstream + */ template std::ostream& operator<<(std::ostream& ostr, const List& obj) { ostr << obj.get_count() << std::endl; diff --git a/src/Generic/List/OrderedList.hpp b/src/Generic/List/OrderedList.hpp index 069bd4a..8d13a5d 100644 --- a/src/Generic/List/OrderedList.hpp +++ b/src/Generic/List/OrderedList.hpp @@ -1,28 +1,47 @@ #ifndef HEADER_ORDEREDLIST #define HEADER_ORDEREDLIST +/*! \file OrderedList.hpp + * \brief Stores declaration and definition of templated class OrderedList + */ + #include "List.hpp" -template +/*! \brief Inherits List, but contains it's elements in a sorted manner + * + * \warning Outside those defined in List, insert() requires the type to have defined a "compare" of functions. + * \sa insert() + */ +template class OrderedList : public List { public: OrderedList(); OrderedList(const T* elements, unsigned elementsCount); + /*! \brief \warning Function is deleted, use insert() instead + * \sa insert() + */ void add(T element) = delete; + /*! \brief \warning Function is deleted, use insert() instead + * \sa insert() + */ void insertAt(T element, unsigned index) = delete; + //! Inserts an element at a sorted position void insert(T element); - // unsigned findIndex(const T& element) const; TODO: binary search }; -template +template OrderedList::OrderedList() : OrderedList(nullptr, 0) {} -template +template OrderedList::OrderedList(const T* elements, unsigned elementsCount) : List::List(elements, elementsCount) {} -template +/*! + * \warning The function depends on the type having a function "compare" defined, which takes two elements and returns a number <0 if elem1 < elem2, >0 if elem1 > elem2, 0 if elem1 == elem2 + * \note Insertion is done linearly + */ +template void OrderedList::insert(T element) { if (List::length == List::count) List::resize(); -- cgit v1.3.1-26-gb76a