lemon-1.2: comparison lemon/path.h

equal deleted inserted replaced

-:dbe08cdf4d9a
+:cac7ce604998
 ///
 /// A structure for representing directed path in a digraph.
 /// \param Digraph The digraph type in which the path is.
 ///
 /// In a sense, the path can be treated as a list of arcs. The
-/// lemon path type stores just this list. As a consequence it
+/// lemon path type stores just this list. As a consequence, it
-/// cannot enumerate the nodes in the path and the zero length paths
+/// cannot enumerate the nodes of the path and the source node of
-/// cannot store the source.
+/// a zero length path is undefined.
 ///
 /// This implementation is a back and front insertable and erasable
 /// path type. It can be indexed in O(1) time. The front and back
-/// insertion and erasure is amortized O(1) time. The
+/// insertion and erase is done in O(1) (amortized) time. The
-/// impelementation is based on two opposite organized vectors.
+/// implementation uses two vectors for storing the front and back
+/// insertions.
 template <typename _Digraph>
 class Path {
 public:
 typedef _Digraph Digraph;
 /// Default constructor
 Path() {}
 /// \brief Template copy constructor
 ///
-/// This path can be initialized with any other path type. It just
+/// This constuctor initializes the path from any other path type.
-/// makes a copy of the given path.
+/// It simply makes a copy of the given path.
 template <typename CPath>
 Path(const CPath& cpath) {
 copyPath(*this, cpath);
 }
 /// \brief Template copy assignment
 ///
-/// This path can be initialized with any other path type. It just
+/// This operator makes a copy of a path of any other type.
-/// makes a copy of the given path.
 template <typename CPath>
 Path& operator=(const CPath& cpath) {
 copyPath(*this, cpath);
 return *this;
 }
 public:
 /// \brief Default constructor
 ArcIt() {}
 /// \brief Invalid constructor
 ArcIt(Invalid) : path(0), idx(-1) {}
-/// \brief Initializate the constructor to the first arc of path
+/// \brief Initializate the iterator to the first arc of path
 ArcIt(const Path &_path)
 : path(&_path), idx(_path.empty() ? -1 : 0) {}
 private:
 int idx;
 };
 /// \brief Length of the path.
 int length() const { return head.size() + tail.size(); }
-/// \brief Returns whether the path is empty.
+/// \brief Return whether the path is empty.
 bool empty() const { return head.empty() && tail.empty(); }
-/// \brief Resets the path to an empty path.
+/// \brief Reset the path to an empty one.
 void clear() { head.clear(); tail.clear(); }
-/// \brief Gives back the nth arc.
+/// \brief The nth arc.
 ///
 /// \pre n is in the [0..length() - 1] range
 const Arc& nth(int n) const {
 return n < int(head.size()) ? *(head.rbegin() + n) :
 *(tail.begin() + (n - head.size()));
 }
-/// \brief Initializes arc iterator to point to the nth arc
+/// \brief Initialize arc iterator to point to the nth arc
 ///
 /// \pre n is in the [0..length() - 1] range
 ArcIt nthIt(int n) const {
 return ArcIt(*this, n);
 }
-/// \brief Gives back the first arc of the path
+/// \brief The first arc of the path
 const Arc& front() const {
 return head.empty() ? tail.front() : head.back();
 }
 /// \brief Add a new arc before the current path
 std::copy(tail.begin() + halfsize + 1, tail.end(), tail.begin());
 tail.resize(tail.size() - halfsize - 1);
 }
 }
-/// \brief Gives back the last arc of the path
+/// \brief The last arc of the path
 const Arc& back() const {
 return tail.empty() ? head.front() : tail.back();
 }
 /// \brief Add a new arc behind the current path
 std::copy(head.begin() + halfsize + 1, head.end(), head.begin());
 head.resize(head.size() - halfsize - 1);
 }
 }
 typedef True BuildTag;
 template <typename CPath>
 void build(const CPath& path) {
 int len = path.length();
 int idx;
 };
 /// \brief Length of the path.
 int length() const { return data.size(); }
