# HG changeset patch
# User Peter Kovacs <kpeter@inf.elte.hu>
# Date 1518907455 3600
# Sat Feb 17 23:44:15 2018 +0100
# Node ID ba6afb21b6fd147e765de15c3b197f40cd608afb
# Parent 15d7c5eadacadbf50145095312677c6837327282
API doc improvements for Path structures (#250)
diff git a/lemon/path.h b/lemon/path.h
a

b


42  42  /// A structure for representing directed path in a digraph. 
43  43  /// \tparam GR The digraph type in which the path is. 
44  44  /// 
45   /// In a sense, the path can be treated as a list of arcs. The 
46   /// LEMON path type stores just this list. As a consequence, it 
47   /// cannot enumerate the nodes of the path and the source node of 
48   /// a zero length path is undefined. 
 45  /// In a sense, a path can be treated as a list of arcs. The 
 46  /// LEMON path type simply stores this list. As a consequence, it 
 47  /// cannot enumerate the nodes in the path, and the source node of 
 48  /// a zerolength path is undefined. 
49  49  /// 
50  50  /// This implementation is a back and front insertable and erasable 
51  51  /// path type. It can be indexed in O(1) time. The front and back 
… 
… 

150  150  
151  151  /// \brief The nth arc. 
152  152  /// 
153   /// \pre \c n is in the <tt>[0..length()  1]</tt> range. 
 153  /// Gives back the nth arc. This function runs in O(1) time. 
 154  /// \pre \c n is in the range <tt>[0..length()  1]</tt>. 
154  155  const Arc& nth(int n) const { 
155  156  return n < int(head.size()) ? *(head.rbegin() + n) : 
156  157  *(tail.begin() + (n  head.size())); 
… 
… 

243  244  /// A structure for representing directed path in a digraph. 
244  245  /// \tparam GR The digraph type in which the path is. 
245  246  /// 
246   /// In a sense, the path can be treated as a list of arcs. The 
247   /// LEMON path type stores just this list. As a consequence it 
248   /// cannot enumerate the nodes in the path and the zero length paths 
249   /// cannot store the source. 
 247  /// In a sense, a path can be treated as a list of arcs. The 
 248  /// LEMON path type simply stores this list. As a consequence, it 
 249  /// cannot enumerate the nodes in the path, and the source node of 
 250  /// a zerolength path is undefined. 
250  251  /// 
251  252  /// This implementation is a just back insertable and erasable path 
252  253  /// type. It can be indexed in O(1) time. The back insertion and 
253  254  /// erasure is amortized O(1) time. This implementation is faster 
254   /// then the \c Path type because it use just one vector for the 
 255  /// than the \c Path type because it use just one vector for the 
255  256  /// arcs. 
256  257  template <typename GR> 
257  258  class SimplePath { 
… 
… 

355  356  
356  357  /// \brief The nth arc. 
357  358  /// 
358   /// \pre \c n is in the <tt>[0..length()  1]</tt> range. 
 359  /// Gives back the nth arc. This function runs in O(1) time. 
 360  /// \pre \c n is in the range <tt>[0..length()  1]</tt>. 
359  361  const Arc& nth(int n) const { 
360  362  return data[n]; 
361  363  } 
… 
… 

420  422  /// A structure for representing directed path in a digraph. 
421  423  /// \tparam GR The digraph type in which the path is. 
422  424  /// 
423   /// In a sense, the path can be treated as a list of arcs. The 
424   /// LEMON path type stores just this list. As a consequence it 
425   /// cannot enumerate the nodes in the path and the zero length paths 
426   /// cannot store the source. 
 425  /// In a sense, a path can be treated as a list of arcs. The 
 426  /// LEMON path type simply stores this list. As a consequence, it 
 427  /// cannot enumerate the nodes in the path, and the source node of 
 428  /// a zerolength path is undefined. 
427  429  /// 
428  430  /// This implementation is a back and front insertable and erasable 
429  431  /// path type. It can be indexed in O(k) time, where k is the rank 
… 
… 

546  548  /// \brief The nth arc. 
547  549  /// 
548  550  /// This function looks for the nth arc in O(n) time. 
549   /// \pre \c n is in the <tt>[0..length()  1]</tt> range. 
 551  /// \pre \c n is in the range <tt>[0..length()  1]</tt>. 
550  552  const Arc& nth(int n) const { 
551  553  Node *node = first; 
552  554  for (int i = 0; i < n; ++i) { 
… 
… 

732  734  /// starting with 
733  735  /// \c it will put into \c tpath. If \c tpath have arcs 
734  736  /// before the operation they are removed first. The time 
735   /// complexity of this function is O(1) plus the the time of emtying 
 737  /// complexity of this function is O(1) plus the time of emtying 
736  738  /// \c tpath. If \c it is \c INVALID then it just clears \c tpath 
737  739  void split(ArcIt it, ListPath& tpath) { 
738  740  tpath.clear(); 
… 
… 

773  775  /// A structure for representing directed path in a digraph. 
774  776  /// \tparam GR The digraph type in which the path is. 
775  777  /// 
776   /// In a sense, the path can be treated as a list of arcs. The 
777   /// LEMON path type stores just this list. As a consequence it 
778   /// cannot enumerate the nodes in the path and the source node of 
779   /// a zero length path is undefined. 
 778  /// In a sense, a path can be treated as a list of arcs. The 
 779  /// LEMON path type simply stores this list. As a consequence, it 
 780  /// cannot enumerate the nodes in the path, and the source node of 
 781  /// a zerolength path is undefined. 
780  782  /// 
781  783  /// This implementation is completly static, i.e. it can be copy constucted 
782  784  /// or copy assigned from another path, but otherwise it cannot be 
783  785  /// modified. 
784  786  /// 
785   /// Being the the most memory efficient path type in LEMON, 
786   /// it is intented to be 
787   /// used when you want to store a large number of paths. 
 787  /// Being the most memoryefficient path type in LEMON, it is 
 788  /// intented to be used when you want to store a large number of paths. 
788  789  template <typename GR> 
789  790  class StaticPath { 
790  791  public: 
… 
… 

885  886  
886  887  /// \brief The nth arc. 
887  888  /// 
888   /// \pre \c n is in the <tt>[0..length()  1]</tt> range. 
 889  /// Gives back the nth arc. This function runs in O(1) time. 
 890  /// \pre \c n is in the range <tt>[0..length()  1]</tt>. 
889  891  const Arc& nth(int n) const { 
890  892  return arcs[n]; 
891  893  } 
… 
… 

901  903  /// \brief Return true when the path is empty. 
902  904  int empty() const { return len == 0; } 
903  905  
904   /// \brief Erase all arcs in the digraph. 
 906  /// \brief Reset the path to an empty one. 
905  907  void clear() { 
906  908  len = 0; 
907  909  if (arcs) delete[] arcs; 
… 
… 

1091  1093  return path.empty() ? INVALID : digraph.target(path.back()); 
1092  1094  } 
1093  1095  
1094   /// \brief Class which helps to iterate through the nodes of a path 
 1096  /// \brief Class for iterating through the nodes of a path 
 1097  /// 
 1098  /// Class for iterating through the nodes of a path. 
1095  1099  /// 
1096   /// In a sense, the path can be treated as a list of arcs. The 
1097   /// LEMON path type stores only this list. As a consequence, it 
1098   /// cannot enumerate the nodes in the path and the zero length paths 
1099   /// cannot have a source node. 
 1100  /// In a sense, a path can be treated as a list of arcs. The 
 1101  /// LEMON path type simply stores this list. As a consequence, it 
 1102  /// cannot enumerate the nodes in the path, and the source node of 
 1103  /// a zerolength path is undefined. 
1100  1104  /// 
1101   /// This class implements the node iterator of a path structure. To 
1102   /// provide this feature, the underlying digraph should be passed to 
 1105  /// However, this class implements a node iterator for path structures. 
 1106  /// To provide this feature, the underlying digraph should be passed to 
1103  1107  /// the constructor of the iterator. 
1104  1108  template <typename Path> 
1105  1109  class PathNodeIt { 