From a14193ac17be8cf781feeea182a5e56582d4e0a6 Mon Sep 17 00:00:00 2001
From: Thomas Jarosch <thomas.jarosch@intra2net.com>
Date: Mon, 4 May 2009 17:11:28 +0200
Subject: [PATCH] Added some more functions to list API. Fixed return type of size() call and made sure clear() really frees the internal memory of the list. Added doxygen documentation

---
 ftdipp/ftdi.cpp |  137 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 ftdipp/ftdi.hpp |   45 +++++++++++-------
 2 files changed, 151 insertions(+), 31 deletions(-)

diff --git a/ftdipp/ftdi.cpp b/ftdipp/ftdi.cpp
index 0a22bd5..584a04a 100644
--- a/ftdipp/ftdi.cpp
+++ b/ftdipp/ftdi.cpp
@@ -435,41 +435,152 @@ List::~List()
 {
 }
 
-int List::size()
+/**
+* Return begin iterator for accessing the contained list elements
+* @return Iterator
+*/
+List::iterator List::begin()
 {
-   return d->list.size();
+    return d->list.begin();
 }
 
-void List::push_front(const Context& element)
+/**
+* Return end iterator for accessing the contained list elements
+* @return Iterator
+*/
+List::iterator List::end()
+{
+    return d->list.end();
+}
+
+/**
+* Return begin iterator for accessing the contained list elements
+* @return Const iterator
+*/
+List::const_iterator List::begin() const
 {
-   d->list.push_front(element);
+    return d->list.begin();
 }
 
+/**
+* Return end iterator for accessing the contained list elements
+* @return Const iterator
+*/
+List::const_iterator List::end() const
+{
+    return d->list.end();
+}
 
-void List::push_back(const Context& element)
+/**
+* Return begin reverse iterator for accessing the contained list elements
+* @return Reverse iterator
+*/
+List::reverse_iterator List::rbegin()
 {
-   d->list.push_back(element);
+    return d->list.rbegin();
 }
 
+/**
+* Return end reverse iterator for accessing the contained list elements
+* @return Reverse iterator
+*/
+List::reverse_iterator List::rend()
+{
+    return d->list.rend();
+}
+
+/**
+* Return begin reverse iterator for accessing the contained list elements
+* @return Const reverse iterator
+*/
+List::const_reverse_iterator List::rbegin() const
+{
+    return d->list.rbegin();
+}
+
+/**
+* Return end reverse iterator for accessing the contained list elements
+* @return Const reverse iterator
+*/
+List::const_reverse_iterator List::rend() const
+{
+    return d->list.rend();
+
+}
+
+/**
+* Get number of elements stored in the list
+* @return Number of elements
+*/
+List::ListType::size_type List::size() const
+{
+    return d->list.size();
+}
+
+/**
+* Check if list is empty
+* @return True if empty, false otherwise
+*/
+bool List::empty() const
+{
+    return d->list.empty();
+}
+
+/**
+ * Removes all elements. Invalidates all iterators.
+ * Do it in a non-throwing way and also make
+ * sure we really free the allocated memory.
+ */
 void List::clear()
 {
-    d->list.clear();
+    ListType().swap(d->list);
 
     // Free device list
-    ftdi_list_free(&d->devlist);
-    d->devlist = 0;
+    if (d->devlist)
+    {
+        ftdi_list_free(&d->devlist);
+        d->devlist = 0;
+    }
 }
 
-std::list<Context>::iterator List::begin()
+/**
+ * Appends a copy of the element as the new last element.
+ * @param element Value to copy and append
+*/
+void List::push_back(const Context& element)
 {
-   return d->list.begin();
+    d->list.push_back(element);
 }
 
-std::list<Context>::iterator List::end()
+/**
+ * Adds a copy of the element as the new first element.
+ * @param element Value to copy and add
+*/
+void List::push_front(const Context& element)
 {
-   return d->list.end();
+    d->list.push_front(element);
 }
 
+/**
+ * Erase one element pointed by iterator
+ * @param pos Element to erase
+ * @return Position of the following element (or end())
+*/
+List::iterator List::erase(iterator pos)
+{
+    return d->list.erase(pos);
+}
+
+/**
+ * Erase a range of elements
+ * @param beg Begin of range
+ * @param end End of range
+ * @return Position of the element after the erased range (or end())
+*/
+List::iterator List::erase(iterator beg, iterator end)
+{
+    return d->list.erase(beg, end);
+}
 
 List* List::find_all(int vendor, int product)
 {
diff --git a/ftdipp/ftdi.hpp b/ftdipp/ftdi.hpp
index d56660d..d752bd6 100644
--- a/ftdipp/ftdi.hpp
+++ b/ftdipp/ftdi.hpp
@@ -172,27 +172,36 @@ public:
 
     static List* find_all(int vendor, int product);
 
-    /*! List size */
-    int size();
-
-    /*! Append element */
-    void push_back(const Context& element);    
-    void append(const Context& element)
-    { push_back(element); }
-
-    /*! Prepend element */
-    void push_front(const Context& element);
-    void prepend(const Context& element)
-    { push_front(element); }
-
-    /*! Clear list */
+    /// List type storing "Context" objects
+    typedef std::list<Context> ListType;
+    /// Iterator type for the container
+    typedef ListType::iterator iterator;
+    /// Const iterator type for the container
+    typedef ListType::const_iterator const_iterator;
+    /// Reverse iterator type for the container
+    typedef ListType::reverse_iterator reverse_iterator;
+    /// Const reverse iterator type for the container
+    typedef ListType::const_reverse_iterator const_reverse_iterator;
+
+    iterator begin();
+    iterator end();
+    const_iterator begin() const;
+    const_iterator end() const;
+
+    reverse_iterator rbegin();
+    reverse_iterator rend();
+    const_reverse_iterator rbegin() const;
+    const_reverse_iterator rend() const;
+
+    ListType::size_type size() const;
+    bool empty() const;
     void clear();
 
-    /* Iterators */
-    typedef std::list<Context>::iterator iterator;
-    std::list<Context>::iterator begin();
-    std::list<Context>::iterator end();
+    void push_back(const Context& element);
+    void push_front(const Context& element);
 
+    iterator erase(iterator pos);
+    iterator erase(iterator beg, iterator end);
 
 private:
     class Private;
-- 
1.7.1