-/// \brief Returns whether the path is empty.
+/// \brief Return true if the path is empty.
 bool empty() const { return data.empty(); }
-/// \brief Resets the path to an empty path.
+/// \brief Reset the path to an empty one.
 void clear() { data.clear(); }
-/// \brief Gives back the nth arc.
+/// \brief The nth arc.
 ///
 /// \pre n is in the [0..length() - 1] range
 const Arc& nth(int n) const {
 return data[n];
 }
 /// \brief  Initializes arc iterator to point to the nth arc.
 ArcIt nthIt(int n) const {
 return ArcIt(*this, n);
 }
-/// \brief Gives back the first arc of the path.
+/// \brief The first arc of the path.
 const Arc& front() const {
 return data.front();
 }
-/// \brief Gives back the last arc of the path.
+/// \brief The last arc of the path.
 const Arc& back() const {
 return data.back();
 }
 /// \brief Add a new arc behind the current path.
 private:
 const ListPath *path;
 Node *node;
 };
-/// \brief Gives back the nth arc.
+/// \brief The nth arc.
 ///
-/// Gives back the nth arc in O(n) time.
+/// This function looks for the nth arc in O(n) time.
 /// \pre n is in the [0..length() - 1] range
 const Arc& nth(int n) const {
 Node *node = first;
 for (int i = 0; i < n; ++i) {
 node = node->next;
 ++len;
 }
 return len;
 }
-/// \brief Returns whether the path is empty.
+/// \brief Return true if the path is empty.
 bool empty() const { return first == 0; }
-/// \brief Resets the path to an empty path.
+/// \brief Reset the path to an empty one.
 void clear() {
 while (first != 0) {
 last = first->next;
 alloc.destroy(first);
 alloc.deallocate(first, 1);
 first = last;
 }
 }
-/// \brief Gives back the first arc of the path
+/// \brief The first arc of the path
 const Arc& front() const {
 return first->arc;
 }
 /// \brief Add a new arc before the current path
 }
 alloc.destroy(node);
 alloc.deallocate(node, 1);
 }
-/// \brief Gives back the last arc of the path.
+/// \brief The last arc of the path.
 const Arc& back() const {
 return last->arc;
 }
 /// \brief Add a new arc behind the current path.
 }
 alloc.destroy(node);
 alloc.deallocate(node, 1);
 }
-/// \brief Splicing the given path to the current path.
+/// \brief Splice a path to the back of the current path.
 ///
