From 1243cb834e83c350dbee887d096e551406ec31e2 Mon Sep 17 00:00:00 2001 From: manuel Date: Sat, 13 Jun 2009 22:20:39 +0200 Subject: adding documentation --- ue5/array.hpp | 181 +++++++++++++++++++++++++++++++++- ue5/mean_mark.hpp | 51 +++++++++- ue5/shared_ptr.hpp | 282 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 508 insertions(+), 6 deletions(-) (limited to 'ue5') diff --git a/ue5/array.hpp b/ue5/array.hpp index 0acd37d..a78ff56 100644 --- a/ue5/array.hpp +++ b/ue5/array.hpp @@ -1,3 +1,10 @@ +/** + * @module array + * @author Guenther Neuwirth (0626638), Manuel Mausz (0728348) + * @brief Class template array + * @date 13.06.2009 + */ + #ifndef ARRAY_H #define ARRAY_H @@ -10,72 +17,208 @@ namespace Ti { + /** + * @class array + * + * Array defines a class template for storing fixed-size sequences of objects. + */ template struct array { + /** lvalue of T */ typedef T& reference; + /** constant lvalue of T */ typedef const T& const_reference; + /** iterator type whose value type is T */ typedef T* iterator; + /** constant iterator type whose value type is T */ typedef const T* const_iterator; + /** unsigned integral type */ typedef std::size_t size_type; + /* we don't suppport zero-sized arrays */ static_assert(N != 0, "array not allowed"); + /** + * @method fill + * @brief Fills container with elements of u + * @param u object to fill array with + * @return return N + * @globalvars none + * @exception none + * @pre requires CopyAssignable void fill(const T& u) + * @post none + */ void fill(const T& u) { std::fill_n(begin(), N, u); } - void swap(array & other) + /** + * @method swap + * @brief Exchanges the contents of *this and other. + * @param other object to swap with + * @return - + * @globalvars none + * @exception none + * @pre none + * @post none + */ + void swap(array& other) { std::swap_ranges(begin(), end(), other.begin()); } + /** + * @method begin + * @brief Get an iterator referring to the first element in the container + * @param - + * @return iterator referring to the first element in the container. + * @globalvars none + * @exception none + * @pre none + * @post none + */ iterator begin() { return m_data; } + /** + * @method begin + * @brief Get a constant iterator referring to the first element in the + * container + * @param - + * @return constant iterator referring to the first element in the container. + * @globalvars none + * @exception none + * @pre none + * @post none + */ const_iterator begin() const { return m_data; } + /** + * @method end + * @brief Get an iterator which is the past-the-end value for the container. + * @param - + * @return iterator which is the past-the-end value for the container + * @globalvars none + * @exception none + * @pre none + * @post none + */ iterator end() { return m_data + N; } + /** + * @method end + * @brief Get a constant iterator which is the past-the-end value for the + * container. + * @param - + * @return constant iterator which is the past-the-end value for the container + * @globalvars none + * @exception none + * @pre none + * @post none + */ const_iterator end() const { return m_data + N; } + /** + * @method size + * @brief Get number of elements in the container + * @param - + * @return return N + * @globalvars none + * @exception none + * @pre none + * @post none + */ size_type size() const { return N; } + /** + * @method max_size + * @brief Get maximal number of elements which fit into the container + * @param - + * @return return N + * @globalvars none + * @exception none + * @pre none + * @post none + */ size_type max_size() const { return N; } + /** + * @method empty + * @brief Check if container is empty + * @param - + * @return always false + * @globalvars none + * @exception none + * @pre none + * @post none + */ bool empty() const { return false; /* size() == 0 */ } + /** + * @method operator[] + * @brief operator [] + * @param n position of an element in the array + * @return reference to the element at position n in the container + * @globalvars none + * @exception none + * @pre none + * @post none + */ reference operator[](size_type n) { return m_data[n]; } + /** + * @method operator[] + * @brief operator [] + * @param n position of an element in the array + * @return constant reference to the element at position n in the container + * @globalvars none + * @exception none + * @pre none + * @post none + */ const_reference operator[](size_type n) const { return m_data[n]; } + /** + * @method at + * @brief Get reference to the element at position n + * @param n position of an element in the array + * @return reference to the element at position n in the container. + * The difference between this member function and member operator + * function operator[] is that at signals if the requested + * position is out of range by throwing an out_of_range exception. + * @globalvars none + * @exception out_of_range + * @pre none + * @post none + */ reference at(size_type n) { if (n >= N) @@ -83,6 +226,19 @@ namespace Ti return m_data[n]; } + /** + * @method at + * @brief Get constant reference to the element at position n + * @param n position of an element in the array + * @return constant reference to the element at position n in the container. + * The difference between this member function and member operator + * function operator[] is that at signals if the requested + * position is out of range by throwing an out_of_range exception. + * @globalvars none + * @exception out_of_range + * @pre none + * @post none + */ const_reference at(size_type n) const { if (n >= N) @@ -90,22 +246,41 @@ namespace Ti return m_data[n]; } + /** + * @method data + * @brief Check if container is empty + * @param - + * @return returns enclosed array + * @globalvars none + * @exception none + * @pre none + * @post none + */ T* data() { return m_data; } private: + /** enclosed array */ T m_data[N]; }; - /* std::move returns lvalue as rvalue */ + /** + * @method make_array + * @brief Get an rvalue of an empty array + * @param none + * @return rvalue of an empty array + * @globalvars none + * @exception none + * @pre none + * @post none + */ template array&& make_array() { return std::move(array()); } - } // namespace #endif diff --git a/ue5/mean_mark.hpp b/ue5/mean_mark.hpp index e07aedc..614a671 100644 --- a/ue5/mean_mark.hpp +++ b/ue5/mean_mark.hpp @@ -1,3 +1,10 @@ +/** + * @module mean_mark + * @author Guenther Neuwirth (0626638), Manuel Mausz (0728348) + * @brief Templates for mean_mark, mean_mark_student, remove_greater + * @date 13.06.2009 + */ + #ifndef MEAN_MARK_H #define MEAN_MARK_H @@ -9,7 +16,18 @@ namespace Ti { - + /** + * @method mean_mark + * @brief computes mean mark in the range [first,last) + * @param first forward iterator to the initial positions in a sequence + * @param last forward iterator to the final positions in a sequence + * @return computed mean mark + * @globalvars none + * @exception none + * @pre all objects in the sequence must have a method mark returning a type + * convertible to double + * @post none + */ template double mean_mark(Iter first, Iter last) { @@ -23,6 +41,19 @@ namespace Ti return (count == 0) ? 0 : result / count; } + /** + * @method mean_mark_student + * @brief computes mean mark of objects of type Student in the range [first,last) + * (using RTTI) + * @param first forward iterator to the initial positions in a sequence + * @param last forward iterator to the final positions in a sequence + * @return computed mean mark of objects of type Student + * @globalvars none + * @exception none + * @pre All objects in the sequence must have a method mark returning a type + * convertible to double. And type Stundent must exist + * @post none + */ template double mean_mark_student(Iter first, Iter last) { @@ -41,6 +72,23 @@ namespace Ti return (count == 0) ? 0 : result / count; } + /** + * @method remove_greater + * @brief Removes from the range [first,last) the elements with a mark greater + * than mark and returns an iterator to the new end of the range, + * which now includes only elements with a mark less than mark. + * @param first forward iterator to the initial positions in a sequence + * @param last forward iterator to the final positions in a sequence + * @param mark maximal value for mark to keep + * @return A forward iterator pointing to the new end of the sequence, + * which now includes all the elements with a mark less than mark. + * @globalvars none + * @exception none + * @pre All objects in the sequence must have a method mark returning a type + * convertible to double. + * @post This function does not alter the elements past the new end, + * which keep their old values and are still accessible. + */ template ForwardIterator remove_greater (ForwardIterator first, ForwardIterator last, int mark) { @@ -55,7 +103,6 @@ namespace Ti } return result; } - } #endif diff --git a/ue5/shared_ptr.hpp b/ue5/shared_ptr.hpp index 37989e3..7f502bd 100644 --- a/ue5/shared_ptr.hpp +++ b/ue5/shared_ptr.hpp @@ -1,3 +1,10 @@ +/** + * @module shared_ptr + * @author Guenther Neuwirth (0626638), Manuel Mausz (0728348) + * @brief Class template shared_ptr + * @date 13.06.2009 + */ + #ifndef SHARED_PTR_H #define SHARED_PTR_H @@ -8,29 +15,85 @@ namespace Ti { + /** + * @class shared_ptr + * + * The templates stores a pointer, usually obtained via new. + * shared_ptr implements semantics of shared ownership; the last remaining + * owner of the pointer is responsible for destroying the object, or + * otherwise releasing the resources associated with the stored pointer. + * A shared_ptr object is empty if it does not own a pointer. + */ template class shared_ptr { private: + /** stored pointer */ T* m_ptr; + /** reference counter */ unsigned long* m_count; public: + /** + * @method shared_ptr + * @brief Default ctor + * @param - + * @return - + * @globalvars none + * @exception none + * @pre none + * @post get() == m_count == NULL + */ shared_ptr() : m_ptr(NULL), m_count(NULL) {} + /** + * @method get + * @brief Returns pointer of enclosed object + * @param - + * @return returns the stored pointer, null pointer if *this is empty. + * @globalvars none + * @exception none + * @pre none + * @post none + */ T* get() const { return m_ptr; } + /** + * @method shared_ptr + * @brief Copy ctor. If r is empty, constructs an empty shared_ptr + * object - otherwise, constructs a shared_ptr object that + * shares ownership with r. + * @param other instance to copy from + * @return - + * @globalvars none + * @exception none + * @pre none + * @post get() == other.get() && m_count == other.m_count + */ shared_ptr(const shared_ptr& other) : m_ptr(other.m_ptr), m_count(other.m_count) { add_ref(); } + /** + * @method shared_ptr + * @brief Copy ctor. If other is empty, constructs an empty shared_ptr + * object - otherwise, constructs a shared_ptr object that + * shares ownership with other. + * @param other instance to copy from + * @return - + * @globalvars none + * @exception none + * @pre The constructor shall not participate in the overload + * resolution unless O* is implicitly convertible to T*. + * @post get() == other.get() && m_count == other.m_count + */ template shared_ptr(const shared_ptr& other) : m_ptr(other.m_ptr), m_count(other.m_count) @@ -38,7 +101,18 @@ namespace Ti add_ref(); } - /* used to construct shared_ptr with a sub-object of O */ + /** + * @method shared_ptr + * @brief Copy ctor. Constructs a shared_ptr instance that stores ptr + * and shares ownership with other. + * @param other instance to copy from + * @param ptr ptr to store + * @return - + * @globalvars none + * @exception none + * @pre none + * @post get() == p && m_count == other.m_count + */ template shared_ptr(const shared_ptr& other, T* ptr) : m_ptr(ptr), m_count(other.m_count) @@ -46,11 +120,33 @@ namespace Ti add_ref(); } + /** + * @method shared_ptr + * @brief Copy ctor. Constructs a shared_ptr object that owns the pointer p. + * @param p pointer to store + * @return - + * @globalvars none + * @exception bad_alloc if memory couldn't be optained + * @pre p shall be convertible to T*. Y shall be a complete type. The + * expression delete p shall be well formed, shall have well + * defined behavior, and shall not throw exceptions. + * @post get() == p && m_count == 1 + */ template explicit shared_ptr(O* p) : m_ptr(p), m_count(new unsigned long(1)) {} + /** + * @method operator= + * @brief operator = + * @param other object to compare with + * @return always *this + * @globalvars none + * @exception none + * @pre none + * @post none + */ shared_ptr& operator=(const shared_ptr& other) { if (*this == other) @@ -62,6 +158,16 @@ namespace Ti return *this; } + /** + * @method operator= + * @brief operator = + * @param other object to compare with + * @return always *this + * @globalvars none + * @exception none + * @pre none + * @post none + */ template shared_ptr& operator=(const shared_ptr& other) { @@ -74,39 +180,110 @@ namespace Ti return *this; } + /** + * @method ~shared_ptr + * @brief Dtor + * @param - + * @return - + * @globalvars none + * @exception none + * @pre none + * @post none + */ ~shared_ptr() { release(); } + /** + * @method operator* + * @brief operator * + * @param - + * @return returns *get() + * @globalvars none + * @exception none + * @pre get() != NULL + * @post none + */ T& operator*() const { return *m_ptr; } + /** + * @method operator-> + * @brief operator -> + * @param - + * @return returns get() + * @globalvars none + * @exception none + * @pre get() != NULL + * @post none + */ T* operator->() const { return m_ptr; } + /** + * @method swap + * @brief Exchanges the contents of *this and other. + * @param other instance to swap with + * @return - + * @globalvars none + * @exception none + * @pre none + * @post none + */ void swap(shared_ptr& other) { std::swap(m_ptr, other.m_ptr); std::swap(m_count, other.m_count); } + /** + * @method reset + * @brief Equivalent to shared_ptr().swap(*this). + * @param - + * @return - + * @globalvars none + * @exception none + * @pre none + * @post none + */ inline void reset() { shared_ptr().swap(*this); } private: + /** + * @method add_ref + * @brief Increase reference counter + * @param - + * @return - + * @globalvars none + * @exception none + * @pre m_count != NULL + * @post none + */ void add_ref() { if (m_count != NULL) ++(*m_count); } + /** + * @method release + * @brief Decrease reference counter + * if m_count == 0 free all resources + * @param - + * @return - + * @globalvars none + * @exception none + * @pre m_ptr != NULL && m_count != NULL + * @post none + */ void release() { if (m_ptr != NULL) @@ -147,48 +324,139 @@ namespace Ti friend shared_ptr shared_dynamic_cast(const shared_ptr& from); }; + /** + * @method make_shared + * @brief Creates an instance of shared_ptr containing a pointer to the + * also created instance of T(args...). + * @param args arguments for ctor of T. + * @return A shared_ptr instance that stores and owns the address of the + * newly constructed object of type T. + * @globalvars none + * @exception bad_alloc + * @pre none + * @post get() != 0 && use_count() == 1 + */ template shared_ptr make_shared(Args ... args) { return shared_ptr(new T(args ...)); } + /** + * @method operator== + * @brief operator == + * @param a object1 to compare + * @param b object2 to compare + * @return true if both objects contain the same pointer, false otherwise. + * @globalvars none + * @exception none + * @pre none + * @post none + */ template bool operator==(const shared_ptr& a, const shared_ptr& b) { return a.get() == b.get(); } + /** + * @method operator== + * @brief operator == + * @param a shared_ptr to compare + * @param b pointer to compare + * @return true if a contains pointer b, false otherwise. + * @globalvars none + * @exception none + * @pre none + * @post none + */ template bool operator==(const shared_ptr& a, const U2* b) { return a.get() == b; } + /** + * @method operator== + * @brief operator == + * @param a pointer to compare + * @param b shared_ptr to compare + * @return true if b contains pointer a, false otherwise. + * @globalvars none + * @exception none + * @pre none + * @post none + */ template bool operator==(const U1* a, const shared_ptr& b) { return a == b.get(); } + /** + * @method operator!= + * @brief operator != + * @param a shared_ptr to compare + * @param b pointer to compare + * @return true if a contains different pointer than b, false otherwise. + * @globalvars none + * @exception none + * @pre none + * @post none + */ template bool operator!=(const shared_ptr& a, const U2* b) { return a.get() != b; } + /** + * @method operator!= + * @brief operator != + * @param a pointer to compare + * @param b shared_ptr to compare + * @return true if b contains different pointer than a, false otherwise. + * @globalvars none + * @exception none + * @pre none + * @post none + */ template bool operator!=(const U1* a, const shared_ptr& b) { return a != b.get(); } + /** + * @method operator!= + * @brief operator != + * @param a object1 to compare + * @param b object2 to compare + * @return true if both objects contain different pointers, false otherwise. + * @globalvars none + * @exception none + * @pre none + * @post none + */ template bool operator!=(const shared_ptr& a, const shared_ptr& b) { return a.get() != b.get(); } + /** + * @method shared_dynamic_cast + * @brief Converts pointer from F to T by using dynamic_cast. + * @param from object to cast + * @return When dynamic_cast(from.get()) returns a nonzero value, + * a shared_ptr object that stores a copy of it and shares + * ownership with from - otherwise an empty shared_ptr object. + * @globalvars none + * @exception none + * @pre The expression shared_dynamic_cast(from.get()) shall be well + * formed and shall have well defined behavior. + * @post w.get() == dynamic_cast(from.get()), where w is the return value. + */ template shared_ptr shared_dynamic_cast(const shared_ptr& from) { @@ -203,6 +471,18 @@ namespace Ti namespace std { using namespace Ti; + + /** + * @method swap + * @brief Exchanges the contents of t1 and t2. + * @param t1 instance#1 of shared_ptr + * @param t2 instance#2 of shared_ptr + * @return - + * @globalvars none + * @exception none + * @pre none + * @post none + */ template inline void swap(shared_ptr& t1, shared_ptr& t2) { -- cgit v1.2.3