-/// It splices the \c tpath to the back of the current path and \c
+/// It splices \c tpath to the back of the current path and \c
 /// tpath becomes empty. The time complexity of this function is
 /// O(1).
 void spliceBack(ListPath& tpath) {
 if (first) {
 if (tpath.first) {
 last = tpath.last;
 }
 tpath.first = tpath.last = 0;
 }
-/// \brief Splicing the given path to the current path.
+/// \brief Splice a path to the front of the current path.
 ///
-/// It splices the \c tpath before the current path and \c tpath
+/// It splices \c tpath before the current path and \c tpath
 /// becomes empty. The time complexity of this function
 /// is O(1).
 void spliceFront(ListPath& tpath) {
 if (first) {
 if (tpath.first) {
 last = tpath.last;
 }
 tpath.first = tpath.last = 0;
 }
-/// \brief Splicing the given path into the current path.
+/// \brief Splice a path into the current path.
 ///
 /// It splices the \c tpath into the current path before the
 /// position of \c it iterator and \c tpath becomes empty. The
-/// time complexity of this function is O(1). If the \c it is \c
+/// time complexity of this function is O(1). If the \c it is
-/// INVALID then it will splice behind the current path.
+/// \c INVALID then it will splice behind the current path.
 void splice(ArcIt it, ListPath& tpath) {
 if (it.node) {
 if (tpath.first) {
 tpath.first->prev = it.node->prev;
 if (it.node->prev) {
 }
 }
 tpath.first = tpath.last = 0;
 }
-/// \brief Spliting the current path.
+/// \brief Split the current path.
 ///
-/// It splits the current path into two parts. The part before \c
+/// It splits the current path into two parts. The part before
-/// it iterator will remain in the current path and the part from
+/// the iterator \c it will remain in the current path and the part
-/// the it will put into the \c tpath. If the \c tpath had arcs
+/// starting with
-/// before the operation they will be removed first.  The time
+/// \c it will put into \c tpath. If \c tpath have arcs
-/// complexity of this function is O(1) plus the clearing of \c
+/// before the operation they are removed first.  The time
-/// tpath. If the \c it is \c INVALID then it just clears \c
+/// complexity of this function is O(1) plus the the time of emtying
-/// tpath.
+/// \c tpath. If \c it is \c INVALID then it just clears \c tpath
 void split(ArcIt it, ListPath& tpath) {
 tpath.clear();
 if (it.node) {
 tpath.first = it.node;
 tpath.last = last;
 /// A structure for representing directed path in a digraph.
 /// \param Digraph The digraph type in which the path is.
 ///
 /// In a sense, the path can be treated as a list of arcs. The
 /// lemon path type stores just this list. As a consequence it
-/// cannot enumerate the nodes in the path and the zero length paths
+/// cannot enumerate the nodes in the path and the source node of
-/// cannot store the source.
+/// a zero length path is undefined.
 ///
-/// This implementation is completly static, so it cannot be
+/// This implementation is completly static, i.e. it can be copy constucted
-/// modified exclude the assign an other path. It is intented to be
+/// or copy assigned from another path, but otherwise it cannot be
-/// used when you want to store a large number of paths because it is
+/// modified.
-/// the most memory efficient path type in the lemon.
+///
+/// Being the the most memory efficient path type in LEMON,
+/// it is intented to be
+/// used when you want to store a large number of paths.
 template <typename _Digraph>
 class StaticPath {
 public:
 typedef _Digraph Digraph;
 /// Default constructor
 StaticPath() : len(0), arcs(0) {}
 /// \brief Template copy constructor
 ///
-/// This path can be initialized with any other path type. It just
+/// This path can be initialized from any other path type.
-/// makes a copy of the given path.
 template <typename CPath>
 StaticPath(const CPath& cpath) : arcs(0) {
 copyPath(*this, cpath);
 }
 if (arcs) delete[] arcs;
 }
 /// \brief Template copy assignment
 ///
-/// This path can be initialized with any other path type. It just
+/// This path can be made equal to any other path type. It simply
 /// makes a copy of the given path.
 template <typename CPath>
 StaticPath& operator=(const CPath& cpath) {
 copyPath(*this, cpath);
 return *this;
 private:
 const StaticPath *path;
 int idx;
 };
-/// \brief Gives back the nth arc.
+/// \brief The nth arc.
 ///
 /// \pre n is in the [0..length() - 1] range
 const Arc& nth(int n) const {
 return arcs[n];
 }
-/// \brief Initializes arc iterator to point to the nth arc.
+/// \brief The arc iterator pointing to the nth arc.
 ArcIt nthIt(int n) const {
 return ArcIt(*this, n);
 }
-/// \brief Gives back the length of the path.
+/// \brief The length of the path.
 int length() const { return len; }
-/// \brief Returns true when the path is empty.
+/// \brief Return true when the path is empty.
 int empty() const { return len == 0; }
-/// \break Erase all arc in the digraph.
+/// \break Erase all arcs in the digraph.
 void clear() {
 len = 0;
 if (arcs) delete[] arcs;
 arcs = 0;
 }
-/// \brief Gives back the first arc of the path.
+/// \brief The first arc of the path.
 const Arc& front() const {
 return arcs[0];
 }
-/// \brief Gives back the last arc of the path.
+/// \brief The last arc of the path.
 const Arc& back() const {
 return arcs[len - 1];
 }

changeset 97	ee1324c91288
parent 96	b55e501a90ee
child 98	c4582fc14f58