↑ Collapse diff ↑
Ignore white space 6 line context
1
/* -*- C++ -*-
2
 *
3
 * This file is a part of LEMON, a generic C++ optimization library
4
 *
5
 * Copyright (C) 2003-2008
6
 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7
 * (Egervary Research Group on Combinatorial Optimization, EGRES).
8
 *
9
 * Permission to use, modify and distribute this software is granted
10
 * provided that this copyright notice appears in all copies. For
11
 * precise terms see the accompanying LICENSE file.
12
 *
13
 * This software is provided "AS IS" with no warranty of any kind,
14
 * express or implied, and with no claim as to its suitability for any
15
 * purpose.
16
 *
17
 */
18

	
19
#ifndef LEMON_BELLMAN_FORD_H
20
#define LEMON_BELLMAN_FORD_H
21

	
22
/// \ingroup shortest_path
23
/// \file
24
/// \brief Bellman-Ford algorithm.
25

	
26
#include <lemon/bits/path_dump.h>
27
#include <lemon/core.h>
28
#include <lemon/error.h>
29
#include <lemon/maps.h>
30
#include <lemon/path.h>
31

	
32
#include <limits>
33

	
34
namespace lemon {
35

	
36
  /// \brief Default OperationTraits for the BellmanFord algorithm class.
37
  ///  
38
  /// This operation traits class defines all computational operations
39
  /// and constants that are used in the Bellman-Ford algorithm.
40
  /// The default implementation is based on the \c numeric_limits class.
41
  /// If the numeric type does not have infinity value, then the maximum
42
  /// value is used as extremal infinity value.
43
  template <
44
    typename V, 
45
    bool has_inf = std::numeric_limits<V>::has_infinity>
46
  struct BellmanFordDefaultOperationTraits {
47
    /// \e
48
    typedef V Value;
49
    /// \brief Gives back the zero value of the type.
50
    static Value zero() {
51
      return static_cast<Value>(0);
52
    }
53
    /// \brief Gives back the positive infinity value of the type.
54
    static Value infinity() {
55
      return std::numeric_limits<Value>::infinity();
56
    }
57
    /// \brief Gives back the sum of the given two elements.
58
    static Value plus(const Value& left, const Value& right) {
59
      return left + right;
60
    }
61
    /// \brief Gives back \c true only if the first value is less than
62
    /// the second.
63
    static bool less(const Value& left, const Value& right) {
64
      return left < right;
65
    }
66
  };
67

	
68
  template <typename V>
69
  struct BellmanFordDefaultOperationTraits<V, false> {
70
    typedef V Value;
71
    static Value zero() {
72
      return static_cast<Value>(0);
73
    }
74
    static Value infinity() {
75
      return std::numeric_limits<Value>::max();
76
    }
77
    static Value plus(const Value& left, const Value& right) {
78
      if (left == infinity() || right == infinity()) return infinity();
79
      return left + right;
80
    }
81
    static bool less(const Value& left, const Value& right) {
82
      return left < right;
83
    }
84
  };
85
  
86
  /// \brief Default traits class of BellmanFord class.
87
  ///
88
  /// Default traits class of BellmanFord class.
89
  /// \param GR The type of the digraph.
90
  /// \param LEN The type of the length map.
91
  template<typename GR, typename LEN>
92
  struct BellmanFordDefaultTraits {
93
    /// The type of the digraph the algorithm runs on. 
94
    typedef GR Digraph;
95

	
96
    /// \brief The type of the map that stores the arc lengths.
97
    ///
98
    /// The type of the map that stores the arc lengths.
99
    /// It must conform to the \ref concepts::ReadMap "ReadMap" concept.
100
    typedef LEN LengthMap;
101

	
102
    /// The type of the arc lengths.
103
    typedef typename LEN::Value Value;
104

	
105
    /// \brief Operation traits for Bellman-Ford algorithm.
106
    ///
107
    /// It defines the used operations and the infinity value for the
108
    /// given \c Value type.
109
    /// \see BellmanFordDefaultOperationTraits
110
    typedef BellmanFordDefaultOperationTraits<Value> OperationTraits;
111
 
112
    /// \brief The type of the map that stores the last arcs of the 
113
    /// shortest paths.
114
    /// 
115
    /// The type of the map that stores the last
116
    /// arcs of the shortest paths.
117
    /// It must conform to the \ref concepts::WriteMap "WriteMap" concept.
118
    typedef typename GR::template NodeMap<typename GR::Arc> PredMap;
119

	
120
    /// \brief Instantiates a \c PredMap.
121
    /// 
122
    /// This function instantiates a \ref PredMap. 
123
    /// \param g is the digraph to which we would like to define the
124
    /// \ref PredMap.
125
    static PredMap *createPredMap(const GR& g) {
126
      return new PredMap(g);
127
    }
128

	
129
    /// \brief The type of the map that stores the distances of the nodes.
130
    ///
131
    /// The type of the map that stores the distances of the nodes.
132
    /// It must conform to the \ref concepts::WriteMap "WriteMap" concept.
133
    typedef typename GR::template NodeMap<typename LEN::Value> DistMap;
134

	
135
    /// \brief Instantiates a \c DistMap.
136
    ///
137
    /// This function instantiates a \ref DistMap. 
138
    /// \param g is the digraph to which we would like to define the 
139
    /// \ref DistMap.
140
    static DistMap *createDistMap(const GR& g) {
141
      return new DistMap(g);
142
    }
143

	
144
  };
145
  
146
  /// \brief %BellmanFord algorithm class.
147
  ///
148
  /// \ingroup shortest_path
149
  /// This class provides an efficient implementation of the Bellman-Ford 
150
  /// algorithm. The maximum time complexity of the algorithm is
151
  /// <tt>O(ne)</tt>.
152
  ///
153
  /// The Bellman-Ford algorithm solves the single-source shortest path
154
  /// problem when the arcs can have negative lengths, but the digraph
155
  /// should not contain directed cycles with negative total length.
156
  /// If all arc costs are non-negative, consider to use the Dijkstra
157
  /// algorithm instead, since it is more efficient.
158
  ///
159
  /// The arc lengths are passed to the algorithm using a
160
  /// \ref concepts::ReadMap "ReadMap", so it is easy to change it to any 
161
  /// kind of length. The type of the length values is determined by the
162
  /// \ref concepts::ReadMap::Value "Value" type of the length map.
163
  ///
164
  /// There is also a \ref bellmanFord() "function-type interface" for the
165
  /// Bellman-Ford algorithm, which is convenient in the simplier cases and
166
  /// it can be used easier.
167
  ///
168
  /// \tparam GR The type of the digraph the algorithm runs on.
169
  /// The default type is \ref ListDigraph.
170
  /// \tparam LEN A \ref concepts::ReadMap "readable" arc map that specifies
171
  /// the lengths of the arcs. The default map type is
172
  /// \ref concepts::Digraph::ArcMap "GR::ArcMap<int>".
173
#ifdef DOXYGEN
174
  template <typename GR, typename LEN, typename TR>
175
#else
176
  template <typename GR=ListDigraph,
177
            typename LEN=typename GR::template ArcMap<int>,
178
            typename TR=BellmanFordDefaultTraits<GR,LEN> >
179
#endif
180
  class BellmanFord {
181
  public:
182

	
183
    ///The type of the underlying digraph.
184
    typedef typename TR::Digraph Digraph;
185
    
186
    /// \brief The type of the arc lengths.
187
    typedef typename TR::LengthMap::Value Value;
188
    /// \brief The type of the map that stores the arc lengths.
189
    typedef typename TR::LengthMap LengthMap;
190
    /// \brief The type of the map that stores the last
191
    /// arcs of the shortest paths.
192
    typedef typename TR::PredMap PredMap;
193
    /// \brief The type of the map that stores the distances of the nodes.
194
    typedef typename TR::DistMap DistMap;
195
    /// The type of the paths.
196
    typedef PredMapPath<Digraph, PredMap> Path;
197
    ///\brief The \ref BellmanFordDefaultOperationTraits
198
    /// "operation traits class" of the algorithm.
199
    typedef typename TR::OperationTraits OperationTraits;
200

	
201
    ///The \ref BellmanFordDefaultTraits "traits class" of the algorithm.
202
    typedef TR Traits;
203

	
204
  private:
205

	
206
    typedef typename Digraph::Node Node;
207
    typedef typename Digraph::NodeIt NodeIt;
208
    typedef typename Digraph::Arc Arc;
209
    typedef typename Digraph::OutArcIt OutArcIt;
210

	
211
    // Pointer to the underlying digraph.
212
    const Digraph *_gr;
213
    // Pointer to the length map
214
    const LengthMap *_length;
215
    // Pointer to the map of predecessors arcs.
216
    PredMap *_pred;
217
    // Indicates if _pred is locally allocated (true) or not.
218
    bool _local_pred;
219
    // Pointer to the map of distances.
220
    DistMap *_dist;
221
    // Indicates if _dist is locally allocated (true) or not.
222
    bool _local_dist;
223

	
224
    typedef typename Digraph::template NodeMap<bool> MaskMap;
225
    MaskMap *_mask;
226

	
227
    std::vector<Node> _process;
228

	
229
    // Creates the maps if necessary.
230
    void create_maps() {
231
      if(!_pred) {
232
	_local_pred = true;
233
	_pred = Traits::createPredMap(*_gr);
234
      }
235
      if(!_dist) {
236
	_local_dist = true;
237
	_dist = Traits::createDistMap(*_gr);
238
      }
239
      _mask = new MaskMap(*_gr, false);
240
    }
241
    
242
  public :
243
 
244
    typedef BellmanFord Create;
245

	
246
    /// \name Named Template Parameters
247

	
248
    ///@{
249

	
250
    template <class T>
251
    struct SetPredMapTraits : public Traits {
252
      typedef T PredMap;
253
      static PredMap *createPredMap(const Digraph&) {
254
        LEMON_ASSERT(false, "PredMap is not initialized");
255
        return 0; // ignore warnings
256
      }
257
    };
258

	
259
    /// \brief \ref named-templ-param "Named parameter" for setting
260
    /// \c PredMap type.
261
    ///
262
    /// \ref named-templ-param "Named parameter" for setting
263
    /// \c PredMap type.
264
    /// It must conform to the \ref concepts::WriteMap "WriteMap" concept.
265
    template <class T>
266
    struct SetPredMap 
267
      : public BellmanFord< Digraph, LengthMap, SetPredMapTraits<T> > {
268
      typedef BellmanFord< Digraph, LengthMap, SetPredMapTraits<T> > Create;
269
    };
270
    
271
    template <class T>
272
    struct SetDistMapTraits : public Traits {
273
      typedef T DistMap;
274
      static DistMap *createDistMap(const Digraph&) {
275
        LEMON_ASSERT(false, "DistMap is not initialized");
276
        return 0; // ignore warnings
277
      }
278
    };
279

	
280
    /// \brief \ref named-templ-param "Named parameter" for setting
281
    /// \c DistMap type.
282
    ///
283
    /// \ref named-templ-param "Named parameter" for setting
284
    /// \c DistMap type.
285
    /// It must conform to the \ref concepts::WriteMap "WriteMap" concept.
286
    template <class T>
287
    struct SetDistMap 
288
      : public BellmanFord< Digraph, LengthMap, SetDistMapTraits<T> > {
289
      typedef BellmanFord< Digraph, LengthMap, SetDistMapTraits<T> > Create;
290
    };
291

	
292
    template <class T>
293
    struct SetOperationTraitsTraits : public Traits {
294
      typedef T OperationTraits;
295
    };
296
    
297
    /// \brief \ref named-templ-param "Named parameter" for setting 
298
    /// \c OperationTraits type.
299
    ///
300
    /// \ref named-templ-param "Named parameter" for setting
301
    /// \c OperationTraits type.
302
    /// For more information see \ref BellmanFordDefaultOperationTraits.
303
    template <class T>
304
    struct SetOperationTraits
305
      : public BellmanFord< Digraph, LengthMap, SetOperationTraitsTraits<T> > {
306
      typedef BellmanFord< Digraph, LengthMap, SetOperationTraitsTraits<T> >
307
      Create;
308
    };
309
    
310
    ///@}
311

	
312
  protected:
313
    
314
    BellmanFord() {}
315

	
316
  public:      
317
    
318
    /// \brief Constructor.
319
    ///
320
    /// Constructor.
321
    /// \param g The digraph the algorithm runs on.
322
    /// \param length The length map used by the algorithm.
323
    BellmanFord(const Digraph& g, const LengthMap& length) :
324
      _gr(&g), _length(&length),
325
      _pred(0), _local_pred(false),
326
      _dist(0), _local_dist(false), _mask(0) {}
327
    
328
    ///Destructor.
329
    ~BellmanFord() {
330
      if(_local_pred) delete _pred;
331
      if(_local_dist) delete _dist;
332
      if(_mask) delete _mask;
333
    }
334

	
335
    /// \brief Sets the length map.
336
    ///
337
    /// Sets the length map.
338
    /// \return <tt>(*this)</tt>
339
    BellmanFord &lengthMap(const LengthMap &map) {
340
      _length = &map;
341
      return *this;
342
    }
343

	
344
    /// \brief Sets the map that stores the predecessor arcs.
345
    ///
346
    /// Sets the map that stores the predecessor arcs.
347
    /// If you don't use this function before calling \ref run()
348
    /// or \ref init(), an instance will be allocated automatically.
349
    /// The destructor deallocates this automatically allocated map,
350
    /// of course.
351
    /// \return <tt>(*this)</tt>
352
    BellmanFord &predMap(PredMap &map) {
353
      if(_local_pred) {
354
	delete _pred;
355
	_local_pred=false;
356
      }
357
      _pred = &map;
358
      return *this;
359
    }
360

	
361
    /// \brief Sets the map that stores the distances of the nodes.
362
    ///
363
    /// Sets the map that stores the distances of the nodes calculated
364
    /// by the algorithm.
365
    /// If you don't use this function before calling \ref run()
366
    /// or \ref init(), an instance will be allocated automatically.
367
    /// The destructor deallocates this automatically allocated map,
368
    /// of course.
369
    /// \return <tt>(*this)</tt>
370
    BellmanFord &distMap(DistMap &map) {
371
      if(_local_dist) {
372
	delete _dist;
373
	_local_dist=false;
374
      }
375
      _dist = &map;
376
      return *this;
377
    }
378

	
379
    /// \name Execution Control
380
    /// The simplest way to execute the Bellman-Ford algorithm is to use
381
    /// one of the member functions called \ref run().\n
382
    /// If you need better control on the execution, you have to call
383
    /// \ref init() first, then you can add several source nodes
384
    /// with \ref addSource(). Finally the actual path computation can be
385
    /// performed with \ref start(), \ref checkedStart() or
386
    /// \ref limitedStart().
387

	
388
    ///@{
389

	
390
    /// \brief Initializes the internal data structures.
391
    /// 
392
    /// Initializes the internal data structures. The optional parameter
393
    /// is the initial distance of each node.
394
    void init(const Value value = OperationTraits::infinity()) {
395
      create_maps();
396
      for (NodeIt it(*_gr); it != INVALID; ++it) {
397
	_pred->set(it, INVALID);
398
	_dist->set(it, value);
399
      }
400
      _process.clear();
401
      if (OperationTraits::less(value, OperationTraits::infinity())) {
402
	for (NodeIt it(*_gr); it != INVALID; ++it) {
403
	  _process.push_back(it);
404
	  _mask->set(it, true);
405
	}
406
      }
407
    }
408
    
409
    /// \brief Adds a new source node.
410
    ///
411
    /// This function adds a new source node. The optional second parameter
412
    /// is the initial distance of the node.
413
    void addSource(Node source, Value dst = OperationTraits::zero()) {
414
      _dist->set(source, dst);
415
      if (!(*_mask)[source]) {
416
	_process.push_back(source);
417
	_mask->set(source, true);
418
      }
419
    }
420

	
421
    /// \brief Executes one round from the Bellman-Ford algorithm.
422
    ///
423
    /// If the algoritm calculated the distances in the previous round
424
    /// exactly for the paths of at most \c k arcs, then this function
425
    /// will calculate the distances exactly for the paths of at most
426
    /// <tt>k+1</tt> arcs. Performing \c k iterations using this function
427
    /// calculates the shortest path distances exactly for the paths
428
    /// consisting of at most \c k arcs.
429
    ///
430
    /// \warning The paths with limited arc number cannot be retrieved
431
    /// easily with \ref path() or \ref predArc() functions. If you also
432
    /// need the shortest paths and not only the distances, you should
433
    /// store the \ref predMap() "predecessor map" after each iteration
434
    /// and build the path manually.
435
    ///
436
    /// \return \c true when the algorithm have not found more shorter
437
    /// paths.
438
    ///
439
    /// \see ActiveIt
440
    bool processNextRound() {
441
      for (int i = 0; i < int(_process.size()); ++i) {
442
	_mask->set(_process[i], false);
443
      }
444
      std::vector<Node> nextProcess;
445
      std::vector<Value> values(_process.size());
446
      for (int i = 0; i < int(_process.size()); ++i) {
447
	values[i] = (*_dist)[_process[i]];
448
      }
449
      for (int i = 0; i < int(_process.size()); ++i) {
450
	for (OutArcIt it(*_gr, _process[i]); it != INVALID; ++it) {
451
	  Node target = _gr->target(it);
452
	  Value relaxed = OperationTraits::plus(values[i], (*_length)[it]);
453
	  if (OperationTraits::less(relaxed, (*_dist)[target])) {
454
	    _pred->set(target, it);
455
	    _dist->set(target, relaxed);
456
	    if (!(*_mask)[target]) {
457
	      _mask->set(target, true);
458
	      nextProcess.push_back(target);
459
	    }
460
	  }	  
461
	}
462
      }
463
      _process.swap(nextProcess);
464
      return _process.empty();
465
    }
466

	
467
    /// \brief Executes one weak round from the Bellman-Ford algorithm.
468
    ///
469
    /// If the algorithm calculated the distances in the previous round
470
    /// at least for the paths of at most \c k arcs, then this function
471
    /// will calculate the distances at least for the paths of at most
472
    /// <tt>k+1</tt> arcs.
473
    /// This function does not make it possible to calculate the shortest
474
    /// path distances exactly for paths consisting of at most \c k arcs,
475
    /// this is why it is called weak round.
476
    ///
477
    /// \return \c true when the algorithm have not found more shorter
478
    /// paths.
479
    ///
480
    /// \see ActiveIt
481
    bool processNextWeakRound() {
482
      for (int i = 0; i < int(_process.size()); ++i) {
483
	_mask->set(_process[i], false);
484
      }
485
      std::vector<Node> nextProcess;
486
      for (int i = 0; i < int(_process.size()); ++i) {
487
	for (OutArcIt it(*_gr, _process[i]); it != INVALID; ++it) {
488
	  Node target = _gr->target(it);
489
	  Value relaxed = 
490
	    OperationTraits::plus((*_dist)[_process[i]], (*_length)[it]);
491
	  if (OperationTraits::less(relaxed, (*_dist)[target])) {
492
	    _pred->set(target, it);
493
	    _dist->set(target, relaxed);
494
	    if (!(*_mask)[target]) {
495
	      _mask->set(target, true);
496
	      nextProcess.push_back(target);
497
	    }
498
	  }	  
499
	}
500
      }
501
      _process.swap(nextProcess);
502
      return _process.empty();
503
    }
504

	
505
    /// \brief Executes the algorithm.
506
    ///
507
    /// Executes the algorithm.
508
    ///
509
    /// This method runs the Bellman-Ford algorithm from the root node(s)
510
    /// in order to compute the shortest path to each node.
511
    ///
512
    /// The algorithm computes
513
    /// - the shortest path tree (forest),
514
    /// - the distance of each node from the root(s).
515
    ///
516
    /// \pre init() must be called and at least one root node should be
517
    /// added with addSource() before using this function.
518
    void start() {
519
      int num = countNodes(*_gr) - 1;
520
      for (int i = 0; i < num; ++i) {
521
	if (processNextWeakRound()) break;
522
      }
523
    }
524

	
525
    /// \brief Executes the algorithm and checks the negative cycles.
526
    ///
527
    /// Executes the algorithm and checks the negative cycles.
528
    ///
529
    /// This method runs the Bellman-Ford algorithm from the root node(s)
530
    /// in order to compute the shortest path to each node and also checks
531
    /// if the digraph contains cycles with negative total length.
532
    ///
533
    /// The algorithm computes 
534
    /// - the shortest path tree (forest),
535
    /// - the distance of each node from the root(s).
536
    /// 
537
    /// \return \c false if there is a negative cycle in the digraph.
538
    ///
539
    /// \pre init() must be called and at least one root node should be
540
    /// added with addSource() before using this function. 
541
    bool checkedStart() {
542
      int num = countNodes(*_gr);
543
      for (int i = 0; i < num; ++i) {
544
	if (processNextWeakRound()) return true;
545
      }
546
      return _process.empty();
547
    }
548

	
549
    /// \brief Executes the algorithm with arc number limit.
550
    ///
551
    /// Executes the algorithm with arc number limit.
552
    ///
553
    /// This method runs the Bellman-Ford algorithm from the root node(s)
554
    /// in order to compute the shortest path distance for each node
555
    /// using only the paths consisting of at most \c num arcs.
556
    ///
557
    /// The algorithm computes
558
    /// - the limited distance of each node from the root(s),
559
    /// - the predecessor arc for each node.
560
    ///
561
    /// \warning The paths with limited arc number cannot be retrieved
562
    /// easily with \ref path() or \ref predArc() functions. If you also
563
    /// need the shortest paths and not only the distances, you should
564
    /// store the \ref predMap() "predecessor map" after each iteration
565
    /// and build the path manually.
566
    ///
567
    /// \pre init() must be called and at least one root node should be
568
    /// added with addSource() before using this function. 
569
    void limitedStart(int num) {
570
      for (int i = 0; i < num; ++i) {
571
	if (processNextRound()) break;
572
      }
573
    }
574
    
575
    /// \brief Runs the algorithm from the given root node.
576
    ///    
577
    /// This method runs the Bellman-Ford algorithm from the given root
578
    /// node \c s in order to compute the shortest path to each node.
579
    ///
580
    /// The algorithm computes
581
    /// - the shortest path tree (forest),
582
    /// - the distance of each node from the root(s).
583
    ///
584
    /// \note bf.run(s) is just a shortcut of the following code.
585
    /// \code
586
    ///   bf.init();
587
    ///   bf.addSource(s);
588
    ///   bf.start();
589
    /// \endcode
590
    void run(Node s) {
591
      init();
592
      addSource(s);
593
      start();
594
    }
595
    
596
    /// \brief Runs the algorithm from the given root node with arc
597
    /// number limit.
598
    ///    
599
    /// This method runs the Bellman-Ford algorithm from the given root
600
    /// node \c s in order to compute the shortest path distance for each
601
    /// node using only the paths consisting of at most \c num arcs.
602
    ///
603
    /// The algorithm computes
604
    /// - the limited distance of each node from the root(s),
605
    /// - the predecessor arc for each node.
606
    ///
607
    /// \warning The paths with limited arc number cannot be retrieved
608
    /// easily with \ref path() or \ref predArc() functions. If you also
609
    /// need the shortest paths and not only the distances, you should
610
    /// store the \ref predMap() "predecessor map" after each iteration
611
    /// and build the path manually.
612
    ///
613
    /// \note bf.run(s, num) is just a shortcut of the following code.
614
    /// \code
615
    ///   bf.init();
616
    ///   bf.addSource(s);
617
    ///   bf.limitedStart(num);
618
    /// \endcode
619
    void run(Node s, int num) {
620
      init();
621
      addSource(s);
622
      limitedStart(num);
623
    }
624
    
625
    ///@}
626

	
627
    /// \brief LEMON iterator for getting the active nodes.
628
    ///
629
    /// This class provides a common style LEMON iterator that traverses
630
    /// the active nodes of the Bellman-Ford algorithm after the last
631
    /// phase. These nodes should be checked in the next phase to
632
    /// find augmenting arcs outgoing from them.
633
    class ActiveIt {
634
    public:
635

	
636
      /// \brief Constructor.
637
      ///
638
      /// Constructor for getting the active nodes of the given BellmanFord
639
      /// instance. 
640
      ActiveIt(const BellmanFord& algorithm) : _algorithm(&algorithm)
641
      {
642
        _index = _algorithm->_process.size() - 1;
643
      }
644

	
645
      /// \brief Invalid constructor.
646
      ///
647
      /// Invalid constructor.
648
      ActiveIt(Invalid) : _algorithm(0), _index(-1) {}
649

	
650
      /// \brief Conversion to \c Node.
651
      ///
652
      /// Conversion to \c Node.
653
      operator Node() const { 
654
        return _index >= 0 ? _algorithm->_process[_index] : INVALID;
655
      }
656

	
657
      /// \brief Increment operator.
658
      ///
659
      /// Increment operator.
660
      ActiveIt& operator++() {
661
        --_index;
662
        return *this; 
663
      }
664

	
665
      bool operator==(const ActiveIt& it) const { 
666
        return static_cast<Node>(*this) == static_cast<Node>(it); 
667
      }
668
      bool operator!=(const ActiveIt& it) const { 
669
        return static_cast<Node>(*this) != static_cast<Node>(it); 
670
      }
671
      bool operator<(const ActiveIt& it) const { 
672
        return static_cast<Node>(*this) < static_cast<Node>(it); 
673
      }
674
      
675
    private:
676
      const BellmanFord* _algorithm;
677
      int _index;
678
    };
679
    
680
    /// \name Query Functions
681
    /// The result of the Bellman-Ford algorithm can be obtained using these
682
    /// functions.\n
683
    /// Either \ref run() or \ref init() should be called before using them.
684
    
685
    ///@{
686

	
687
    /// \brief The shortest path to the given node.
688
    ///    
689
    /// Gives back the shortest path to the given node from the root(s).
690
    ///
691
    /// \warning \c t should be reached from the root(s).
692
    ///
693
    /// \pre Either \ref run() or \ref init() must be called before
694
    /// using this function.
695
    Path path(Node t) const
696
    {
697
      return Path(*_gr, *_pred, t);
698
    }
699
	  
700
    /// \brief The distance of the given node from the root(s).
701
    ///
702
    /// Returns the distance of the given node from the root(s).
703
    ///
704
    /// \warning If node \c v is not reached from the root(s), then
705
    /// the return value of this function is undefined.
706
    ///
707
    /// \pre Either \ref run() or \ref init() must be called before
708
    /// using this function.
709
    Value dist(Node v) const { return (*_dist)[v]; }
710

	
711
    /// \brief Returns the 'previous arc' of the shortest path tree for
712
    /// the given node.
713
    ///
714
    /// This function returns the 'previous arc' of the shortest path
715
    /// tree for node \c v, i.e. it returns the last arc of a
716
    /// shortest path from a root to \c v. It is \c INVALID if \c v
717
    /// is not reached from the root(s) or if \c v is a root.
718
    ///
719
    /// The shortest path tree used here is equal to the shortest path
720
    /// tree used in \ref predNode() and \predMap().
721
    ///
722
    /// \pre Either \ref run() or \ref init() must be called before
723
    /// using this function.
724
    Arc predArc(Node v) const { return (*_pred)[v]; }
725

	
726
    /// \brief Returns the 'previous node' of the shortest path tree for
727
    /// the given node.
728
    ///
729
    /// This function returns the 'previous node' of the shortest path
730
    /// tree for node \c v, i.e. it returns the last but one node of
731
    /// a shortest path from a root to \c v. It is \c INVALID if \c v
732
    /// is not reached from the root(s) or if \c v is a root.
733
    ///
734
    /// The shortest path tree used here is equal to the shortest path
735
    /// tree used in \ref predArc() and \predMap().
736
    ///
737
    /// \pre Either \ref run() or \ref init() must be called before
738
    /// using this function.
739
    Node predNode(Node v) const { 
740
      return (*_pred)[v] == INVALID ? INVALID : _gr->source((*_pred)[v]); 
741
    }
742
    
743
    /// \brief Returns a const reference to the node map that stores the
744
    /// distances of the nodes.
745
    ///
746
    /// Returns a const reference to the node map that stores the distances
747
    /// of the nodes calculated by the algorithm.
748
    ///
749
    /// \pre Either \ref run() or \ref init() must be called before
750
    /// using this function.
751
    const DistMap &distMap() const { return *_dist;}
752
 
753
    /// \brief Returns a const reference to the node map that stores the
754
    /// predecessor arcs.
755
    ///
756
    /// Returns a const reference to the node map that stores the predecessor
757
    /// arcs, which form the shortest path tree (forest).
758
    ///
759
    /// \pre Either \ref run() or \ref init() must be called before
760
    /// using this function.
761
    const PredMap &predMap() const { return *_pred; }
762
 
763
    /// \brief Checks if a node is reached from the root(s).
764
    ///
765
    /// Returns \c true if \c v is reached from the root(s).
766
    ///
767
    /// \pre Either \ref run() or \ref init() must be called before
768
    /// using this function.
769
    bool reached(Node v) const {
770
      return (*_dist)[v] != OperationTraits::infinity();
771
    }
772

	
773
    /// \brief Gives back a negative cycle.
774
    ///    
775
    /// This function gives back a directed cycle with negative total
776
    /// length if the algorithm has already found one.
777
    /// Otherwise it gives back an empty path.
778
    lemon::Path<Digraph> negativeCycle() {
779
      typename Digraph::template NodeMap<int> state(*_gr, -1);
780
      lemon::Path<Digraph> cycle;
781
      for (int i = 0; i < int(_process.size()); ++i) {
782
        if (state[_process[i]] != -1) continue;
783
        for (Node v = _process[i]; (*_pred)[v] != INVALID;
784
             v = _gr->source((*_pred)[v])) {
785
          if (state[v] == i) {
786
            cycle.addFront((*_pred)[v]);
787
            for (Node u = _gr->source((*_pred)[v]); u != v;
788
                 u = _gr->source((*_pred)[u])) {
789
              cycle.addFront((*_pred)[u]);
790
            }
791
            return cycle;
792
          }
793
          else if (state[v] >= 0) {
794
            break;
795
          }
796
          state[v] = i;
797
        }
798
      }
799
      return cycle;
800
    }
801
    
802
    ///@}
803
  };
804
 
805
  /// \brief Default traits class of bellmanFord() function.
806
  ///
807
  /// Default traits class of bellmanFord() function.
808
  /// \tparam GR The type of the digraph.
809
  /// \tparam LEN The type of the length map.
810
  template <typename GR, typename LEN>
811
  struct BellmanFordWizardDefaultTraits {
812
    /// The type of the digraph the algorithm runs on. 
813
    typedef GR Digraph;
814

	
815
    /// \brief The type of the map that stores the arc lengths.
816
    ///
817
    /// The type of the map that stores the arc lengths.
818
    /// It must meet the \ref concepts::ReadMap "ReadMap" concept.
819
    typedef LEN LengthMap;
820

	
821
    /// The type of the arc lengths.
822
    typedef typename LEN::Value Value;
823

	
824
    /// \brief Operation traits for Bellman-Ford algorithm.
825
    ///
826
    /// It defines the used operations and the infinity value for the
827
    /// given \c Value type.
828
    /// \see BellmanFordDefaultOperationTraits
829
    typedef BellmanFordDefaultOperationTraits<Value> OperationTraits;
830

	
831
    /// \brief The type of the map that stores the last
832
    /// arcs of the shortest paths.
833
    /// 
834
    /// The type of the map that stores the last arcs of the shortest paths.
835
    /// It must conform to the \ref concepts::WriteMap "WriteMap" concept.
836
    typedef typename GR::template NodeMap<typename GR::Arc> PredMap;
837

	
838
    /// \brief Instantiates a \c PredMap.
839
    /// 
840
    /// This function instantiates a \ref PredMap.
841
    /// \param g is the digraph to which we would like to define the
842
    /// \ref PredMap.
843
    static PredMap *createPredMap(const GR &g) {
844
      return new PredMap(g);
845
    }
846

	
847
    /// \brief The type of the map that stores the distances of the nodes.
848
    ///
849
    /// The type of the map that stores the distances of the nodes.
850
    /// It must conform to the \ref concepts::WriteMap "WriteMap" concept.
851
    typedef typename GR::template NodeMap<Value> DistMap;
852

	
853
    /// \brief Instantiates a \c DistMap.
854
    ///
855
    /// This function instantiates a \ref DistMap. 
856
    /// \param g is the digraph to which we would like to define the
857
    /// \ref DistMap.
858
    static DistMap *createDistMap(const GR &g) {
859
      return new DistMap(g);
860
    }
861

	
862
    ///The type of the shortest paths.
863

	
864
    ///The type of the shortest paths.
865
    ///It must meet the \ref concepts::Path "Path" concept.
866
    typedef lemon::Path<Digraph> Path;
867
  };
868
  
869
  /// \brief Default traits class used by BellmanFordWizard.
870
  ///
871
  /// Default traits class used by BellmanFordWizard.
872
  /// \tparam GR The type of the digraph.
873
  /// \tparam LEN The type of the length map.
874
  template <typename GR, typename LEN>
875
  class BellmanFordWizardBase 
876
    : public BellmanFordWizardDefaultTraits<GR, LEN> {
877

	
878
    typedef BellmanFordWizardDefaultTraits<GR, LEN> Base;
879
  protected:
880
    // Type of the nodes in the digraph.
881
    typedef typename Base::Digraph::Node Node;
882

	
883
    // Pointer to the underlying digraph.
884
    void *_graph;
885
    // Pointer to the length map
886
    void *_length;
887
    // Pointer to the map of predecessors arcs.
888
    void *_pred;
889
    // Pointer to the map of distances.
890
    void *_dist;
891
    //Pointer to the shortest path to the target node.
892
    void *_path;
893
    //Pointer to the distance of the target node.
894
    void *_di;
895

	
896
    public:
897
    /// Constructor.
898
    
899
    /// This constructor does not require parameters, it initiates
900
    /// all of the attributes to default values \c 0.
901
    BellmanFordWizardBase() :
902
      _graph(0), _length(0), _pred(0), _dist(0), _path(0), _di(0) {}
903

	
904
    /// Constructor.
905
    
906
    /// This constructor requires two parameters,
907
    /// others are initiated to \c 0.
908
    /// \param gr The digraph the algorithm runs on.
909
    /// \param len The length map.
910
    BellmanFordWizardBase(const GR& gr, 
911
			  const LEN& len) :
912
      _graph(reinterpret_cast<void*>(const_cast<GR*>(&gr))), 
913
      _length(reinterpret_cast<void*>(const_cast<LEN*>(&len))), 
914
      _pred(0), _dist(0), _path(0), _di(0) {}
915

	
916
  };
917
  
918
  /// \brief Auxiliary class for the function-type interface of the
919
  /// \ref BellmanFord "Bellman-Ford" algorithm.
920
  ///
921
  /// This auxiliary class is created to implement the
922
  /// \ref bellmanFord() "function-type interface" of the
923
  /// \ref BellmanFord "Bellman-Ford" algorithm.
924
  /// It does not have own \ref run() method, it uses the
925
  /// functions and features of the plain \ref BellmanFord.
926
  ///
927
  /// This class should only be used through the \ref bellmanFord()
928
  /// function, which makes it easier to use the algorithm.
929
  template<class TR>
930
  class BellmanFordWizard : public TR {
931
    typedef TR Base;
932

	
933
    typedef typename TR::Digraph Digraph;
934

	
935
    typedef typename Digraph::Node Node;
936
    typedef typename Digraph::NodeIt NodeIt;
937
    typedef typename Digraph::Arc Arc;
938
    typedef typename Digraph::OutArcIt ArcIt;
939
    
940
    typedef typename TR::LengthMap LengthMap;
941
    typedef typename LengthMap::Value Value;
942
    typedef typename TR::PredMap PredMap;
943
    typedef typename TR::DistMap DistMap;
944
    typedef typename TR::Path Path;
945

	
946
  public:
947
    /// Constructor.
948
    BellmanFordWizard() : TR() {}
949

	
950
    /// \brief Constructor that requires parameters.
951
    ///
952
    /// Constructor that requires parameters.
953
    /// These parameters will be the default values for the traits class.
954
    /// \param gr The digraph the algorithm runs on.
955
    /// \param len The length map.
956
    BellmanFordWizard(const Digraph& gr, const LengthMap& len) 
957
      : TR(gr, len) {}
958

	
959
    /// \brief Copy constructor
960
    BellmanFordWizard(const TR &b) : TR(b) {}
961

	
962
    ~BellmanFordWizard() {}
963

	
964
    /// \brief Runs the Bellman-Ford algorithm from the given source node.
965
    ///    
966
    /// This method runs the Bellman-Ford algorithm from the given source
967
    /// node in order to compute the shortest path to each node.
968
    void run(Node s) {
969
      BellmanFord<Digraph,LengthMap,TR> 
970
	bf(*reinterpret_cast<const Digraph*>(Base::_graph), 
971
           *reinterpret_cast<const LengthMap*>(Base::_length));
972
      if (Base::_pred) bf.predMap(*reinterpret_cast<PredMap*>(Base::_pred));
973
      if (Base::_dist) bf.distMap(*reinterpret_cast<DistMap*>(Base::_dist));
974
      bf.run(s);
975
    }
976

	
977
    /// \brief Runs the Bellman-Ford algorithm to find the shortest path
978
    /// between \c s and \c t.
979
    ///
980
    /// This method runs the Bellman-Ford algorithm from node \c s
981
    /// in order to compute the shortest path to node \c t.
982
    /// Actually, it computes the shortest path to each node, but using
983
    /// this function you can retrieve the distance and the shortest path
984
    /// for a single target node easier.
985
    ///
986
    /// \return \c true if \c t is reachable form \c s.
987
    bool run(Node s, Node t) {
988
      BellmanFord<Digraph,LengthMap,TR>
989
        bf(*reinterpret_cast<const Digraph*>(Base::_graph),
990
           *reinterpret_cast<const LengthMap*>(Base::_length));
991
      if (Base::_pred) bf.predMap(*reinterpret_cast<PredMap*>(Base::_pred));
992
      if (Base::_dist) bf.distMap(*reinterpret_cast<DistMap*>(Base::_dist));
993
      bf.run(s);
994
      if (Base::_path) *reinterpret_cast<Path*>(Base::_path) = bf.path(t);
995
      if (Base::_di) *reinterpret_cast<Value*>(Base::_di) = bf.dist(t);
996
      return bf.reached(t);
997
    }
998

	
999
    template<class T>
1000
    struct SetPredMapBase : public Base {
1001
      typedef T PredMap;
1002
      static PredMap *createPredMap(const Digraph &) { return 0; };
1003
      SetPredMapBase(const TR &b) : TR(b) {}
1004
    };
1005
    
1006
    /// \brief \ref named-templ-param "Named parameter" for setting
1007
    /// the predecessor map.
1008
    ///
1009
    /// \ref named-templ-param "Named parameter" for setting
1010
    /// the map that stores the predecessor arcs of the nodes.
1011
    template<class T>
1012
    BellmanFordWizard<SetPredMapBase<T> > predMap(const T &t) {
1013
      Base::_pred=reinterpret_cast<void*>(const_cast<T*>(&t));
1014
      return BellmanFordWizard<SetPredMapBase<T> >(*this);
1015
    }
1016
    
1017
    template<class T>
1018
    struct SetDistMapBase : public Base {
1019
      typedef T DistMap;
1020
      static DistMap *createDistMap(const Digraph &) { return 0; };
1021
      SetDistMapBase(const TR &b) : TR(b) {}
1022
    };
1023
    
1024
    /// \brief \ref named-templ-param "Named parameter" for setting
1025
    /// the distance map.
1026
    ///
1027
    /// \ref named-templ-param "Named parameter" for setting
1028
    /// the map that stores the distances of the nodes calculated
1029
    /// by the algorithm.
1030
    template<class T>
1031
    BellmanFordWizard<SetDistMapBase<T> > distMap(const T &t) {
1032
      Base::_dist=reinterpret_cast<void*>(const_cast<T*>(&t));
1033
      return BellmanFordWizard<SetDistMapBase<T> >(*this);
1034
    }
1035

	
1036
    template<class T>
1037
    struct SetPathBase : public Base {
1038
      typedef T Path;
1039
      SetPathBase(const TR &b) : TR(b) {}
1040
    };
1041

	
1042
    /// \brief \ref named-func-param "Named parameter" for getting
1043
    /// the shortest path to the target node.
1044
    ///
1045
    /// \ref named-func-param "Named parameter" for getting
1046
    /// the shortest path to the target node.
1047
    template<class T>
1048
    BellmanFordWizard<SetPathBase<T> > path(const T &t)
1049
    {
1050
      Base::_path=reinterpret_cast<void*>(const_cast<T*>(&t));
1051
      return BellmanFordWizard<SetPathBase<T> >(*this);
1052
    }
1053

	
1054
    /// \brief \ref named-func-param "Named parameter" for getting
1055
    /// the distance of the target node.
1056
    ///
1057
    /// \ref named-func-param "Named parameter" for getting
1058
    /// the distance of the target node.
1059
    BellmanFordWizard dist(const Value &d)
1060
    {
1061
      Base::_di=reinterpret_cast<void*>(const_cast<Value*>(&d));
1062
      return *this;
1063
    }
1064
    
1065
  };
1066
  
1067
  /// \brief Function type interface for the \ref BellmanFord "Bellman-Ford"
1068
  /// algorithm.
1069
  ///
1070
  /// \ingroup shortest_path
1071
  /// Function type interface for the \ref BellmanFord "Bellman-Ford"
1072
  /// algorithm.
1073
  ///
1074
  /// This function also has several \ref named-templ-func-param 
1075
  /// "named parameters", they are declared as the members of class 
1076
  /// \ref BellmanFordWizard.
1077
  /// The following examples show how to use these parameters.
1078
  /// \code
1079
  ///   // Compute shortest path from node s to each node
1080
  ///   bellmanFord(g,length).predMap(preds).distMap(dists).run(s);
1081
  ///
1082
  ///   // Compute shortest path from s to t
1083
  ///   bool reached = bellmanFord(g,length).path(p).dist(d).run(s,t);
1084
  /// \endcode
1085
  /// \warning Don't forget to put the \ref BellmanFordWizard::run() "run()"
1086
  /// to the end of the parameter list.
1087
  /// \sa BellmanFordWizard
1088
  /// \sa BellmanFord
1089
  template<typename GR, typename LEN>
1090
  BellmanFordWizard<BellmanFordWizardBase<GR,LEN> >
1091
  bellmanFord(const GR& digraph,
1092
	      const LEN& length)
1093
  {
1094
    return BellmanFordWizard<BellmanFordWizardBase<GR,LEN> >(digraph, length);
1095
  }
1096

	
1097
} //END OF NAMESPACE LEMON
1098

	
1099
#endif
1100

	
Ignore white space 6 line context
1
/* -*- mode: C++; indent-tabs-mode: nil; -*-
2
 *
3
 * This file is a part of LEMON, a generic C++ optimization library.
4
 *
5
 * Copyright (C) 2003-2009
6
 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7
 * (Egervary Research Group on Combinatorial Optimization, EGRES).
8
 *
9
 * Permission to use, modify and distribute this software is granted
10
 * provided that this copyright notice appears in all copies. For
11
 * precise terms see the accompanying LICENSE file.
12
 *
13
 * This software is provided "AS IS" with no warranty of any kind,
14
 * express or implied, and with no claim as to its suitability for any
15
 * purpose.
16
 *
17
 */
18

	
19
#ifndef LEMON_BINOM_HEAP_H
20
#define LEMON_BINOM_HEAP_H
21

	
22
///\file
23
///\ingroup heaps
24
///\brief Binomial Heap implementation.
25

	
26
#include <vector>
27
#include <utility>
28
#include <functional>
29
#include <lemon/math.h>
30
#include <lemon/counter.h>
31

	
32
namespace lemon {
33

	
34
  /// \ingroup heaps
35
  ///
36
  ///\brief Binomial heap data structure.
37
  ///
38
  /// This class implements the \e binomial \e heap data structure.
39
  /// It fully conforms to the \ref concepts::Heap "heap concept".
40
  ///
41
  /// The methods \ref increase() and \ref erase() are not efficient
42
  /// in a binomial heap. In case of many calls of these operations,
43
  /// it is better to use other heap structure, e.g. \ref BinHeap
44
  /// "binary heap".
45
  ///
46
  /// \tparam PR Type of the priorities of the items.
47
  /// \tparam IM A read-writable item map with \c int values, used
48
  /// internally to handle the cross references.
49
  /// \tparam CMP A functor class for comparing the priorities.
50
  /// The default is \c std::less<PR>.
51
#ifdef DOXYGEN
52
  template <typename PR, typename IM, typename CMP>
53
#else
54
  template <typename PR, typename IM, typename CMP = std::less<PR> >
55
#endif
56
  class BinomHeap {
57
  public:
58
    /// Type of the item-int map.
59
    typedef IM ItemIntMap;
60
    /// Type of the priorities.
61
    typedef PR Prio;
62
    /// Type of the items stored in the heap.
63
    typedef typename ItemIntMap::Key Item;
64
    /// Functor type for comparing the priorities.
65
    typedef CMP Compare;
66

	
67
    /// \brief Type to represent the states of the items.
68
    ///
69
    /// Each item has a state associated to it. It can be "in heap",
70
    /// "pre-heap" or "post-heap". The latter two are indifferent from the
71
    /// heap's point of view, but may be useful to the user.
72
    ///
73
    /// The item-int map must be initialized in such way that it assigns
74
    /// \c PRE_HEAP (<tt>-1</tt>) to any element to be put in the heap.
75
    enum State {
76
      IN_HEAP = 0,    ///< = 0.
77
      PRE_HEAP = -1,  ///< = -1.
78
      POST_HEAP = -2  ///< = -2.
79
    };
80

	
81
  private:
82
    class Store;
83

	
84
    std::vector<Store> _data;
85
    int _min, _head;
86
    ItemIntMap &_iim;
87
    Compare _comp;
88
    int _num_items;
89

	
90
  public:
91
    /// \brief Constructor.
92
    ///
93
    /// Constructor.
94
    /// \param map A map that assigns \c int values to the items.
95
    /// It is used internally to handle the cross references.
96
    /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
97
    explicit BinomHeap(ItemIntMap &map)
98
      : _min(0), _head(-1), _iim(map), _num_items(0) {}
99

	
100
    /// \brief Constructor.
101
    ///
102
    /// Constructor.
103
    /// \param map A map that assigns \c int values to the items.
104
    /// It is used internally to handle the cross references.
105
    /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
106
    /// \param comp The function object used for comparing the priorities.
107
    BinomHeap(ItemIntMap &map, const Compare &comp)
108
      : _min(0), _head(-1), _iim(map), _comp(comp), _num_items(0) {}
109

	
110
    /// \brief The number of items stored in the heap.
111
    ///
112
    /// This function returns the number of items stored in the heap.
113
    int size() const { return _num_items; }
114

	
115
    /// \brief Check if the heap is empty.
116
    ///
117
    /// This function returns \c true if the heap is empty.
118
    bool empty() const { return _num_items==0; }
119

	
120
    /// \brief Make the heap empty.
121
    ///
122
    /// This functon makes the heap empty.
123
    /// It does not change the cross reference map. If you want to reuse
124
    /// a heap that is not surely empty, you should first clear it and
125
    /// then you should set the cross reference map to \c PRE_HEAP
126
    /// for each item.
127
    void clear() {
128
      _data.clear(); _min=0; _num_items=0; _head=-1;
129
    }
130

	
131
    /// \brief Set the priority of an item or insert it, if it is
132
    /// not stored in the heap.
133
    ///
134
    /// This method sets the priority of the given item if it is
135
    /// already stored in the heap. Otherwise it inserts the given
136
    /// item into the heap with the given priority.
137
    /// \param item The item.
138
    /// \param value The priority.
139
    void set (const Item& item, const Prio& value) {
140
      int i=_iim[item];
141
      if ( i >= 0 && _data[i].in ) {
142
        if ( _comp(value, _data[i].prio) ) decrease(item, value);
143
        if ( _comp(_data[i].prio, value) ) increase(item, value);
144
      } else push(item, value);
145
    }
146

	
147
    /// \brief Insert an item into the heap with the given priority.
148
    ///
149
    /// This function inserts the given item into the heap with the
150
    /// given priority.
151
    /// \param item The item to insert.
152
    /// \param value The priority of the item.
153
    /// \pre \e item must not be stored in the heap.
154
    void push (const Item& item, const Prio& value) {
155
      int i=_iim[item];
156
      if ( i<0 ) {
157
        int s=_data.size();
158
        _iim.set( item,s );
159
        Store st;
160
        st.name=item;
161
        st.prio=value;
162
        _data.push_back(st);
163
        i=s;
164
      }
165
      else {
166
        _data[i].parent=_data[i].right_neighbor=_data[i].child=-1;
167
        _data[i].degree=0;
168
        _data[i].in=true;
169
        _data[i].prio=value;
170
      }
171

	
172
      if( 0==_num_items ) {
173
        _head=i;
174
        _min=i;
175
      } else {
176
        merge(i);
177
        if( _comp(_data[i].prio, _data[_min].prio) ) _min=i;
178
      }
179
      ++_num_items;
180
    }
181

	
182
    /// \brief Return the item having minimum priority.
183
    ///
184
    /// This function returns the item having minimum priority.
185
    /// \pre The heap must be non-empty.
186
    Item top() const { return _data[_min].name; }
187

	
188
    /// \brief The minimum priority.
189
    ///
190
    /// This function returns the minimum priority.
191
    /// \pre The heap must be non-empty.
192
    Prio prio() const { return _data[_min].prio; }
193

	
194
    /// \brief The priority of the given item.
195
    ///
196
    /// This function returns the priority of the given item.
197
    /// \param item The item.
198
    /// \pre \e item must be in the heap.
199
    const Prio& operator[](const Item& item) const {
200
      return _data[_iim[item]].prio;
201
    }
202

	
203
    /// \brief Remove the item having minimum priority.
204
    ///
205
    /// This function removes the item having minimum priority.
206
    /// \pre The heap must be non-empty.
207
    void pop() {
208
      _data[_min].in=false;
209

	
210
      int head_child=-1;
211
      if ( _data[_min].child!=-1 ) {
212
        int child=_data[_min].child;
213
        int neighb;
214
        while( child!=-1 ) {
215
          neighb=_data[child].right_neighbor;
216
          _data[child].parent=-1;
217
          _data[child].right_neighbor=head_child;
218
          head_child=child;
219
          child=neighb;
220
        }
221
      }
222

	
223
      if ( _data[_head].right_neighbor==-1 ) {
224
        // there was only one root
225
        _head=head_child;
226
      }
227
      else {
228
        // there were more roots
229
        if( _head!=_min )  { unlace(_min); }
230
        else { _head=_data[_head].right_neighbor; }
231
        merge(head_child);
232
      }
233
      _min=findMin();
234
      --_num_items;
235
    }
236

	
237
    /// \brief Remove the given item from the heap.
238
    ///
239
    /// This function removes the given item from the heap if it is
240
    /// already stored.
241
    /// \param item The item to delete.
242
    /// \pre \e item must be in the heap.
243
    void erase (const Item& item) {
244
      int i=_iim[item];
245
      if ( i >= 0 && _data[i].in ) {
246
        decrease( item, _data[_min].prio-1 );
247
        pop();
248
      }
249
    }
250

	
251
    /// \brief Decrease the priority of an item to the given value.
252
    ///
253
    /// This function decreases the priority of an item to the given value.
254
    /// \param item The item.
255
    /// \param value The priority.
256
    /// \pre \e item must be stored in the heap with priority at least \e value.
257
    void decrease (Item item, const Prio& value) {
258
      int i=_iim[item];
259
      int p=_data[i].parent;
260
      _data[i].prio=value;
261
      
262
      while( p!=-1 && _comp(value, _data[p].prio) ) {
263
        _data[i].name=_data[p].name;
264
        _data[i].prio=_data[p].prio;
265
        _data[p].name=item;
266
        _data[p].prio=value;
267
        _iim[_data[i].name]=i;
268
        i=p;
269
        p=_data[p].parent;
270
      }
271
      _iim[item]=i;
272
      if ( _comp(value, _data[_min].prio) ) _min=i;
273
    }
274

	
275
    /// \brief Increase the priority of an item to the given value.
276
    ///
277
    /// This function increases the priority of an item to the given value.
278
    /// \param item The item.
279
    /// \param value The priority.
280
    /// \pre \e item must be stored in the heap with priority at most \e value.
281
    void increase (Item item, const Prio& value) {
282
      erase(item);
283
      push(item, value);
284
    }
285

	
286
    /// \brief Return the state of an item.
287
    ///
288
    /// This method returns \c PRE_HEAP if the given item has never
289
    /// been in the heap, \c IN_HEAP if it is in the heap at the moment,
290
    /// and \c POST_HEAP otherwise.
291
    /// In the latter case it is possible that the item will get back
292
    /// to the heap again.
293
    /// \param item The item.
294
    State state(const Item &item) const {
295
      int i=_iim[item];
296
      if( i>=0 ) {
297
        if ( _data[i].in ) i=0;
298
        else i=-2;
299
      }
300
      return State(i);
301
    }
302

	
303
    /// \brief Set the state of an item in the heap.
304
    ///
305
    /// This function sets the state of the given item in the heap.
306
    /// It can be used to manually clear the heap when it is important
307
    /// to achive better time complexity.
308
    /// \param i The item.
309
    /// \param st The state. It should not be \c IN_HEAP.
310
    void state(const Item& i, State st) {
311
      switch (st) {
312
      case POST_HEAP:
313
      case PRE_HEAP:
314
        if (state(i) == IN_HEAP) {
315
          erase(i);
316
        }
317
        _iim[i] = st;
318
        break;
319
      case IN_HEAP:
320
        break;
321
      }
322
    }
323

	
324
  private:
325
    
326
    // Find the minimum of the roots
327
    int findMin() {
328
      if( _head!=-1 ) {
329
        int min_loc=_head, min_val=_data[_head].prio;
330
        for( int x=_data[_head].right_neighbor; x!=-1;
331
             x=_data[x].right_neighbor ) {
332
          if( _comp( _data[x].prio,min_val ) ) {
333
            min_val=_data[x].prio;
334
            min_loc=x;
335
          }
336
        }
337
        return min_loc;
338
      }
339
      else return -1;
340
    }
341

	
342
    // Merge the heap with another heap starting at the given position
343
    void merge(int a) {
344
      if( _head==-1 || a==-1 ) return;
345
      if( _data[a].right_neighbor==-1 &&
346
          _data[a].degree<=_data[_head].degree ) {
347
        _data[a].right_neighbor=_head;
348
        _head=a;
349
      } else {
350
        interleave(a);
351
      }
352
      if( _data[_head].right_neighbor==-1 ) return;
353
      
354
      int x=_head;
355
      int x_prev=-1, x_next=_data[x].right_neighbor;
356
      while( x_next!=-1 ) {
357
        if( _data[x].degree!=_data[x_next].degree ||
358
            ( _data[x_next].right_neighbor!=-1 &&
359
              _data[_data[x_next].right_neighbor].degree==_data[x].degree ) ) {
360
          x_prev=x;
361
          x=x_next;
362
        }
363
        else {
364
          if( _comp(_data[x_next].prio,_data[x].prio) ) {
365
            if( x_prev==-1 ) {
366
              _head=x_next;
367
            } else {
368
              _data[x_prev].right_neighbor=x_next;
369
            }
370
            fuse(x,x_next);
371
            x=x_next;
372
          }
373
          else {
374
            _data[x].right_neighbor=_data[x_next].right_neighbor;
375
            fuse(x_next,x);
376
          }
377
        }
378
        x_next=_data[x].right_neighbor;
379
      }
380
    }
381

	
382
    // Interleave the elements of the given list into the list of the roots
383
    void interleave(int a) {
384
      int p=_head, q=a;
385
      int curr=_data.size();
386
      _data.push_back(Store());
387
      
388
      while( p!=-1 || q!=-1 ) {
389
        if( q==-1 || ( p!=-1 && _data[p].degree<_data[q].degree ) ) {
390
          _data[curr].right_neighbor=p;
391
          curr=p;
392
          p=_data[p].right_neighbor;
393
        }
394
        else {
395
          _data[curr].right_neighbor=q;
396
          curr=q;
397
          q=_data[q].right_neighbor;
398
        }
399
      }
400
      
401
      _head=_data.back().right_neighbor;
402
      _data.pop_back();
403
    }
404

	
405
    // Lace node a under node b
406
    void fuse(int a, int b) {
407
      _data[a].parent=b;
408
      _data[a].right_neighbor=_data[b].child;
409
      _data[b].child=a;
410

	
411
      ++_data[b].degree;
412
    }
413

	
414
    // Unlace node a (if it has siblings)
415
    void unlace(int a) {
416
      int neighb=_data[a].right_neighbor;
417
      int other=_head;
418

	
419
      while( _data[other].right_neighbor!=a )
420
        other=_data[other].right_neighbor;
421
      _data[other].right_neighbor=neighb;
422
    }
423

	
424
  private:
425

	
426
    class Store {
427
      friend class BinomHeap;
428

	
429
      Item name;
430
      int parent;
431
      int right_neighbor;
432
      int child;
433
      int degree;
434
      bool in;
435
      Prio prio;
436

	
437
      Store() : parent(-1), right_neighbor(-1), child(-1), degree(0),
438
        in(true) {}
439
    };
440
  };
441

	
442
} //namespace lemon
443

	
444
#endif //LEMON_BINOM_HEAP_H
445

	
Ignore white space 6 line context
1 1
/* -*- mode: C++; indent-tabs-mode: nil; -*-
2 2
 *
3 3
 * This file is a part of LEMON, a generic C++ optimization library.
4 4
 *
5 5
 * Copyright (C) 2003-2009
6 6
 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 7
 * (Egervary Research Group on Combinatorial Optimization, EGRES).
8 8
 *
9 9
 * Permission to use, modify and distribute this software is granted
10 10
 * provided that this copyright notice appears in all copies. For
11 11
 * precise terms see the accompanying LICENSE file.
12 12
 *
13 13
 * This software is provided "AS IS" with no warranty of any kind,
14 14
 * express or implied, and with no claim as to its suitability for any
15 15
 * purpose.
16 16
 *
17 17
 */
18 18

	
19 19
namespace lemon {
20 20

	
21 21
/**
22 22
@defgroup datas Data Structures
23 23
This group contains the several data structures implemented in LEMON.
24 24
*/
25 25

	
26 26
/**
27 27
@defgroup graphs Graph Structures
28 28
@ingroup datas
29 29
\brief Graph structures implemented in LEMON.
30 30

	
31 31
The implementation of combinatorial algorithms heavily relies on
32 32
efficient graph implementations. LEMON offers data structures which are
33 33
planned to be easily used in an experimental phase of implementation studies,
34 34
and thereafter the program code can be made efficient by small modifications.
35 35

	
36 36
The most efficient implementation of diverse applications require the
37 37
usage of different physical graph implementations. These differences
38 38
appear in the size of graph we require to handle, memory or time usage
39 39
limitations or in the set of operations through which the graph can be
40 40
accessed.  LEMON provides several physical graph structures to meet
41 41
the diverging requirements of the possible users.  In order to save on
42 42
running time or on memory usage, some structures may fail to provide
43 43
some graph features like arc/edge or node deletion.
44 44

	
45 45
Alteration of standard containers need a very limited number of
46 46
operations, these together satisfy the everyday requirements.
47 47
In the case of graph structures, different operations are needed which do
48 48
not alter the physical graph, but gives another view. If some nodes or
49 49
arcs have to be hidden or the reverse oriented graph have to be used, then
50 50
this is the case. It also may happen that in a flow implementation
51 51
the residual graph can be accessed by another algorithm, or a node-set
52 52
is to be shrunk for another algorithm.
53 53
LEMON also provides a variety of graphs for these requirements called
54 54
\ref graph_adaptors "graph adaptors". Adaptors cannot be used alone but only
55 55
in conjunction with other graph representations.
56 56

	
57 57
You are free to use the graph structure that fit your requirements
58 58
the best, most graph algorithms and auxiliary data structures can be used
59 59
with any graph structure.
60 60

	
61 61
<b>See also:</b> \ref graph_concepts "Graph Structure Concepts".
62 62
*/
63 63

	
64 64
/**
65 65
@defgroup graph_adaptors Adaptor Classes for Graphs
66 66
@ingroup graphs
67 67
\brief Adaptor classes for digraphs and graphs
68 68

	
69 69
This group contains several useful adaptor classes for digraphs and graphs.
70 70

	
71 71
The main parts of LEMON are the different graph structures, generic
72 72
graph algorithms, graph concepts, which couple them, and graph
73 73
adaptors. While the previous notions are more or less clear, the
74 74
latter one needs further explanation. Graph adaptors are graph classes
75 75
which serve for considering graph structures in different ways.
76 76

	
77 77
A short example makes this much clearer.  Suppose that we have an
78 78
instance \c g of a directed graph type, say ListDigraph and an algorithm
79 79
\code
80 80
template <typename Digraph>
81 81
int algorithm(const Digraph&);
82 82
\endcode
83 83
is needed to run on the reverse oriented graph.  It may be expensive
84 84
(in time or in memory usage) to copy \c g with the reversed
85 85
arcs.  In this case, an adaptor class is used, which (according
86 86
to LEMON \ref concepts::Digraph "digraph concepts") works as a digraph.
87 87
The adaptor uses the original digraph structure and digraph operations when
88 88
methods of the reversed oriented graph are called.  This means that the adaptor
89 89
have minor memory usage, and do not perform sophisticated algorithmic
90 90
actions.  The purpose of it is to give a tool for the cases when a
91 91
graph have to be used in a specific alteration.  If this alteration is
92 92
obtained by a usual construction like filtering the node or the arc set or
93 93
considering a new orientation, then an adaptor is worthwhile to use.
94 94
To come back to the reverse oriented graph, in this situation
95 95
\code
96 96
template<typename Digraph> class ReverseDigraph;
97 97
\endcode
98 98
template class can be used. The code looks as follows
99 99
\code
100 100
ListDigraph g;
101 101
ReverseDigraph<ListDigraph> rg(g);
102 102
int result = algorithm(rg);
103 103
\endcode
104 104
During running the algorithm, the original digraph \c g is untouched.
105 105
This techniques give rise to an elegant code, and based on stable
106 106
graph adaptors, complex algorithms can be implemented easily.
107 107

	
108 108
In flow, circulation and matching problems, the residual
109 109
graph is of particular importance. Combining an adaptor implementing
110 110
this with shortest path algorithms or minimum mean cycle algorithms,
111 111
a range of weighted and cardinality optimization algorithms can be
112 112
obtained. For other examples, the interested user is referred to the
113 113
detailed documentation of particular adaptors.
114 114

	
115 115
The behavior of graph adaptors can be very different. Some of them keep
116 116
capabilities of the original graph while in other cases this would be
117 117
meaningless. This means that the concepts that they meet depend
118 118
on the graph adaptor, and the wrapped graph.
119 119
For example, if an arc of a reversed digraph is deleted, this is carried
120 120
out by deleting the corresponding arc of the original digraph, thus the
121 121
adaptor modifies the original digraph.
122 122
However in case of a residual digraph, this operation has no sense.
123 123

	
124 124
Let us stand one more example here to simplify your work.
125 125
ReverseDigraph has constructor
126 126
\code
127 127
ReverseDigraph(Digraph& digraph);
128 128
\endcode
129 129
This means that in a situation, when a <tt>const %ListDigraph&</tt>
130 130
reference to a graph is given, then it have to be instantiated with
131 131
<tt>Digraph=const %ListDigraph</tt>.
132 132
\code
133 133
int algorithm1(const ListDigraph& g) {
134 134
  ReverseDigraph<const ListDigraph> rg(g);
135 135
  return algorithm2(rg);
136 136
}
137 137
\endcode
138 138
*/
139 139

	
140 140
/**
141 141
@defgroup maps Maps
142 142
@ingroup datas
143 143
\brief Map structures implemented in LEMON.
144 144

	
145 145
This group contains the map structures implemented in LEMON.
146 146

	
147 147
LEMON provides several special purpose maps and map adaptors that e.g. combine
148 148
new maps from existing ones.
149 149

	
150 150
<b>See also:</b> \ref map_concepts "Map Concepts".
151 151
*/
152 152

	
153 153
/**
154 154
@defgroup graph_maps Graph Maps
155 155
@ingroup maps
156 156
\brief Special graph-related maps.
157 157

	
158 158
This group contains maps that are specifically designed to assign
159 159
values to the nodes and arcs/edges of graphs.
160 160

	
161 161
If you are looking for the standard graph maps (\c NodeMap, \c ArcMap,
162 162
\c EdgeMap), see the \ref graph_concepts "Graph Structure Concepts".
163 163
*/
164 164

	
165 165
/**
166 166
\defgroup map_adaptors Map Adaptors
167 167
\ingroup maps
168 168
\brief Tools to create new maps from existing ones
169 169

	
170 170
This group contains map adaptors that are used to create "implicit"
171 171
maps from other maps.
172 172

	
173 173
Most of them are \ref concepts::ReadMap "read-only maps".
174 174
They can make arithmetic and logical operations between one or two maps
175 175
(negation, shifting, addition, multiplication, logical 'and', 'or',
176 176
'not' etc.) or e.g. convert a map to another one of different Value type.
177 177

	
178 178
The typical usage of this classes is passing implicit maps to
179 179
algorithms.  If a function type algorithm is called then the function
180 180
type map adaptors can be used comfortable. For example let's see the
181 181
usage of map adaptors with the \c graphToEps() function.
182 182
\code
183 183
  Color nodeColor(int deg) {
184 184
    if (deg >= 2) {
185 185
      return Color(0.5, 0.0, 0.5);
186 186
    } else if (deg == 1) {
187 187
      return Color(1.0, 0.5, 1.0);
188 188
    } else {
189 189
      return Color(0.0, 0.0, 0.0);
190 190
    }
191 191
  }
192 192

	
193 193
  Digraph::NodeMap<int> degree_map(graph);
194 194

	
195 195
  graphToEps(graph, "graph.eps")
196 196
    .coords(coords).scaleToA4().undirected()
197 197
    .nodeColors(composeMap(functorToMap(nodeColor), degree_map))
198 198
    .run();
199 199
\endcode
200 200
The \c functorToMap() function makes an \c int to \c Color map from the
201 201
\c nodeColor() function. The \c composeMap() compose the \c degree_map
202 202
and the previously created map. The composed map is a proper function to
203 203
get the color of each node.
204 204

	
205 205
The usage with class type algorithms is little bit harder. In this
206 206
case the function type map adaptors can not be used, because the
207 207
function map adaptors give back temporary objects.
208 208
\code
209 209
  Digraph graph;
210 210

	
211 211
  typedef Digraph::ArcMap<double> DoubleArcMap;
212 212
  DoubleArcMap length(graph);
213 213
  DoubleArcMap speed(graph);
214 214

	
215 215
  typedef DivMap<DoubleArcMap, DoubleArcMap> TimeMap;
216 216
  TimeMap time(length, speed);
217 217

	
218 218
  Dijkstra<Digraph, TimeMap> dijkstra(graph, time);
219 219
  dijkstra.run(source, target);
220 220
\endcode
221 221
We have a length map and a maximum speed map on the arcs of a digraph.
222 222
The minimum time to pass the arc can be calculated as the division of
223 223
the two maps which can be done implicitly with the \c DivMap template
224 224
class. We use the implicit minimum time map as the length map of the
225 225
\c Dijkstra algorithm.
226 226
*/
227 227

	
228 228
/**
229
@defgroup matrices Matrices
230
@ingroup datas
231
\brief Two dimensional data storages implemented in LEMON.
232

	
233
This group contains two dimensional data storages implemented in LEMON.
234
*/
235

	
236
/**
237 229
@defgroup paths Path Structures
238 230
@ingroup datas
239 231
\brief %Path structures implemented in LEMON.
240 232

	
241 233
This group contains the path structures implemented in LEMON.
242 234

	
243 235
LEMON provides flexible data structures to work with paths.
244 236
All of them have similar interfaces and they can be copied easily with
245 237
assignment operators and copy constructors. This makes it easy and
246 238
efficient to have e.g. the Dijkstra algorithm to store its result in
247 239
any kind of path structure.
248 240

	
249
\sa lemon::concepts::Path
241
\sa \ref concepts::Path "Path concept"
242
*/
243

	
244
/**
245
@defgroup heaps Heap Structures
246
@ingroup datas
247
\brief %Heap structures implemented in LEMON.
248

	
249
This group contains the heap structures implemented in LEMON.
250

	
251
LEMON provides several heap classes. They are efficient implementations
252
of the abstract data type \e priority \e queue. They store items with
253
specified values called \e priorities in such a way that finding and
254
removing the item with minimum priority are efficient.
255
The basic operations are adding and erasing items, changing the priority
256
of an item, etc.
257

	
258
Heaps are crucial in several algorithms, such as Dijkstra and Prim.
259
The heap implementations have the same interface, thus any of them can be
260
used easily in such algorithms.
261

	
262
\sa \ref concepts::Heap "Heap concept"
263
*/
264

	
265
/**
266
@defgroup matrices Matrices
267
@ingroup datas
268
\brief Two dimensional data storages implemented in LEMON.
269

	
270
This group contains two dimensional data storages implemented in LEMON.
250 271
*/
251 272

	
252 273
/**
253 274
@defgroup auxdat Auxiliary Data Structures
254 275
@ingroup datas
255 276
\brief Auxiliary data structures implemented in LEMON.
256 277

	
257 278
This group contains some data structures implemented in LEMON in
258 279
order to make it easier to implement combinatorial algorithms.
259 280
*/
260 281

	
261 282
/**
283
@defgroup geomdat Geometric Data Structures
284
@ingroup auxdat
285
\brief Geometric data structures implemented in LEMON.
286

	
287
This group contains geometric data structures implemented in LEMON.
288

	
289
 - \ref lemon::dim2::Point "dim2::Point" implements a two dimensional
290
   vector with the usual operations.
291
 - \ref lemon::dim2::Box "dim2::Box" can be used to determine the
292
   rectangular bounding box of a set of \ref lemon::dim2::Point
293
   "dim2::Point"'s.
294
*/
295

	
296
/**
297
@defgroup matrices Matrices
298
@ingroup auxdat
299
\brief Two dimensional data storages implemented in LEMON.
300

	
301
This group contains two dimensional data storages implemented in LEMON.
302
*/
303

	
304
/**
262 305
@defgroup algs Algorithms
263 306
\brief This group contains the several algorithms
264 307
implemented in LEMON.
265 308

	
266 309
This group contains the several algorithms
267 310
implemented in LEMON.
268 311
*/
269 312

	
270 313
/**
271 314
@defgroup search Graph Search
272 315
@ingroup algs
273 316
\brief Common graph search algorithms.
274 317

	
275 318
This group contains the common graph search algorithms, namely
276 319
\e breadth-first \e search (BFS) and \e depth-first \e search (DFS).
277 320
*/
278 321

	
279 322
/**
280 323
@defgroup shortest_path Shortest Path Algorithms
281 324
@ingroup algs
282 325
\brief Algorithms for finding shortest paths.
283 326

	
284 327
This group contains the algorithms for finding shortest paths in digraphs.
285 328

	
286 329
 - \ref Dijkstra algorithm for finding shortest paths from a source node
287 330
   when all arc lengths are non-negative.
288 331
 - \ref BellmanFord "Bellman-Ford" algorithm for finding shortest paths
289 332
   from a source node when arc lenghts can be either positive or negative,
290 333
   but the digraph should not contain directed cycles with negative total
291 334
   length.
292 335
 - \ref FloydWarshall "Floyd-Warshall" and \ref Johnson "Johnson" algorithms
293 336
   for solving the \e all-pairs \e shortest \e paths \e problem when arc
294 337
   lenghts can be either positive or negative, but the digraph should
295 338
   not contain directed cycles with negative total length.
296 339
 - \ref Suurballe A successive shortest path algorithm for finding
297 340
   arc-disjoint paths between two nodes having minimum total length.
298 341
*/
299 342

	
300 343
/**
344
@defgroup spantree Minimum Spanning Tree Algorithms
345
@ingroup algs
346
\brief Algorithms for finding minimum cost spanning trees and arborescences.
347

	
348
This group contains the algorithms for finding minimum cost spanning
349
trees and arborescences.
350
*/
351

	
352
/**
301 353
@defgroup max_flow Maximum Flow Algorithms
302 354
@ingroup algs
303 355
\brief Algorithms for finding maximum flows.
304 356

	
305 357
This group contains the algorithms for finding maximum flows and
306 358
feasible circulations.
307 359

	
308 360
The \e maximum \e flow \e problem is to find a flow of maximum value between
309 361
a single source and a single target. Formally, there is a \f$G=(V,A)\f$
310 362
digraph, a \f$cap: A\rightarrow\mathbf{R}^+_0\f$ capacity function and
311 363
\f$s, t \in V\f$ source and target nodes.
312 364
A maximum flow is an \f$f: A\rightarrow\mathbf{R}^+_0\f$ solution of the
313 365
following optimization problem.
314 366

	
315 367
\f[ \max\sum_{sv\in A} f(sv) - \sum_{vs\in A} f(vs) \f]
316 368
\f[ \sum_{uv\in A} f(uv) = \sum_{vu\in A} f(vu)
317 369
    \quad \forall u\in V\setminus\{s,t\} \f]
318 370
\f[ 0 \leq f(uv) \leq cap(uv) \quad \forall uv\in A \f]
319 371

	
320 372
LEMON contains several algorithms for solving maximum flow problems:
321 373
- \ref EdmondsKarp Edmonds-Karp algorithm.
322 374
- \ref Preflow Goldberg-Tarjan's preflow push-relabel algorithm.
323 375
- \ref DinitzSleatorTarjan Dinitz's blocking flow algorithm with dynamic trees.
324 376
- \ref GoldbergTarjan Preflow push-relabel algorithm with dynamic trees.
325 377

	
326 378
In most cases the \ref Preflow "Preflow" algorithm provides the
327 379
fastest method for computing a maximum flow. All implementations
328 380
also provide functions to query the minimum cut, which is the dual
329 381
problem of maximum flow.
330 382

	
331 383
\ref Circulation is a preflow push-relabel algorithm implemented directly 
332 384
for finding feasible circulations, which is a somewhat different problem,
333 385
but it is strongly related to maximum flow.
334 386
For more information, see \ref Circulation.
335 387
*/
336 388

	
337 389
/**
338 390
@defgroup min_cost_flow_algs Minimum Cost Flow Algorithms
339 391
@ingroup algs
340 392

	
341 393
\brief Algorithms for finding minimum cost flows and circulations.
342 394

	
343 395
This group contains the algorithms for finding minimum cost flows and
344 396
circulations. For more information about this problem and its dual
345 397
solution see \ref min_cost_flow "Minimum Cost Flow Problem".
346 398

	
347 399
LEMON contains several algorithms for this problem.
348 400
 - \ref NetworkSimplex Primal Network Simplex algorithm with various
349 401
   pivot strategies.
350 402
 - \ref CostScaling Push-Relabel and Augment-Relabel algorithms based on
351 403
   cost scaling.
352 404
 - \ref CapacityScaling Successive Shortest %Path algorithm with optional
353 405
   capacity scaling.
354 406
 - \ref CancelAndTighten The Cancel and Tighten algorithm.
355 407
 - \ref CycleCanceling Cycle-Canceling algorithms.
356 408

	
357 409
In general NetworkSimplex is the most efficient implementation,
358 410
but in special cases other algorithms could be faster.
359 411
For example, if the total supply and/or capacities are rather small,
360 412
CapacityScaling is usually the fastest algorithm (without effective scaling).
361 413
*/
362 414

	
363 415
/**
364 416
@defgroup min_cut Minimum Cut Algorithms
365 417
@ingroup algs
366 418

	
367 419
\brief Algorithms for finding minimum cut in graphs.
368 420

	
369 421
This group contains the algorithms for finding minimum cut in graphs.
370 422

	
371 423
The \e minimum \e cut \e problem is to find a non-empty and non-complete
372 424
\f$X\f$ subset of the nodes with minimum overall capacity on
373 425
outgoing arcs. Formally, there is a \f$G=(V,A)\f$ digraph, a
374 426
\f$cap: A\rightarrow\mathbf{R}^+_0\f$ capacity function. The minimum
375 427
cut is the \f$X\f$ solution of the next optimization problem:
376 428

	
377 429
\f[ \min_{X \subset V, X\not\in \{\emptyset, V\}}
378
    \sum_{uv\in A, u\in X, v\not\in X}cap(uv) \f]
430
    \sum_{uv\in A: u\in X, v\not\in X}cap(uv) \f]
379 431

	
380 432
LEMON contains several algorithms related to minimum cut problems:
381 433

	
382 434
- \ref HaoOrlin "Hao-Orlin algorithm" for calculating minimum cut
383 435
  in directed graphs.
384 436
- \ref NagamochiIbaraki "Nagamochi-Ibaraki algorithm" for
385 437
  calculating minimum cut in undirected graphs.
386 438
- \ref GomoryHu "Gomory-Hu tree computation" for calculating
387 439
  all-pairs minimum cut in undirected graphs.
388 440

	
389 441
If you want to find minimum cut just between two distinict nodes,
390 442
see the \ref max_flow "maximum flow problem".
391 443
*/
392 444

	
393 445
/**
394
@defgroup graph_properties Connectivity and Other Graph Properties
395
@ingroup algs
396
\brief Algorithms for discovering the graph properties
397

	
398
This group contains the algorithms for discovering the graph properties
399
like connectivity, bipartiteness, euler property, simplicity etc.
400

	
401
\image html edge_biconnected_components.png
402
\image latex edge_biconnected_components.eps "bi-edge-connected components" width=\textwidth
403
*/
404

	
405
/**
406
@defgroup planar Planarity Embedding and Drawing
407
@ingroup algs
408
\brief Algorithms for planarity checking, embedding and drawing
409

	
410
This group contains the algorithms for planarity checking,
411
embedding and drawing.
412

	
413
\image html planar.png
414
\image latex planar.eps "Plane graph" width=\textwidth
415
*/
416

	
417
/**
418 446
@defgroup matching Matching Algorithms
419 447
@ingroup algs
420 448
\brief Algorithms for finding matchings in graphs and bipartite graphs.
421 449

	
422 450
This group contains the algorithms for calculating
423 451
matchings in graphs and bipartite graphs. The general matching problem is
424 452
finding a subset of the edges for which each node has at most one incident
425 453
edge.
426 454

	
427 455
There are several different algorithms for calculate matchings in
428 456
graphs.  The matching problems in bipartite graphs are generally
429 457
easier than in general graphs. The goal of the matching optimization
430 458
can be finding maximum cardinality, maximum weight or minimum cost
431 459
matching. The search can be constrained to find perfect or
432 460
maximum cardinality matching.
433 461

	
434 462
The matching algorithms implemented in LEMON:
435 463
- \ref MaxBipartiteMatching Hopcroft-Karp augmenting path algorithm
436 464
  for calculating maximum cardinality matching in bipartite graphs.
437 465
- \ref PrBipartiteMatching Push-relabel algorithm
438 466
  for calculating maximum cardinality matching in bipartite graphs.
439 467
- \ref MaxWeightedBipartiteMatching
440 468
  Successive shortest path algorithm for calculating maximum weighted
441 469
  matching and maximum weighted bipartite matching in bipartite graphs.
442 470
- \ref MinCostMaxBipartiteMatching
443 471
  Successive shortest path algorithm for calculating minimum cost maximum
444 472
  matching in bipartite graphs.
445 473
- \ref MaxMatching Edmond's blossom shrinking algorithm for calculating
446 474
  maximum cardinality matching in general graphs.
447 475
- \ref MaxWeightedMatching Edmond's blossom shrinking algorithm for calculating
448 476
  maximum weighted matching in general graphs.
449 477
- \ref MaxWeightedPerfectMatching
450 478
  Edmond's blossom shrinking algorithm for calculating maximum weighted
451 479
  perfect matching in general graphs.
452 480

	
453 481
\image html bipartite_matching.png
454 482
\image latex bipartite_matching.eps "Bipartite Matching" width=\textwidth
455 483
*/
456 484

	
457 485
/**
458
@defgroup spantree Minimum Spanning Tree Algorithms
486
@defgroup graph_properties Connectivity and Other Graph Properties
459 487
@ingroup algs
460
\brief Algorithms for finding minimum cost spanning trees and arborescences.
488
\brief Algorithms for discovering the graph properties
461 489

	
462
This group contains the algorithms for finding minimum cost spanning
463
trees and arborescences.
490
This group contains the algorithms for discovering the graph properties
491
like connectivity, bipartiteness, euler property, simplicity etc.
492

	
493
\image html connected_components.png
494
\image latex connected_components.eps "Connected components" width=\textwidth
495
*/
496

	
497
/**
498
@defgroup planar Planarity Embedding and Drawing
499
@ingroup algs
500
\brief Algorithms for planarity checking, embedding and drawing
501

	
502
This group contains the algorithms for planarity checking,
503
embedding and drawing.
504

	
505
\image html planar.png
506
\image latex planar.eps "Plane graph" width=\textwidth
507
*/
508

	
509
/**
510
@defgroup approx Approximation Algorithms
511
@ingroup algs
512
\brief Approximation algorithms.
513

	
514
This group contains the approximation and heuristic algorithms
515
implemented in LEMON.
464 516
*/
465 517

	
466 518
/**
467 519
@defgroup auxalg Auxiliary Algorithms
468 520
@ingroup algs
469 521
\brief Auxiliary algorithms implemented in LEMON.
470 522

	
471 523
This group contains some algorithms implemented in LEMON
472 524
in order to make it easier to implement complex algorithms.
473 525
*/
474 526

	
475 527
/**
476
@defgroup approx Approximation Algorithms
477
@ingroup algs
478
\brief Approximation algorithms.
479

	
480
This group contains the approximation and heuristic algorithms
481
implemented in LEMON.
482
*/
483

	
484
/**
485 528
@defgroup gen_opt_group General Optimization Tools
486 529
\brief This group contains some general optimization frameworks
487 530
implemented in LEMON.
488 531

	
489 532
This group contains some general optimization frameworks
490 533
implemented in LEMON.
491 534
*/
492 535

	
493 536
/**
494 537
@defgroup lp_group Lp and Mip Solvers
495 538
@ingroup gen_opt_group
496 539
\brief Lp and Mip solver interfaces for LEMON.
497 540

	
498 541
This group contains Lp and Mip solver interfaces for LEMON. The
499 542
various LP solvers could be used in the same manner with this
500 543
interface.
501 544
*/
502 545

	
503 546
/**
504 547
@defgroup lp_utils Tools for Lp and Mip Solvers
505 548
@ingroup lp_group
506 549
\brief Helper tools to the Lp and Mip solvers.
507 550

	
508 551
This group adds some helper tools to general optimization framework
509 552
implemented in LEMON.
510 553
*/
511 554

	
512 555
/**
513 556
@defgroup metah Metaheuristics
514 557
@ingroup gen_opt_group
515 558
\brief Metaheuristics for LEMON library.
516 559

	
517 560
This group contains some metaheuristic optimization tools.
518 561
*/
519 562

	
520 563
/**
521 564
@defgroup utils Tools and Utilities
522 565
\brief Tools and utilities for programming in LEMON
523 566

	
524 567
Tools and utilities for programming in LEMON.
525 568
*/
526 569

	
527 570
/**
528 571
@defgroup gutils Basic Graph Utilities
529 572
@ingroup utils
530 573
\brief Simple basic graph utilities.
531 574

	
532 575
This group contains some simple basic graph utilities.
533 576
*/
534 577

	
535 578
/**
536 579
@defgroup misc Miscellaneous Tools
537 580
@ingroup utils
538 581
\brief Tools for development, debugging and testing.
539 582

	
540 583
This group contains several useful tools for development,
541 584
debugging and testing.
542 585
*/
543 586

	
544 587
/**
545 588
@defgroup timecount Time Measuring and Counting
546 589
@ingroup misc
547 590
\brief Simple tools for measuring the performance of algorithms.
548 591

	
549 592
This group contains simple tools for measuring the performance
550 593
of algorithms.
551 594
*/
552 595

	
553 596
/**
554 597
@defgroup exceptions Exceptions
555 598
@ingroup utils
556 599
\brief Exceptions defined in LEMON.
557 600

	
558 601
This group contains the exceptions defined in LEMON.
559 602
*/
560 603

	
561 604
/**
562 605
@defgroup io_group Input-Output
563 606
\brief Graph Input-Output methods
564 607

	
565 608
This group contains the tools for importing and exporting graphs
566 609
and graph related data. Now it supports the \ref lgf-format
567 610
"LEMON Graph Format", the \c DIMACS format and the encapsulated
568 611
postscript (EPS) format.
569 612
*/
570 613

	
571 614
/**
572 615
@defgroup lemon_io LEMON Graph Format
573 616
@ingroup io_group
574 617
\brief Reading and writing LEMON Graph Format.
575 618

	
576 619
This group contains methods for reading and writing
577 620
\ref lgf-format "LEMON Graph Format".
578 621
*/
579 622

	
580 623
/**
581 624
@defgroup eps_io Postscript Exporting
582 625
@ingroup io_group
583 626
\brief General \c EPS drawer and graph exporter
584 627

	
585 628
This group contains general \c EPS drawing methods and special
586 629
graph exporting tools.
587 630
*/
588 631

	
589 632
/**
590
@defgroup dimacs_group DIMACS format
633
@defgroup dimacs_group DIMACS Format
591 634
@ingroup io_group
592 635
\brief Read and write files in DIMACS format
593 636

	
594 637
Tools to read a digraph from or write it to a file in DIMACS format data.
595 638
*/
596 639

	
597 640
/**
598 641
@defgroup nauty_group NAUTY Format
599 642
@ingroup io_group
600 643
\brief Read \e Nauty format
601 644

	
602 645
Tool to read graphs from \e Nauty format data.
603 646
*/
604 647

	
605 648
/**
606 649
@defgroup concept Concepts
607 650
\brief Skeleton classes and concept checking classes
608 651

	
609 652
This group contains the data/algorithm skeletons and concept checking
610 653
classes implemented in LEMON.
611 654

	
612 655
The purpose of the classes in this group is fourfold.
613 656

	
614 657
- These classes contain the documentations of the %concepts. In order
615 658
  to avoid document multiplications, an implementation of a concept
616 659
  simply refers to the corresponding concept class.
617 660

	
618 661
- These classes declare every functions, <tt>typedef</tt>s etc. an
619 662
  implementation of the %concepts should provide, however completely
620 663
  without implementations and real data structures behind the
621 664
  interface. On the other hand they should provide nothing else. All
622 665
  the algorithms working on a data structure meeting a certain concept
623 666
  should compile with these classes. (Though it will not run properly,
624 667
  of course.) In this way it is easily to check if an algorithm
625 668
  doesn't use any extra feature of a certain implementation.
626 669

	
627 670
- The concept descriptor classes also provide a <em>checker class</em>
628 671
  that makes it possible to check whether a certain implementation of a
629 672
  concept indeed provides all the required features.
630 673

	
631 674
- Finally, They can serve as a skeleton of a new implementation of a concept.
632 675
*/
633 676

	
634 677
/**
635 678
@defgroup graph_concepts Graph Structure Concepts
636 679
@ingroup concept
637 680
\brief Skeleton and concept checking classes for graph structures
638 681

	
639 682
This group contains the skeletons and concept checking classes of LEMON's
640 683
graph structures and helper classes used to implement these.
641 684
*/
642 685

	
643 686
/**
644 687
@defgroup map_concepts Map Concepts
645 688
@ingroup concept
646 689
\brief Skeleton and concept checking classes for maps
647 690

	
648 691
This group contains the skeletons and concept checking classes of maps.
649 692
*/
650 693

	
651 694
/**
695
@defgroup tools Standalone Utility Applications
696

	
697
Some utility applications are listed here.
698

	
699
The standard compilation procedure (<tt>./configure;make</tt>) will compile
700
them, as well.
701
*/
702

	
703
/**
652 704
\anchor demoprograms
653 705

	
654 706
@defgroup demos Demo Programs
655 707

	
656 708
Some demo programs are listed here. Their full source codes can be found in
657 709
the \c demo subdirectory of the source tree.
658 710

	
659 711
In order to compile them, use the <tt>make demo</tt> or the
660 712
<tt>make check</tt> commands.
661 713
*/
662 714

	
663
/**
664
@defgroup tools Standalone Utility Applications
665

	
666
Some utility applications are listed here.
667

	
668
The standard compilation procedure (<tt>./configure;make</tt>) will compile
669
them, as well.
670
*/
671

	
672 715
}
Ignore white space 6 line context
1 1
EXTRA_DIST += \
2 2
	lemon/lemon.pc.in \
3 3
	lemon/CMakeLists.txt \
4 4
	lemon/config.h.cmake
5 5

	
6 6
pkgconfig_DATA += lemon/lemon.pc
7 7

	
8 8
lib_LTLIBRARIES += lemon/libemon.la
9 9

	
10 10
lemon_libemon_la_SOURCES = \
11 11
	lemon/arg_parser.cc \
12 12
	lemon/base.cc \
13 13
	lemon/color.cc \
14 14
	lemon/lp_base.cc \
15 15
	lemon/lp_skeleton.cc \
16 16
	lemon/random.cc \
17 17
	lemon/bits/windows.cc
18 18

	
19 19
nodist_lemon_HEADERS = lemon/config.h	
20 20

	
21 21
lemon_libemon_la_CXXFLAGS = \
22 22
	$(AM_CXXFLAGS) \
23 23
	$(GLPK_CFLAGS) \
24 24
	$(CPLEX_CFLAGS) \
25 25
	$(SOPLEX_CXXFLAGS) \
26 26
	$(CLP_CXXFLAGS) \
27 27
	$(CBC_CXXFLAGS)
28 28

	
29 29
lemon_libemon_la_LDFLAGS = \
30 30
	$(GLPK_LIBS) \
31 31
	$(CPLEX_LIBS) \
32 32
	$(SOPLEX_LIBS) \
33 33
	$(CLP_LIBS) \
34 34
	$(CBC_LIBS)
35 35

	
36 36
if HAVE_GLPK
37 37
lemon_libemon_la_SOURCES += lemon/glpk.cc
38 38
endif
39 39

	
40 40
if HAVE_CPLEX
41 41
lemon_libemon_la_SOURCES += lemon/cplex.cc
42 42
endif
43 43

	
44 44
if HAVE_SOPLEX
45 45
lemon_libemon_la_SOURCES += lemon/soplex.cc
46 46
endif
47 47

	
48 48
if HAVE_CLP
49 49
lemon_libemon_la_SOURCES += lemon/clp.cc
50 50
endif
51 51

	
52 52
if HAVE_CBC
53 53
lemon_libemon_la_SOURCES += lemon/cbc.cc
54 54
endif
55 55

	
56 56
lemon_HEADERS += \
57 57
	lemon/adaptors.h \
58 58
	lemon/arg_parser.h \
59 59
	lemon/assert.h \
60
	lemon/bellman_ford.h \
60 61
	lemon/bfs.h \
61 62
	lemon/bin_heap.h \
63
	lemon/binom_heap.h \
62 64
	lemon/bucket_heap.h \
63 65
	lemon/cbc.h \
64 66
	lemon/circulation.h \
65 67
	lemon/clp.h \
66 68
	lemon/color.h \
67 69
	lemon/concept_check.h \
68 70
	lemon/connectivity.h \
69 71
	lemon/counter.h \
70 72
	lemon/core.h \
71 73
	lemon/cplex.h \
72 74
	lemon/dfs.h \
73 75
	lemon/dijkstra.h \
74 76
	lemon/dim2.h \
75 77
	lemon/dimacs.h \
76 78
	lemon/edge_set.h \
77 79
	lemon/elevator.h \
78 80
	lemon/error.h \
79 81
	lemon/euler.h \
80 82
	lemon/fib_heap.h \
83
	lemon/fourary_heap.h \
81 84
	lemon/full_graph.h \
82 85
	lemon/glpk.h \
83 86
	lemon/gomory_hu.h \
84 87
	lemon/graph_to_eps.h \
85 88
	lemon/grid_graph.h \
86 89
	lemon/hypercube_graph.h \
90
	lemon/kary_heap.h \
87 91
	lemon/kruskal.h \
88 92
	lemon/hao_orlin.h \
89 93
	lemon/lgf_reader.h \
90 94
	lemon/lgf_writer.h \
91 95
	lemon/list_graph.h \
92 96
	lemon/lp.h \
93 97
	lemon/lp_base.h \
94 98
	lemon/lp_skeleton.h \
95
	lemon/list_graph.h \
96 99
	lemon/maps.h \
97 100
	lemon/matching.h \
98 101
	lemon/math.h \
99 102
	lemon/min_cost_arborescence.h \
100 103
	lemon/nauty_reader.h \
101 104
	lemon/network_simplex.h \
105
	lemon/pairing_heap.h \
102 106
	lemon/path.h \
103 107
	lemon/preflow.h \
104 108
	lemon/radix_heap.h \
105 109
	lemon/radix_sort.h \
106 110
	lemon/random.h \
107 111
	lemon/smart_graph.h \
108 112
	lemon/soplex.h \
109 113
	lemon/suurballe.h \
110 114
	lemon/time_measure.h \
111 115
	lemon/tolerance.h \
112 116
	lemon/unionfind.h \
113 117
	lemon/bits/windows.h
114 118

	
115 119
bits_HEADERS += \
116 120
	lemon/bits/alteration_notifier.h \
117 121
	lemon/bits/array_map.h \
118 122
	lemon/bits/bezier.h \
119 123
	lemon/bits/default_map.h \
120 124
	lemon/bits/edge_set_extender.h \
121 125
	lemon/bits/enable_if.h \
122 126
	lemon/bits/graph_adaptor_extender.h \
123 127
	lemon/bits/graph_extender.h \
124 128
	lemon/bits/map_extender.h \
125 129
	lemon/bits/path_dump.h \
126 130
	lemon/bits/solver_bits.h \
127 131
	lemon/bits/traits.h \
128 132
	lemon/bits/variant.h \
129 133
	lemon/bits/vector_map.h
130 134

	
131 135
concept_HEADERS += \
132 136
	lemon/concepts/digraph.h \
133 137
	lemon/concepts/graph.h \
134 138
	lemon/concepts/graph_components.h \
135 139
	lemon/concepts/heap.h \
136 140
	lemon/concepts/maps.h \
137 141
	lemon/concepts/path.h
Ignore white space 6 line context
1 1
/* -*- mode: C++; indent-tabs-mode: nil; -*-
2 2
 *
3 3
 * This file is a part of LEMON, a generic C++ optimization library.
4 4
 *
5 5
 * Copyright (C) 2003-2009
6 6
 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 7
 * (Egervary Research Group on Combinatorial Optimization, EGRES).
8 8
 *
9 9
 * Permission to use, modify and distribute this software is granted
10 10
 * provided that this copyright notice appears in all copies. For
11 11
 * precise terms see the accompanying LICENSE file.
12 12
 *
13 13
 * This software is provided "AS IS" with no warranty of any kind,
14 14
 * express or implied, and with no claim as to its suitability for any
15 15
 * purpose.
16 16
 *
17 17
 */
18 18

	
19 19
#ifndef LEMON_BFS_H
20 20
#define LEMON_BFS_H
21 21

	
22 22
///\ingroup search
23 23
///\file
24 24
///\brief BFS algorithm.
25 25

	
26 26
#include <lemon/list_graph.h>
27 27
#include <lemon/bits/path_dump.h>
28 28
#include <lemon/core.h>
29 29
#include <lemon/error.h>
30 30
#include <lemon/maps.h>
31 31
#include <lemon/path.h>
32 32

	
33 33
namespace lemon {
34 34

	
35 35
  ///Default traits class of Bfs class.
36 36

	
37 37
  ///Default traits class of Bfs class.
38 38
  ///\tparam GR Digraph type.
39 39
  template<class GR>
40 40
  struct BfsDefaultTraits
41 41
  {
42 42
    ///The type of the digraph the algorithm runs on.
43 43
    typedef GR Digraph;
44 44

	
45 45
    ///\brief The type of the map that stores the predecessor
46 46
    ///arcs of the shortest paths.
47 47
    ///
48 48
    ///The type of the map that stores the predecessor
49 49
    ///arcs of the shortest paths.
50
    ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
50
    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
51 51
    typedef typename Digraph::template NodeMap<typename Digraph::Arc> PredMap;
52 52
    ///Instantiates a \c PredMap.
53 53

	
54 54
    ///This function instantiates a \ref PredMap.
55 55
    ///\param g is the digraph, to which we would like to define the
56 56
    ///\ref PredMap.
57 57
    static PredMap *createPredMap(const Digraph &g)
58 58
    {
59 59
      return new PredMap(g);
60 60
    }
61 61

	
62 62
    ///The type of the map that indicates which nodes are processed.
63 63

	
64 64
    ///The type of the map that indicates which nodes are processed.
65
    ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
65
    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
66
    ///By default it is a NullMap.
66 67
    typedef NullMap<typename Digraph::Node,bool> ProcessedMap;
67 68
    ///Instantiates a \c ProcessedMap.
68 69

	
69 70
    ///This function instantiates a \ref ProcessedMap.
70 71
    ///\param g is the digraph, to which
71 72
    ///we would like to define the \ref ProcessedMap
72 73
#ifdef DOXYGEN
73 74
    static ProcessedMap *createProcessedMap(const Digraph &g)
74 75
#else
75 76
    static ProcessedMap *createProcessedMap(const Digraph &)
76 77
#endif
77 78
    {
78 79
      return new ProcessedMap();
79 80
    }
80 81

	
81 82
    ///The type of the map that indicates which nodes are reached.
82 83

	
83 84
    ///The type of the map that indicates which nodes are reached.
84
    ///It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
85
    ///It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
85 86
    typedef typename Digraph::template NodeMap<bool> ReachedMap;
86 87
    ///Instantiates a \c ReachedMap.
87 88

	
88 89
    ///This function instantiates a \ref ReachedMap.
89 90
    ///\param g is the digraph, to which
90 91
    ///we would like to define the \ref ReachedMap.
91 92
    static ReachedMap *createReachedMap(const Digraph &g)
92 93
    {
93 94
      return new ReachedMap(g);
94 95
    }
95 96

	
96 97
    ///The type of the map that stores the distances of the nodes.
97 98

	
98 99
    ///The type of the map that stores the distances of the nodes.
99
    ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
100
    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
100 101
    typedef typename Digraph::template NodeMap<int> DistMap;
101 102
    ///Instantiates a \c DistMap.
102 103

	
103 104
    ///This function instantiates a \ref DistMap.
104 105
    ///\param g is the digraph, to which we would like to define the
105 106
    ///\ref DistMap.
106 107
    static DistMap *createDistMap(const Digraph &g)
107 108
    {
108 109
      return new DistMap(g);
109 110
    }
110 111
  };
111 112

	
112 113
  ///%BFS algorithm class.
113 114

	
114 115
  ///\ingroup search
115 116
  ///This class provides an efficient implementation of the %BFS algorithm.
116 117
  ///
117 118
  ///There is also a \ref bfs() "function-type interface" for the BFS
118 119
  ///algorithm, which is convenient in the simplier cases and it can be
119 120
  ///used easier.
120 121
  ///
121 122
  ///\tparam GR The type of the digraph the algorithm runs on.
122 123
  ///The default type is \ref ListDigraph.
123 124
#ifdef DOXYGEN
124 125
  template <typename GR,
125 126
            typename TR>
126 127
#else
127 128
  template <typename GR=ListDigraph,
128 129
            typename TR=BfsDefaultTraits<GR> >
129 130
#endif
130 131
  class Bfs {
131 132
  public:
132 133

	
133 134
    ///The type of the digraph the algorithm runs on.
134 135
    typedef typename TR::Digraph Digraph;
135 136

	
136 137
    ///\brief The type of the map that stores the predecessor arcs of the
137 138
    ///shortest paths.
138 139
    typedef typename TR::PredMap PredMap;
139 140
    ///The type of the map that stores the distances of the nodes.
140 141
    typedef typename TR::DistMap DistMap;
141 142
    ///The type of the map that indicates which nodes are reached.
142 143
    typedef typename TR::ReachedMap ReachedMap;
143 144
    ///The type of the map that indicates which nodes are processed.
144 145
    typedef typename TR::ProcessedMap ProcessedMap;
145 146
    ///The type of the paths.
146 147
    typedef PredMapPath<Digraph, PredMap> Path;
147 148

	
148 149
    ///The \ref BfsDefaultTraits "traits class" of the algorithm.
149 150
    typedef TR Traits;
150 151

	
151 152
  private:
152 153

	
153 154
    typedef typename Digraph::Node Node;
154 155
    typedef typename Digraph::NodeIt NodeIt;
155 156
    typedef typename Digraph::Arc Arc;
156 157
    typedef typename Digraph::OutArcIt OutArcIt;
157 158

	
158 159
    //Pointer to the underlying digraph.
159 160
    const Digraph *G;
160 161
    //Pointer to the map of predecessor arcs.
161 162
    PredMap *_pred;
162 163
    //Indicates if _pred is locally allocated (true) or not.
163 164
    bool local_pred;
164 165
    //Pointer to the map of distances.
165 166
    DistMap *_dist;
166 167
    //Indicates if _dist is locally allocated (true) or not.
167 168
    bool local_dist;
168 169
    //Pointer to the map of reached status of the nodes.
169 170
    ReachedMap *_reached;
170 171
    //Indicates if _reached is locally allocated (true) or not.
171 172
    bool local_reached;
172 173
    //Pointer to the map of processed status of the nodes.
173 174
    ProcessedMap *_processed;
174 175
    //Indicates if _processed is locally allocated (true) or not.
175 176
    bool local_processed;
176 177

	
177 178
    std::vector<typename Digraph::Node> _queue;
178 179
    int _queue_head,_queue_tail,_queue_next_dist;
179 180
    int _curr_dist;
180 181

	
181 182
    //Creates the maps if necessary.
182 183
    void create_maps()
183 184
    {
184 185
      if(!_pred) {
185 186
        local_pred = true;
186 187
        _pred = Traits::createPredMap(*G);
187 188
      }
188 189
      if(!_dist) {
189 190
        local_dist = true;
190 191
        _dist = Traits::createDistMap(*G);
191 192
      }
192 193
      if(!_reached) {
193 194
        local_reached = true;
194 195
        _reached = Traits::createReachedMap(*G);
195 196
      }
196 197
      if(!_processed) {
197 198
        local_processed = true;
198 199
        _processed = Traits::createProcessedMap(*G);
199 200
      }
200 201
    }
201 202

	
202 203
  protected:
203 204

	
204 205
    Bfs() {}
205 206

	
206 207
  public:
207 208

	
208 209
    typedef Bfs Create;
209 210

	
210 211
    ///\name Named Template Parameters
211 212

	
212 213
    ///@{
213 214

	
214 215
    template <class T>
215 216
    struct SetPredMapTraits : public Traits {
216 217
      typedef T PredMap;
217 218
      static PredMap *createPredMap(const Digraph &)
218 219
      {
219 220
        LEMON_ASSERT(false, "PredMap is not initialized");
220 221
        return 0; // ignore warnings
221 222
      }
222 223
    };
223 224
    ///\brief \ref named-templ-param "Named parameter" for setting
224 225
    ///\c PredMap type.
225 226
    ///
226 227
    ///\ref named-templ-param "Named parameter" for setting
227 228
    ///\c PredMap type.
228
    ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
229
    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
229 230
    template <class T>
230 231
    struct SetPredMap : public Bfs< Digraph, SetPredMapTraits<T> > {
231 232
      typedef Bfs< Digraph, SetPredMapTraits<T> > Create;
232 233
    };
233 234

	
234 235
    template <class T>
235 236
    struct SetDistMapTraits : public Traits {
236 237
      typedef T DistMap;
237 238
      static DistMap *createDistMap(const Digraph &)
238 239
      {
239 240
        LEMON_ASSERT(false, "DistMap is not initialized");
240 241
        return 0; // ignore warnings
241 242
      }
242 243
    };
243 244
    ///\brief \ref named-templ-param "Named parameter" for setting
244 245
    ///\c DistMap type.
245 246
    ///
246 247
    ///\ref named-templ-param "Named parameter" for setting
247 248
    ///\c DistMap type.
248
    ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
249
    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
249 250
    template <class T>
250 251
    struct SetDistMap : public Bfs< Digraph, SetDistMapTraits<T> > {
251 252
      typedef Bfs< Digraph, SetDistMapTraits<T> > Create;
252 253
    };
253 254

	
254 255
    template <class T>
255 256
    struct SetReachedMapTraits : public Traits {
256 257
      typedef T ReachedMap;
257 258
      static ReachedMap *createReachedMap(const Digraph &)
258 259
      {
259 260
        LEMON_ASSERT(false, "ReachedMap is not initialized");
260 261
        return 0; // ignore warnings
261 262
      }
262 263
    };
263 264
    ///\brief \ref named-templ-param "Named parameter" for setting
264 265
    ///\c ReachedMap type.
265 266
    ///
266 267
    ///\ref named-templ-param "Named parameter" for setting
267 268
    ///\c ReachedMap type.
268
    ///It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
269
    ///It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
269 270
    template <class T>
270 271
    struct SetReachedMap : public Bfs< Digraph, SetReachedMapTraits<T> > {
271 272
      typedef Bfs< Digraph, SetReachedMapTraits<T> > Create;
272 273
    };
273 274

	
274 275
    template <class T>
275 276
    struct SetProcessedMapTraits : public Traits {
276 277
      typedef T ProcessedMap;
277 278
      static ProcessedMap *createProcessedMap(const Digraph &)
278 279
      {
279 280
        LEMON_ASSERT(false, "ProcessedMap is not initialized");
280 281
        return 0; // ignore warnings
281 282
      }
282 283
    };
283 284
    ///\brief \ref named-templ-param "Named parameter" for setting
284 285
    ///\c ProcessedMap type.
285 286
    ///
286 287
    ///\ref named-templ-param "Named parameter" for setting
287 288
    ///\c ProcessedMap type.
288
    ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
289
    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
289 290
    template <class T>
290 291
    struct SetProcessedMap : public Bfs< Digraph, SetProcessedMapTraits<T> > {
291 292
      typedef Bfs< Digraph, SetProcessedMapTraits<T> > Create;
292 293
    };
293 294

	
294 295
    struct SetStandardProcessedMapTraits : public Traits {
295 296
      typedef typename Digraph::template NodeMap<bool> ProcessedMap;
296 297
      static ProcessedMap *createProcessedMap(const Digraph &g)
297 298
      {
298 299
        return new ProcessedMap(g);
299 300
        return 0; // ignore warnings
300 301
      }
301 302
    };
302 303
    ///\brief \ref named-templ-param "Named parameter" for setting
303 304
    ///\c ProcessedMap type to be <tt>Digraph::NodeMap<bool></tt>.
304 305
    ///
305 306
    ///\ref named-templ-param "Named parameter" for setting
306 307
    ///\c ProcessedMap type to be <tt>Digraph::NodeMap<bool></tt>.
307 308
    ///If you don't set it explicitly, it will be automatically allocated.
308 309
    struct SetStandardProcessedMap :
309 310
      public Bfs< Digraph, SetStandardProcessedMapTraits > {
310 311
      typedef Bfs< Digraph, SetStandardProcessedMapTraits > Create;
311 312
    };
312 313

	
313 314
    ///@}
314 315

	
315 316
  public:
316 317

	
317 318
    ///Constructor.
318 319

	
319 320
    ///Constructor.
320 321
    ///\param g The digraph the algorithm runs on.
321 322
    Bfs(const Digraph &g) :
322 323
      G(&g),
323 324
      _pred(NULL), local_pred(false),
324 325
      _dist(NULL), local_dist(false),
325 326
      _reached(NULL), local_reached(false),
326 327
      _processed(NULL), local_processed(false)
327 328
    { }
328 329

	
329 330
    ///Destructor.
330 331
    ~Bfs()
331 332
    {
332 333
      if(local_pred) delete _pred;
333 334
      if(local_dist) delete _dist;
334 335
      if(local_reached) delete _reached;
335 336
      if(local_processed) delete _processed;
336 337
    }
337 338

	
338 339
    ///Sets the map that stores the predecessor arcs.
339 340

	
340 341
    ///Sets the map that stores the predecessor arcs.
341 342
    ///If you don't use this function before calling \ref run(Node) "run()"
342 343
    ///or \ref init(), an instance will be allocated automatically.
343 344
    ///The destructor deallocates this automatically allocated map,
344 345
    ///of course.
345 346
    ///\return <tt> (*this) </tt>
346 347
    Bfs &predMap(PredMap &m)
347 348
    {
348 349
      if(local_pred) {
349 350
        delete _pred;
350 351
        local_pred=false;
351 352
      }
352 353
      _pred = &m;
353 354
      return *this;
354 355
    }
355 356

	
356 357
    ///Sets the map that indicates which nodes are reached.
357 358

	
358 359
    ///Sets the map that indicates which nodes are reached.
359 360
    ///If you don't use this function before calling \ref run(Node) "run()"
360 361
    ///or \ref init(), an instance will be allocated automatically.
361 362
    ///The destructor deallocates this automatically allocated map,
362 363
    ///of course.
363 364
    ///\return <tt> (*this) </tt>
364 365
    Bfs &reachedMap(ReachedMap &m)
365 366
    {
366 367
      if(local_reached) {
367 368
        delete _reached;
368 369
        local_reached=false;
369 370
      }
370 371
      _reached = &m;
371 372
      return *this;
372 373
    }
373 374

	
374 375
    ///Sets the map that indicates which nodes are processed.
375 376

	
376 377
    ///Sets the map that indicates which nodes are processed.
377 378
    ///If you don't use this function before calling \ref run(Node) "run()"
378 379
    ///or \ref init(), an instance will be allocated automatically.
379 380
    ///The destructor deallocates this automatically allocated map,
380 381
    ///of course.
381 382
    ///\return <tt> (*this) </tt>
382 383
    Bfs &processedMap(ProcessedMap &m)
383 384
    {
384 385
      if(local_processed) {
385 386
        delete _processed;
386 387
        local_processed=false;
387 388
      }
388 389
      _processed = &m;
389 390
      return *this;
390 391
    }
391 392

	
392 393
    ///Sets the map that stores the distances of the nodes.
393 394

	
394 395
    ///Sets the map that stores the distances of the nodes calculated by
395 396
    ///the algorithm.
396 397
    ///If you don't use this function before calling \ref run(Node) "run()"
397 398
    ///or \ref init(), an instance will be allocated automatically.
398 399
    ///The destructor deallocates this automatically allocated map,
399 400
    ///of course.
400 401
    ///\return <tt> (*this) </tt>
401 402
    Bfs &distMap(DistMap &m)
402 403
    {
403 404
      if(local_dist) {
404 405
        delete _dist;
405 406
        local_dist=false;
406 407
      }
407 408
      _dist = &m;
408 409
      return *this;
409 410
    }
410 411

	
411 412
  public:
412 413

	
413 414
    ///\name Execution Control
414 415
    ///The simplest way to execute the BFS algorithm is to use one of the
415 416
    ///member functions called \ref run(Node) "run()".\n
416
    ///If you need more control on the execution, first you have to call
417
    ///\ref init(), then you can add several source nodes with
417
    ///If you need better control on the execution, you have to call
418
    ///\ref init() first, then you can add several source nodes with
418 419
    ///\ref addSource(). Finally the actual path computation can be
419 420
    ///performed with one of the \ref start() functions.
420 421

	
421 422
    ///@{
422 423

	
423 424
    ///\brief Initializes the internal data structures.
424 425
    ///
425 426
    ///Initializes the internal data structures.
426 427
    void init()
427 428
    {
428 429
      create_maps();
429 430
      _queue.resize(countNodes(*G));
430 431
      _queue_head=_queue_tail=0;
431 432
      _curr_dist=1;
432 433
      for ( NodeIt u(*G) ; u!=INVALID ; ++u ) {
433 434
        _pred->set(u,INVALID);
434 435
        _reached->set(u,false);
435 436
        _processed->set(u,false);
436 437
      }
437 438
    }
438 439

	
439 440
    ///Adds a new source node.
440 441

	
441 442
    ///Adds a new source node to the set of nodes to be processed.
442 443
    ///
443 444
    void addSource(Node s)
444 445
    {
445 446
      if(!(*_reached)[s])
446 447
        {
447 448
          _reached->set(s,true);
448 449
          _pred->set(s,INVALID);
449 450
          _dist->set(s,0);
450 451
          _queue[_queue_head++]=s;
451 452
          _queue_next_dist=_queue_head;
452 453
        }
453 454
    }
454 455

	
455 456
    ///Processes the next node.
456 457

	
457 458
    ///Processes the next node.
458 459
    ///
459 460
    ///\return The processed node.
460 461
    ///
461 462
    ///\pre The queue must not be empty.
462 463
    Node processNextNode()
463 464
    {
464 465
      if(_queue_tail==_queue_next_dist) {
465 466
        _curr_dist++;
466 467
        _queue_next_dist=_queue_head;
467 468
      }
468 469
      Node n=_queue[_queue_tail++];
469 470
      _processed->set(n,true);
470 471
      Node m;
471 472
      for(OutArcIt e(*G,n);e!=INVALID;++e)
472 473
        if(!(*_reached)[m=G->target(e)]) {
473 474
          _queue[_queue_head++]=m;
474 475
          _reached->set(m,true);
475 476
          _pred->set(m,e);
476 477
          _dist->set(m,_curr_dist);
477 478
        }
478 479
      return n;
479 480
    }
480 481

	
481 482
    ///Processes the next node.
482 483

	
483 484
    ///Processes the next node and checks if the given target node
484 485
    ///is reached. If the target node is reachable from the processed
485 486
    ///node, then the \c reach parameter will be set to \c true.
486 487
    ///
487 488
    ///\param target The target node.
488 489
    ///\retval reach Indicates if the target node is reached.
489 490
    ///It should be initially \c false.
490 491
    ///
491 492
    ///\return The processed node.
492 493
    ///
493 494
    ///\pre The queue must not be empty.
494 495
    Node processNextNode(Node target, bool& reach)
495 496
    {
496 497
      if(_queue_tail==_queue_next_dist) {
497 498
        _curr_dist++;
498 499
        _queue_next_dist=_queue_head;
499 500
      }
500 501
      Node n=_queue[_queue_tail++];
501 502
      _processed->set(n,true);
502 503
      Node m;
503 504
      for(OutArcIt e(*G,n);e!=INVALID;++e)
504 505
        if(!(*_reached)[m=G->target(e)]) {
505 506
          _queue[_queue_head++]=m;
506 507
          _reached->set(m,true);
507 508
          _pred->set(m,e);
508 509
          _dist->set(m,_curr_dist);
509 510
          reach = reach || (target == m);
510 511
        }
511 512
      return n;
512 513
    }
513 514

	
514 515
    ///Processes the next node.
515 516

	
516 517
    ///Processes the next node and checks if at least one of reached
517 518
    ///nodes has \c true value in the \c nm node map. If one node
518 519
    ///with \c true value is reachable from the processed node, then the
519 520
    ///\c rnode parameter will be set to the first of such nodes.
520 521
    ///
521 522
    ///\param nm A \c bool (or convertible) node map that indicates the
522 523
    ///possible targets.
523 524
    ///\retval rnode The reached target node.
524 525
    ///It should be initially \c INVALID.
525 526
    ///
526 527
    ///\return The processed node.
527 528
    ///
528 529
    ///\pre The queue must not be empty.
529 530
    template<class NM>
530 531
    Node processNextNode(const NM& nm, Node& rnode)
531 532
    {
532 533
      if(_queue_tail==_queue_next_dist) {
533 534
        _curr_dist++;
534 535
        _queue_next_dist=_queue_head;
535 536
      }
536 537
      Node n=_queue[_queue_tail++];
537 538
      _processed->set(n,true);
538 539
      Node m;
539 540
      for(OutArcIt e(*G,n);e!=INVALID;++e)
540 541
        if(!(*_reached)[m=G->target(e)]) {
541 542
          _queue[_queue_head++]=m;
542 543
          _reached->set(m,true);
543 544
          _pred->set(m,e);
544 545
          _dist->set(m,_curr_dist);
545 546
          if (nm[m] && rnode == INVALID) rnode = m;
546 547
        }
547 548
      return n;
548 549
    }
549 550

	
550 551
    ///The next node to be processed.
551 552

	
552 553
    ///Returns the next node to be processed or \c INVALID if the queue
553 554
    ///is empty.
554 555
    Node nextNode() const
555 556
    {
556 557
      return _queue_tail<_queue_head?_queue[_queue_tail]:INVALID;
557 558
    }
558 559

	
559 560
    ///Returns \c false if there are nodes to be processed.
560 561

	
561 562
    ///Returns \c false if there are nodes to be processed
562 563
    ///in the queue.
563 564
    bool emptyQueue() const { return _queue_tail==_queue_head; }
564 565

	
565 566
    ///Returns the number of the nodes to be processed.
566 567

	
567 568
    ///Returns the number of the nodes to be processed
568 569
    ///in the queue.
569 570
    int queueSize() const { return _queue_head-_queue_tail; }
570 571

	
571 572
    ///Executes the algorithm.
572 573

	
573 574
    ///Executes the algorithm.
574 575
    ///
575 576
    ///This method runs the %BFS algorithm from the root node(s)
576 577
    ///in order to compute the shortest path to each node.
577 578
    ///
578 579
    ///The algorithm computes
579 580
    ///- the shortest path tree (forest),
580 581
    ///- the distance of each node from the root(s).
581 582
    ///
582 583
    ///\pre init() must be called and at least one root node should be
583 584
    ///added with addSource() before using this function.
584 585
    ///
585 586
    ///\note <tt>b.start()</tt> is just a shortcut of the following code.
586 587
    ///\code
587 588
    ///  while ( !b.emptyQueue() ) {
588 589
    ///    b.processNextNode();
589 590
    ///  }
590 591
    ///\endcode
591 592
    void start()
592 593
    {
593 594
      while ( !emptyQueue() ) processNextNode();
594 595
    }
595 596

	
596 597
    ///Executes the algorithm until the given target node is reached.
597 598

	
598 599
    ///Executes the algorithm until the given target node is reached.
599 600
    ///
600 601
    ///This method runs the %BFS algorithm from the root node(s)
601 602
    ///in order to compute the shortest path to \c t.
602 603
    ///
603 604
    ///The algorithm computes
604 605
    ///- the shortest path to \c t,
605 606
    ///- the distance of \c t from the root(s).
606 607
    ///
607 608
    ///\pre init() must be called and at least one root node should be
608 609
    ///added with addSource() before using this function.
609 610
    ///
610 611
    ///\note <tt>b.start(t)</tt> is just a shortcut of the following code.
611 612
    ///\code
612 613
    ///  bool reach = false;
613 614
    ///  while ( !b.emptyQueue() && !reach ) {
614 615
    ///    b.processNextNode(t, reach);
615 616
    ///  }
616 617
    ///\endcode
617 618
    void start(Node t)
618 619
    {
619 620
      bool reach = false;
620 621
      while ( !emptyQueue() && !reach ) processNextNode(t, reach);
621 622
    }
622 623

	
623 624
    ///Executes the algorithm until a condition is met.
624 625

	
625 626
    ///Executes the algorithm until a condition is met.
626 627
    ///
627 628
    ///This method runs the %BFS algorithm from the root node(s) in
628 629
    ///order to compute the shortest path to a node \c v with
629 630
    /// <tt>nm[v]</tt> true, if such a node can be found.
630 631
    ///
631 632
    ///\param nm A \c bool (or convertible) node map. The algorithm
632 633
    ///will stop when it reaches a node \c v with <tt>nm[v]</tt> true.
633 634
    ///
634 635
    ///\return The reached node \c v with <tt>nm[v]</tt> true or
635 636
    ///\c INVALID if no such node was found.
636 637
    ///
637 638
    ///\pre init() must be called and at least one root node should be
638 639
    ///added with addSource() before using this function.
639 640
    ///
640 641
    ///\note <tt>b.start(nm)</tt> is just a shortcut of the following code.
641 642
    ///\code
642 643
    ///  Node rnode = INVALID;
643 644
    ///  while ( !b.emptyQueue() && rnode == INVALID ) {
644 645
    ///    b.processNextNode(nm, rnode);
645 646
    ///  }
646 647
    ///  return rnode;
647 648
    ///\endcode
648 649
    template<class NodeBoolMap>
649 650
    Node start(const NodeBoolMap &nm)
650 651
    {
651 652
      Node rnode = INVALID;
652 653
      while ( !emptyQueue() && rnode == INVALID ) {
653 654
        processNextNode(nm, rnode);
654 655
      }
655 656
      return rnode;
656 657
    }
657 658

	
658 659
    ///Runs the algorithm from the given source node.
659 660

	
660 661
    ///This method runs the %BFS algorithm from node \c s
661 662
    ///in order to compute the shortest path to each node.
662 663
    ///
663 664
    ///The algorithm computes
664 665
    ///- the shortest path tree,
665 666
    ///- the distance of each node from the root.
666 667
    ///
667 668
    ///\note <tt>b.run(s)</tt> is just a shortcut of the following code.
668 669
    ///\code
669 670
    ///  b.init();
670 671
    ///  b.addSource(s);
671 672
    ///  b.start();
672 673
    ///\endcode
673 674
    void run(Node s) {
674 675
      init();
675 676
      addSource(s);
676 677
      start();
677 678
    }
678 679

	
679 680
    ///Finds the shortest path between \c s and \c t.
680 681

	
681 682
    ///This method runs the %BFS algorithm from node \c s
682 683
    ///in order to compute the shortest path to node \c t
683 684
    ///(it stops searching when \c t is processed).
684 685
    ///
685 686
    ///\return \c true if \c t is reachable form \c s.
686 687
    ///
687 688
    ///\note Apart from the return value, <tt>b.run(s,t)</tt> is just a
688 689
    ///shortcut of the following code.
689 690
    ///\code
690 691
    ///  b.init();
691 692
    ///  b.addSource(s);
692 693
    ///  b.start(t);
693 694
    ///\endcode
694 695
    bool run(Node s,Node t) {
695 696
      init();
696 697
      addSource(s);
697 698
      start(t);
698 699
      return reached(t);
699 700
    }
700 701

	
701 702
    ///Runs the algorithm to visit all nodes in the digraph.
702 703

	
703 704
    ///This method runs the %BFS algorithm in order to
704 705
    ///compute the shortest path to each node.
705 706
    ///
706 707
    ///The algorithm computes
707 708
    ///- the shortest path tree (forest),
708 709
    ///- the distance of each node from the root(s).
709 710
    ///
710 711
    ///\note <tt>b.run(s)</tt> is just a shortcut of the following code.
711 712
    ///\code
712 713
    ///  b.init();
713 714
    ///  for (NodeIt n(gr); n != INVALID; ++n) {
714 715
    ///    if (!b.reached(n)) {
715 716
    ///      b.addSource(n);
716 717
    ///      b.start();
717 718
    ///    }
718 719
    ///  }
719 720
    ///\endcode
720 721
    void run() {
721 722
      init();
722 723
      for (NodeIt n(*G); n != INVALID; ++n) {
723 724
        if (!reached(n)) {
724 725
          addSource(n);
725 726
          start();
726 727
        }
727 728
      }
728 729
    }
729 730

	
730 731
    ///@}
731 732

	
732 733
    ///\name Query Functions
733 734
    ///The results of the BFS algorithm can be obtained using these
734 735
    ///functions.\n
735 736
    ///Either \ref run(Node) "run()" or \ref start() should be called
736 737
    ///before using them.
737 738

	
738 739
    ///@{
739 740

	
740
    ///The shortest path to a node.
741
    ///The shortest path to the given node.
741 742

	
742
    ///Returns the shortest path to a node.
743
    ///Returns the shortest path to the given node from the root(s).
743 744
    ///
744 745
    ///\warning \c t should be reached from the root(s).
745 746
    ///
746 747
    ///\pre Either \ref run(Node) "run()" or \ref init()
747 748
    ///must be called before using this function.
748 749
    Path path(Node t) const { return Path(*G, *_pred, t); }
749 750

	
750
    ///The distance of a node from the root(s).
751
    ///The distance of the given node from the root(s).
751 752

	
752
    ///Returns the distance of a node from the root(s).
753
    ///Returns the distance of the given node from the root(s).
753 754
    ///
754 755
    ///\warning If node \c v is not reached from the root(s), then
755 756
    ///the return value of this function is undefined.
756 757
    ///
757 758
    ///\pre Either \ref run(Node) "run()" or \ref init()
758 759
    ///must be called before using this function.
759 760
    int dist(Node v) const { return (*_dist)[v]; }
760 761

	
761
    ///Returns the 'previous arc' of the shortest path tree for a node.
762

	
762
    ///\brief Returns the 'previous arc' of the shortest path tree for
763
    ///the given node.
764
    ///
763 765
    ///This function returns the 'previous arc' of the shortest path
764 766
    ///tree for the node \c v, i.e. it returns the last arc of a
765 767
    ///shortest path from a root to \c v. It is \c INVALID if \c v
766 768
    ///is not reached from the root(s) or if \c v is a root.
767 769
    ///
768 770
    ///The shortest path tree used here is equal to the shortest path
769
    ///tree used in \ref predNode().
771
    ///tree used in \ref predNode() and \ref predMap().
770 772
    ///
771 773
    ///\pre Either \ref run(Node) "run()" or \ref init()
772 774
    ///must be called before using this function.
773 775
    Arc predArc(Node v) const { return (*_pred)[v];}
774 776

	
775
    ///Returns the 'previous node' of the shortest path tree for a node.
776

	
777
    ///\brief Returns the 'previous node' of the shortest path tree for
778
    ///the given node.
779
    ///
777 780
    ///This function returns the 'previous node' of the shortest path
778 781
    ///tree for the node \c v, i.e. it returns the last but one node
779
    ///from a shortest path from a root to \c v. It is \c INVALID
782
    ///of a shortest path from a root to \c v. It is \c INVALID
780 783
    ///if \c v is not reached from the root(s) or if \c v is a root.
781 784
    ///
782 785
    ///The shortest path tree used here is equal to the shortest path
783
    ///tree used in \ref predArc().
786
    ///tree used in \ref predArc() and \ref predMap().
784 787
    ///
785 788
    ///\pre Either \ref run(Node) "run()" or \ref init()
786 789
    ///must be called before using this function.
787 790
    Node predNode(Node v) const { return (*_pred)[v]==INVALID ? INVALID:
788 791
                                  G->source((*_pred)[v]); }
789 792

	
790 793
    ///\brief Returns a const reference to the node map that stores the
791 794
    /// distances of the nodes.
792 795
    ///
793 796
    ///Returns a const reference to the node map that stores the distances
794 797
    ///of the nodes calculated by the algorithm.
795 798
    ///
796 799
    ///\pre Either \ref run(Node) "run()" or \ref init()
797 800
    ///must be called before using this function.
798 801
    const DistMap &distMap() const { return *_dist;}
799 802

	
800 803
    ///\brief Returns a const reference to the node map that stores the
801 804
    ///predecessor arcs.
802 805
    ///
803 806
    ///Returns a const reference to the node map that stores the predecessor
804
    ///arcs, which form the shortest path tree.
807
    ///arcs, which form the shortest path tree (forest).
805 808
    ///
806 809
    ///\pre Either \ref run(Node) "run()" or \ref init()
807 810
    ///must be called before using this function.
808 811
    const PredMap &predMap() const { return *_pred;}
809 812

	
810
    ///Checks if a node is reached from the root(s).
813
    ///Checks if the given node is reached from the root(s).
811 814

	
812 815
    ///Returns \c true if \c v is reached from the root(s).
813 816
    ///
814 817
    ///\pre Either \ref run(Node) "run()" or \ref init()
815 818
    ///must be called before using this function.
816 819
    bool reached(Node v) const { return (*_reached)[v]; }
817 820

	
818 821
    ///@}
819 822
  };
820 823

	
821 824
  ///Default traits class of bfs() function.
822 825

	
823 826
  ///Default traits class of bfs() function.
824 827
  ///\tparam GR Digraph type.
825 828
  template<class GR>
826 829
  struct BfsWizardDefaultTraits
827 830
  {
828 831
    ///The type of the digraph the algorithm runs on.
829 832
    typedef GR Digraph;
830 833

	
831 834
    ///\brief The type of the map that stores the predecessor
832 835
    ///arcs of the shortest paths.
833 836
    ///
834 837
    ///The type of the map that stores the predecessor
835 838
    ///arcs of the shortest paths.
836
    ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
839
    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
837 840
    typedef typename Digraph::template NodeMap<typename Digraph::Arc> PredMap;
838 841
    ///Instantiates a PredMap.
839 842

	
840 843
    ///This function instantiates a PredMap.
841 844
    ///\param g is the digraph, to which we would like to define the
842 845
    ///PredMap.
843 846
    static PredMap *createPredMap(const Digraph &g)
844 847
    {
845 848
      return new PredMap(g);
846 849
    }
847 850

	
848 851
    ///The type of the map that indicates which nodes are processed.
849 852

	
850 853
    ///The type of the map that indicates which nodes are processed.
851
    ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
854
    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
852 855
    ///By default it is a NullMap.
853 856
    typedef NullMap<typename Digraph::Node,bool> ProcessedMap;
854 857
    ///Instantiates a ProcessedMap.
855 858

	
856 859
    ///This function instantiates a ProcessedMap.
857 860
    ///\param g is the digraph, to which
858 861
    ///we would like to define the ProcessedMap.
859 862
#ifdef DOXYGEN
860 863
    static ProcessedMap *createProcessedMap(const Digraph &g)
861 864
#else
862 865
    static ProcessedMap *createProcessedMap(const Digraph &)
863 866
#endif
864 867
    {
865 868
      return new ProcessedMap();
866 869
    }
867 870

	
868 871
    ///The type of the map that indicates which nodes are reached.
869 872

	
870 873
    ///The type of the map that indicates which nodes are reached.
871
    ///It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
874
    ///It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
872 875
    typedef typename Digraph::template NodeMap<bool> ReachedMap;
873 876
    ///Instantiates a ReachedMap.
874 877

	
875 878
    ///This function instantiates a ReachedMap.
876 879
    ///\param g is the digraph, to which
877 880
    ///we would like to define the ReachedMap.
878 881
    static ReachedMap *createReachedMap(const Digraph &g)
879 882
    {
880 883
      return new ReachedMap(g);
881 884
    }
882 885

	
883 886
    ///The type of the map that stores the distances of the nodes.
884 887

	
885 888
    ///The type of the map that stores the distances of the nodes.
886
    ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
889
    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
887 890
    typedef typename Digraph::template NodeMap<int> DistMap;
888 891
    ///Instantiates a DistMap.
889 892

	
890 893
    ///This function instantiates a DistMap.
891 894
    ///\param g is the digraph, to which we would like to define
892 895
    ///the DistMap
893 896
    static DistMap *createDistMap(const Digraph &g)
894 897
    {
895 898
      return new DistMap(g);
896 899
    }
897 900

	
898 901
    ///The type of the shortest paths.
899 902

	
900 903
    ///The type of the shortest paths.
901
    ///It must meet the \ref concepts::Path "Path" concept.
904
    ///It must conform to the \ref concepts::Path "Path" concept.
902 905
    typedef lemon::Path<Digraph> Path;
903 906
  };
904 907

	
905 908
  /// Default traits class used by BfsWizard
906 909

	
907
  /// To make it easier to use Bfs algorithm
908
  /// we have created a wizard class.
909
  /// This \ref BfsWizard class needs default traits,
910
  /// as well as the \ref Bfs class.
911
  /// The \ref BfsWizardBase is a class to be the default traits of the
912
  /// \ref BfsWizard class.
910
  /// Default traits class used by BfsWizard.
911
  /// \tparam GR The type of the digraph.
913 912
  template<class GR>
914 913
  class BfsWizardBase : public BfsWizardDefaultTraits<GR>
915 914
  {
916 915

	
917 916
    typedef BfsWizardDefaultTraits<GR> Base;
918 917
  protected:
919 918
    //The type of the nodes in the digraph.
920 919
    typedef typename Base::Digraph::Node Node;
921 920

	
922 921
    //Pointer to the digraph the algorithm runs on.
923 922
    void *_g;
924 923
    //Pointer to the map of reached nodes.
925 924
    void *_reached;
926 925
    //Pointer to the map of processed nodes.
927 926
    void *_processed;
928 927
    //Pointer to the map of predecessors arcs.
929 928
    void *_pred;
930 929
    //Pointer to the map of distances.
931 930
    void *_dist;
932 931
    //Pointer to the shortest path to the target node.
933 932
    void *_path;
934 933
    //Pointer to the distance of the target node.
935 934
    int *_di;
936 935

	
937 936
    public:
938 937
    /// Constructor.
939 938

	
940
    /// This constructor does not require parameters, therefore it initiates
939
    /// This constructor does not require parameters, it initiates
941 940
    /// all of the attributes to \c 0.
942 941
    BfsWizardBase() : _g(0), _reached(0), _processed(0), _pred(0),
943 942
                      _dist(0), _path(0), _di(0) {}
944 943

	
945 944
    /// Constructor.
946 945

	
947 946
    /// This constructor requires one parameter,
948 947
    /// others are initiated to \c 0.
949 948
    /// \param g The digraph the algorithm runs on.
950 949
    BfsWizardBase(const GR &g) :
951 950
      _g(reinterpret_cast<void*>(const_cast<GR*>(&g))),
952 951
      _reached(0), _processed(0), _pred(0), _dist(0),  _path(0), _di(0) {}
953 952

	
954 953
  };
955 954

	
956 955
  /// Auxiliary class for the function-type interface of BFS algorithm.
957 956

	
958 957
  /// This auxiliary class is created to implement the
959 958
  /// \ref bfs() "function-type interface" of \ref Bfs algorithm.
960 959
  /// It does not have own \ref run(Node) "run()" method, it uses the
961 960
  /// functions and features of the plain \ref Bfs.
962 961
  ///
963 962
  /// This class should only be used through the \ref bfs() function,
964 963
  /// which makes it easier to use the algorithm.
965 964
  template<class TR>
966 965
  class BfsWizard : public TR
967 966
  {
968 967
    typedef TR Base;
969 968

	
970
    ///The type of the digraph the algorithm runs on.
971 969
    typedef typename TR::Digraph Digraph;
972 970

	
973 971
    typedef typename Digraph::Node Node;
974 972
    typedef typename Digraph::NodeIt NodeIt;
975 973
    typedef typename Digraph::Arc Arc;
976 974
    typedef typename Digraph::OutArcIt OutArcIt;
977 975

	
978
    ///\brief The type of the map that stores the predecessor
979
    ///arcs of the shortest paths.
980 976
    typedef typename TR::PredMap PredMap;
981
    ///\brief The type of the map that stores the distances of the nodes.
982 977
    typedef typename TR::DistMap DistMap;
983
    ///\brief The type of the map that indicates which nodes are reached.
984 978
    typedef typename TR::ReachedMap ReachedMap;
985
    ///\brief The type of the map that indicates which nodes are processed.
986 979
    typedef typename TR::ProcessedMap ProcessedMap;
987
    ///The type of the shortest paths
988 980
    typedef typename TR::Path Path;
989 981

	
990 982
  public:
991 983

	
992 984
    /// Constructor.
993 985
    BfsWizard() : TR() {}
994 986

	
995 987
    /// Constructor that requires parameters.
996 988

	
997 989
    /// Constructor that requires parameters.
998 990
    /// These parameters will be the default values for the traits class.
999 991
    /// \param g The digraph the algorithm runs on.
1000 992
    BfsWizard(const Digraph &g) :
1001 993
      TR(g) {}
1002 994

	
1003 995
    ///Copy constructor
1004 996
    BfsWizard(const TR &b) : TR(b) {}
1005 997

	
1006 998
    ~BfsWizard() {}
1007 999

	
1008 1000
    ///Runs BFS algorithm from the given source node.
1009 1001

	
1010 1002
    ///This method runs BFS algorithm from node \c s
1011 1003
    ///in order to compute the shortest path to each node.
1012 1004
    void run(Node s)
1013 1005
    {
1014 1006
      Bfs<Digraph,TR> alg(*reinterpret_cast<const Digraph*>(Base::_g));
1015 1007
      if (Base::_pred)
1016 1008
        alg.predMap(*reinterpret_cast<PredMap*>(Base::_pred));
1017 1009
      if (Base::_dist)
1018 1010
        alg.distMap(*reinterpret_cast<DistMap*>(Base::_dist));
1019 1011
      if (Base::_reached)
1020 1012
        alg.reachedMap(*reinterpret_cast<ReachedMap*>(Base::_reached));
1021 1013
      if (Base::_processed)
1022 1014
        alg.processedMap(*reinterpret_cast<ProcessedMap*>(Base::_processed));
1023 1015
      if (s!=INVALID)
1024 1016
        alg.run(s);
1025 1017
      else
1026 1018
        alg.run();
1027 1019
    }
1028 1020

	
1029 1021
    ///Finds the shortest path between \c s and \c t.
1030 1022

	
1031 1023
    ///This method runs BFS algorithm from node \c s
1032 1024
    ///in order to compute the shortest path to node \c t
1033 1025
    ///(it stops searching when \c t is processed).
1034 1026
    ///
1035 1027
    ///\return \c true if \c t is reachable form \c s.
1036 1028
    bool run(Node s, Node t)
1037 1029
    {
1038 1030
      Bfs<Digraph,TR> alg(*reinterpret_cast<const Digraph*>(Base::_g));
1039 1031
      if (Base::_pred)
1040 1032
        alg.predMap(*reinterpret_cast<PredMap*>(Base::_pred));
1041 1033
      if (Base::_dist)
1042 1034
        alg.distMap(*reinterpret_cast<DistMap*>(Base::_dist));
1043 1035
      if (Base::_reached)
1044 1036
        alg.reachedMap(*reinterpret_cast<ReachedMap*>(Base::_reached));
1045 1037
      if (Base::_processed)
1046 1038
        alg.processedMap(*reinterpret_cast<ProcessedMap*>(Base::_processed));
1047 1039
      alg.run(s,t);
1048 1040
      if (Base::_path)
1049 1041
        *reinterpret_cast<Path*>(Base::_path) = alg.path(t);
1050 1042
      if (Base::_di)
1051 1043
        *Base::_di = alg.dist(t);
1052 1044
      return alg.reached(t);
1053 1045
    }
1054 1046

	
1055 1047
    ///Runs BFS algorithm to visit all nodes in the digraph.
1056 1048

	
1057 1049
    ///This method runs BFS algorithm in order to compute
1058 1050
    ///the shortest path to each node.
1059 1051
    void run()
1060 1052
    {
1061 1053
      run(INVALID);
1062 1054
    }
1063 1055

	
1064 1056
    template<class T>
1065 1057
    struct SetPredMapBase : public Base {
1066 1058
      typedef T PredMap;
1067 1059
      static PredMap *createPredMap(const Digraph &) { return 0; };
1068 1060
      SetPredMapBase(const TR &b) : TR(b) {}
1069 1061
    };
1070
    ///\brief \ref named-func-param "Named parameter"
1071
    ///for setting PredMap object.
1062

	
1063
    ///\brief \ref named-templ-param "Named parameter" for setting
1064
    ///the predecessor map.
1072 1065
    ///
1073
    ///\ref named-func-param "Named parameter"
1074
    ///for setting PredMap object.
1066
    ///\ref named-templ-param "Named parameter" function for setting
1067
    ///the map that stores the predecessor arcs of the nodes.
1075 1068
    template<class T>
1076 1069
    BfsWizard<SetPredMapBase<T> > predMap(const T &t)
1077 1070
    {
1078 1071
      Base::_pred=reinterpret_cast<void*>(const_cast<T*>(&t));
1079 1072
      return BfsWizard<SetPredMapBase<T> >(*this);
1080 1073
    }
1081 1074

	
1082 1075
    template<class T>
1083 1076
    struct SetReachedMapBase : public Base {
1084 1077
      typedef T ReachedMap;
1085 1078
      static ReachedMap *createReachedMap(const Digraph &) { return 0; };
1086 1079
      SetReachedMapBase(const TR &b) : TR(b) {}
1087 1080
    };
1088
    ///\brief \ref named-func-param "Named parameter"
1089
    ///for setting ReachedMap object.
1081

	
1082
    ///\brief \ref named-templ-param "Named parameter" for setting
1083
    ///the reached map.
1090 1084
    ///
1091
    /// \ref named-func-param "Named parameter"
1092
    ///for setting ReachedMap object.
1085
    ///\ref named-templ-param "Named parameter" function for setting
1086
    ///the map that indicates which nodes are reached.
1093 1087
    template<class T>
1094 1088
    BfsWizard<SetReachedMapBase<T> > reachedMap(const T &t)
1095 1089
    {
1096 1090
      Base::_reached=reinterpret_cast<void*>(const_cast<T*>(&t));
1097 1091
      return BfsWizard<SetReachedMapBase<T> >(*this);
1098 1092
    }
1099 1093

	
1100 1094
    template<class T>
1101 1095
    struct SetDistMapBase : public Base {
1102 1096
      typedef T DistMap;
1103 1097
      static DistMap *createDistMap(const Digraph &) { return 0; };
1104 1098
      SetDistMapBase(const TR &b) : TR(b) {}
1105 1099
    };
1106
    ///\brief \ref named-func-param "Named parameter"
1107
    ///for setting DistMap object.
1100

	
1101
    ///\brief \ref named-templ-param "Named parameter" for setting
1102
    ///the distance map.
1108 1103
    ///
1109
    /// \ref named-func-param "Named parameter"
1110
    ///for setting DistMap object.
1104
    ///\ref named-templ-param "Named parameter" function for setting
1105
    ///the map that stores the distances of the nodes calculated
1106
    ///by the algorithm.
1111 1107
    template<class T>
1112 1108
    BfsWizard<SetDistMapBase<T> > distMap(const T &t)
1113 1109
    {
1114 1110
      Base::_dist=reinterpret_cast<void*>(const_cast<T*>(&t));
1115 1111
      return BfsWizard<SetDistMapBase<T> >(*this);
1116 1112
    }
1117 1113

	
1118 1114
    template<class T>
1119 1115
    struct SetProcessedMapBase : public Base {
1120 1116
      typedef T ProcessedMap;
1121 1117
      static ProcessedMap *createProcessedMap(const Digraph &) { return 0; };
1122 1118
      SetProcessedMapBase(const TR &b) : TR(b) {}
1123 1119
    };
1124
    ///\brief \ref named-func-param "Named parameter"
1125
    ///for setting ProcessedMap object.
1120

	
1121
    ///\brief \ref named-func-param "Named parameter" for setting
1122
    ///the processed map.
1126 1123
    ///
1127
    /// \ref named-func-param "Named parameter"
1128
    ///for setting ProcessedMap object.
1124
    ///\ref named-templ-param "Named parameter" function for setting
1125
    ///the map that indicates which nodes are processed.
1129 1126
    template<class T>
1130 1127
    BfsWizard<SetProcessedMapBase<T> > processedMap(const T &t)
1131 1128
    {
1132 1129
      Base::_processed=reinterpret_cast<void*>(const_cast<T*>(&t));
1133 1130
      return BfsWizard<SetProcessedMapBase<T> >(*this);
1134 1131
    }
1135 1132

	
1136 1133
    template<class T>
1137 1134
    struct SetPathBase : public Base {
1138 1135
      typedef T Path;
1139 1136
      SetPathBase(const TR &b) : TR(b) {}
1140 1137
    };
1141 1138
    ///\brief \ref named-func-param "Named parameter"
1142 1139
    ///for getting the shortest path to the target node.
1143 1140
    ///
1144 1141
    ///\ref named-func-param "Named parameter"
1145 1142
    ///for getting the shortest path to the target node.
1146 1143
    template<class T>
1147 1144
    BfsWizard<SetPathBase<T> > path(const T &t)
1148 1145
    {
1149 1146
      Base::_path=reinterpret_cast<void*>(const_cast<T*>(&t));
1150 1147
      return BfsWizard<SetPathBase<T> >(*this);
1151 1148
    }
1152 1149

	
1153 1150
    ///\brief \ref named-func-param "Named parameter"
1154 1151
    ///for getting the distance of the target node.
1155 1152
    ///
1156 1153
    ///\ref named-func-param "Named parameter"
1157 1154
    ///for getting the distance of the target node.
1158 1155
    BfsWizard dist(const int &d)
1159 1156
    {
1160 1157
      Base::_di=const_cast<int*>(&d);
1161 1158
      return *this;
1162 1159
    }
1163 1160

	
1164 1161
  };
1165 1162

	
1166 1163
  ///Function-type interface for BFS algorithm.
1167 1164

	
1168 1165
  /// \ingroup search
1169 1166
  ///Function-type interface for BFS algorithm.
1170 1167
  ///
1171 1168
  ///This function also has several \ref named-func-param "named parameters",
1172 1169
  ///they are declared as the members of class \ref BfsWizard.
1173 1170
  ///The following examples show how to use these parameters.
1174 1171
  ///\code
1175 1172
  ///  // Compute shortest path from node s to each node
1176 1173
  ///  bfs(g).predMap(preds).distMap(dists).run(s);
1177 1174
  ///
1178 1175
  ///  // Compute shortest path from s to t
1179 1176
  ///  bool reached = bfs(g).path(p).dist(d).run(s,t);
1180 1177
  ///\endcode
1181 1178
  ///\warning Don't forget to put the \ref BfsWizard::run(Node) "run()"
1182 1179
  ///to the end of the parameter list.
1183 1180
  ///\sa BfsWizard
1184 1181
  ///\sa Bfs
1185 1182
  template<class GR>
1186 1183
  BfsWizard<BfsWizardBase<GR> >
1187 1184
  bfs(const GR &digraph)
1188 1185
  {
1189 1186
    return BfsWizard<BfsWizardBase<GR> >(digraph);
1190 1187
  }
1191 1188

	
1192 1189
#ifdef DOXYGEN
1193 1190
  /// \brief Visitor class for BFS.
1194 1191
  ///
1195 1192
  /// This class defines the interface of the BfsVisit events, and
1196 1193
  /// it could be the base of a real visitor class.
1197 1194
  template <typename GR>
1198 1195
  struct BfsVisitor {
1199 1196
    typedef GR Digraph;
1200 1197
    typedef typename Digraph::Arc Arc;
1201 1198
    typedef typename Digraph::Node Node;
1202 1199
    /// \brief Called for the source node(s) of the BFS.
1203 1200
    ///
1204 1201
    /// This function is called for the source node(s) of the BFS.
1205 1202
    void start(const Node& node) {}
1206 1203
    /// \brief Called when a node is reached first time.
1207 1204
    ///
1208 1205
    /// This function is called when a node is reached first time.
1209 1206
    void reach(const Node& node) {}
1210 1207
    /// \brief Called when a node is processed.
1211 1208
    ///
1212 1209
    /// This function is called when a node is processed.
1213 1210
    void process(const Node& node) {}
1214 1211
    /// \brief Called when an arc reaches a new node.
1215 1212
    ///
1216 1213
    /// This function is called when the BFS finds an arc whose target node
1217 1214
    /// is not reached yet.
1218 1215
    void discover(const Arc& arc) {}
1219 1216
    /// \brief Called when an arc is examined but its target node is
1220 1217
    /// already discovered.
1221 1218
    ///
1222 1219
    /// This function is called when an arc is examined but its target node is
1223 1220
    /// already discovered.
1224 1221
    void examine(const Arc& arc) {}
1225 1222
  };
1226 1223
#else
1227 1224
  template <typename GR>
1228 1225
  struct BfsVisitor {
1229 1226
    typedef GR Digraph;
1230 1227
    typedef typename Digraph::Arc Arc;
1231 1228
    typedef typename Digraph::Node Node;
1232 1229
    void start(const Node&) {}
1233 1230
    void reach(const Node&) {}
1234 1231
    void process(const Node&) {}
1235 1232
    void discover(const Arc&) {}
1236 1233
    void examine(const Arc&) {}
1237 1234

	
1238 1235
    template <typename _Visitor>
1239 1236
    struct Constraints {
1240 1237
      void constraints() {
1241 1238
        Arc arc;
1242 1239
        Node node;
1243 1240
        visitor.start(node);
1244 1241
        visitor.reach(node);
1245 1242
        visitor.process(node);
1246 1243
        visitor.discover(arc);
1247 1244
        visitor.examine(arc);
1248 1245
      }
1249 1246
      _Visitor& visitor;
1250 1247
    };
1251 1248
  };
1252 1249
#endif
1253 1250

	
1254 1251
  /// \brief Default traits class of BfsVisit class.
1255 1252
  ///
1256 1253
  /// Default traits class of BfsVisit class.
1257 1254
  /// \tparam GR The type of the digraph the algorithm runs on.
1258 1255
  template<class GR>
1259 1256
  struct BfsVisitDefaultTraits {
1260 1257

	
1261 1258
    /// \brief The type of the digraph the algorithm runs on.
1262 1259
    typedef GR Digraph;
1263 1260

	
1264 1261
    /// \brief The type of the map that indicates which nodes are reached.
1265 1262
    ///
1266 1263
    /// The type of the map that indicates which nodes are reached.
1267
    /// It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
1264
    /// It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
1268 1265
    typedef typename Digraph::template NodeMap<bool> ReachedMap;
1269 1266

	
1270 1267
    /// \brief Instantiates a ReachedMap.
1271 1268
    ///
1272 1269
    /// This function instantiates a ReachedMap.
1273 1270
    /// \param digraph is the digraph, to which
1274 1271
    /// we would like to define the ReachedMap.
1275 1272
    static ReachedMap *createReachedMap(const Digraph &digraph) {
1276 1273
      return new ReachedMap(digraph);
1277 1274
    }
1278 1275

	
1279 1276
  };
1280 1277

	
1281 1278
  /// \ingroup search
1282 1279
  ///
1283 1280
  /// \brief BFS algorithm class with visitor interface.
1284 1281
  ///
1285 1282
  /// This class provides an efficient implementation of the BFS algorithm
1286 1283
  /// with visitor interface.
1287 1284
  ///
1288 1285
  /// The BfsVisit class provides an alternative interface to the Bfs
1289 1286
  /// class. It works with callback mechanism, the BfsVisit object calls
1290 1287
  /// the member functions of the \c Visitor class on every BFS event.
1291 1288
  ///
1292 1289
  /// This interface of the BFS algorithm should be used in special cases
1293 1290
  /// when extra actions have to be performed in connection with certain
1294 1291
  /// events of the BFS algorithm. Otherwise consider to use Bfs or bfs()
1295 1292
  /// instead.
1296 1293
  ///
1297 1294
  /// \tparam GR The type of the digraph the algorithm runs on.
1298 1295
  /// The default type is \ref ListDigraph.
1299 1296
  /// The value of GR is not used directly by \ref BfsVisit,
1300 1297
  /// it is only passed to \ref BfsVisitDefaultTraits.
1301 1298
  /// \tparam VS The Visitor type that is used by the algorithm.
1302 1299
  /// \ref BfsVisitor "BfsVisitor<GR>" is an empty visitor, which
1303 1300
  /// does not observe the BFS events. If you want to observe the BFS
1304 1301
  /// events, you should implement your own visitor class.
1305 1302
  /// \tparam TR Traits class to set various data types used by the
1306 1303
  /// algorithm. The default traits class is
1307 1304
  /// \ref BfsVisitDefaultTraits "BfsVisitDefaultTraits<GR>".
1308 1305
  /// See \ref BfsVisitDefaultTraits for the documentation of
1309 1306
  /// a BFS visit traits class.
1310 1307
#ifdef DOXYGEN
1311 1308
  template <typename GR, typename VS, typename TR>
1312 1309
#else
1313 1310
  template <typename GR = ListDigraph,
1314 1311
            typename VS = BfsVisitor<GR>,
1315 1312
            typename TR = BfsVisitDefaultTraits<GR> >
1316 1313
#endif
1317 1314
  class BfsVisit {
1318 1315
  public:
1319 1316

	
1320 1317
    ///The traits class.
1321 1318
    typedef TR Traits;
1322 1319

	
1323 1320
    ///The type of the digraph the algorithm runs on.
1324 1321
    typedef typename Traits::Digraph Digraph;
1325 1322

	
1326 1323
    ///The visitor type used by the algorithm.
1327 1324
    typedef VS Visitor;
1328 1325

	
1329 1326
    ///The type of the map that indicates which nodes are reached.
1330 1327
    typedef typename Traits::ReachedMap ReachedMap;
1331 1328

	
1332 1329
  private:
1333 1330

	
1334 1331
    typedef typename Digraph::Node Node;
1335 1332
    typedef typename Digraph::NodeIt NodeIt;
1336 1333
    typedef typename Digraph::Arc Arc;
1337 1334
    typedef typename Digraph::OutArcIt OutArcIt;
1338 1335

	
1339 1336
    //Pointer to the underlying digraph.
1340 1337
    const Digraph *_digraph;
1341 1338
    //Pointer to the visitor object.
1342 1339
    Visitor *_visitor;
1343 1340
    //Pointer to the map of reached status of the nodes.
1344 1341
    ReachedMap *_reached;
1345 1342
    //Indicates if _reached is locally allocated (true) or not.
1346 1343
    bool local_reached;
1347 1344

	
1348 1345
    std::vector<typename Digraph::Node> _list;
1349 1346
    int _list_front, _list_back;
1350 1347

	
1351 1348
    //Creates the maps if necessary.
1352 1349
    void create_maps() {
1353 1350
      if(!_reached) {
1354 1351
        local_reached = true;
1355 1352
        _reached = Traits::createReachedMap(*_digraph);
1356 1353
      }
1357 1354
    }
1358 1355

	
1359 1356
  protected:
1360 1357

	
1361 1358
    BfsVisit() {}
1362 1359

	
1363 1360
  public:
1364 1361

	
1365 1362
    typedef BfsVisit Create;
1366 1363

	
1367 1364
    /// \name Named Template Parameters
1368 1365

	
1369 1366
    ///@{
1370 1367
    template <class T>
1371 1368
    struct SetReachedMapTraits : public Traits {
1372 1369
      typedef T ReachedMap;
1373 1370
      static ReachedMap *createReachedMap(const Digraph &digraph) {
1374 1371
        LEMON_ASSERT(false, "ReachedMap is not initialized");
1375 1372
        return 0; // ignore warnings
1376 1373
      }
1377 1374
    };
1378 1375
    /// \brief \ref named-templ-param "Named parameter" for setting
1379 1376
    /// ReachedMap type.
1380 1377
    ///
1381 1378
    /// \ref named-templ-param "Named parameter" for setting ReachedMap type.
1382 1379
    template <class T>
1383 1380
    struct SetReachedMap : public BfsVisit< Digraph, Visitor,
1384 1381
                                            SetReachedMapTraits<T> > {
1385 1382
      typedef BfsVisit< Digraph, Visitor, SetReachedMapTraits<T> > Create;
1386 1383
    };
1387 1384
    ///@}
1388 1385

	
1389 1386
  public:
1390 1387

	
1391 1388
    /// \brief Constructor.
1392 1389
    ///
1393 1390
    /// Constructor.
1394 1391
    ///
1395 1392
    /// \param digraph The digraph the algorithm runs on.
1396 1393
    /// \param visitor The visitor object of the algorithm.
1397 1394
    BfsVisit(const Digraph& digraph, Visitor& visitor)
1398 1395
      : _digraph(&digraph), _visitor(&visitor),
1399 1396
        _reached(0), local_reached(false) {}
1400 1397

	
1401 1398
    /// \brief Destructor.
1402 1399
    ~BfsVisit() {
1403 1400
      if(local_reached) delete _reached;
1404 1401
    }
1405 1402

	
1406 1403
    /// \brief Sets the map that indicates which nodes are reached.
1407 1404
    ///
1408 1405
    /// Sets the map that indicates which nodes are reached.
1409 1406
    /// If you don't use this function before calling \ref run(Node) "run()"
1410 1407
    /// or \ref init(), an instance will be allocated automatically.
1411 1408
    /// The destructor deallocates this automatically allocated map,
1412 1409
    /// of course.
1413 1410
    /// \return <tt> (*this) </tt>
1414 1411
    BfsVisit &reachedMap(ReachedMap &m) {
1415 1412
      if(local_reached) {
1416 1413
        delete _reached;
1417 1414
        local_reached = false;
1418 1415
      }
1419 1416
      _reached = &m;
1420 1417
      return *this;
1421 1418
    }
1422 1419

	
1423 1420
  public:
1424 1421

	
1425 1422
    /// \name Execution Control
1426 1423
    /// The simplest way to execute the BFS algorithm is to use one of the
1427 1424
    /// member functions called \ref run(Node) "run()".\n
1428
    /// If you need more control on the execution, first you have to call
1429
    /// \ref init(), then you can add several source nodes with
1425
    /// If you need better control on the execution, you have to call
1426
    /// \ref init() first, then you can add several source nodes with
1430 1427
    /// \ref addSource(). Finally the actual path computation can be
1431 1428
    /// performed with one of the \ref start() functions.
1432 1429

	
1433 1430
    /// @{
1434 1431

	
1435 1432
    /// \brief Initializes the internal data structures.
1436 1433
    ///
1437 1434
    /// Initializes the internal data structures.
1438 1435
    void init() {
1439 1436
      create_maps();
1440 1437
      _list.resize(countNodes(*_digraph));
1441 1438
      _list_front = _list_back = -1;
1442 1439
      for (NodeIt u(*_digraph) ; u != INVALID ; ++u) {
1443 1440
        _reached->set(u, false);
1444 1441
      }
1445 1442
    }
1446 1443

	
1447 1444
    /// \brief Adds a new source node.
1448 1445
    ///
1449 1446
    /// Adds a new source node to the set of nodes to be processed.
1450 1447
    void addSource(Node s) {
1451 1448
      if(!(*_reached)[s]) {
1452 1449
          _reached->set(s,true);
1453 1450
          _visitor->start(s);
1454 1451
          _visitor->reach(s);
1455 1452
          _list[++_list_back] = s;
1456 1453
        }
1457 1454
    }
1458 1455

	
1459 1456
    /// \brief Processes the next node.
1460 1457
    ///
1461 1458
    /// Processes the next node.
1462 1459
    ///
1463 1460
    /// \return The processed node.
1464 1461
    ///
1465 1462
    /// \pre The queue must not be empty.
1466 1463
    Node processNextNode() {
1467 1464
      Node n = _list[++_list_front];
1468 1465
      _visitor->process(n);
1469 1466
      Arc e;
1470 1467
      for (_digraph->firstOut(e, n); e != INVALID; _digraph->nextOut(e)) {
1471 1468
        Node m = _digraph->target(e);
1472 1469
        if (!(*_reached)[m]) {
1473 1470
          _visitor->discover(e);
1474 1471
          _visitor->reach(m);
1475 1472
          _reached->set(m, true);
1476 1473
          _list[++_list_back] = m;
1477 1474
        } else {
1478 1475
          _visitor->examine(e);
1479 1476
        }
1480 1477
      }
1481 1478
      return n;
1482 1479
    }
1483 1480

	
1484 1481
    /// \brief Processes the next node.
1485 1482
    ///
1486 1483
    /// Processes the next node and checks if the given target node
1487 1484
    /// is reached. If the target node is reachable from the processed
1488 1485
    /// node, then the \c reach parameter will be set to \c true.
1489 1486
    ///
1490 1487
    /// \param target The target node.
1491 1488
    /// \retval reach Indicates if the target node is reached.
1492 1489
    /// It should be initially \c false.
1493 1490
    ///
1494 1491
    /// \return The processed node.
1495 1492
    ///
1496 1493
    /// \pre The queue must not be empty.
1497 1494
    Node processNextNode(Node target, bool& reach) {
1498 1495
      Node n = _list[++_list_front];
1499 1496
      _visitor->process(n);
1500 1497
      Arc e;
1501 1498
      for (_digraph->firstOut(e, n); e != INVALID; _digraph->nextOut(e)) {
1502 1499
        Node m = _digraph->target(e);
1503 1500
        if (!(*_reached)[m]) {
1504 1501
          _visitor->discover(e);
1505 1502
          _visitor->reach(m);
1506 1503
          _reached->set(m, true);
1507 1504
          _list[++_list_back] = m;
1508 1505
          reach = reach || (target == m);
1509 1506
        } else {
1510 1507
          _visitor->examine(e);
1511 1508
        }
1512 1509
      }
1513 1510
      return n;
1514 1511
    }
1515 1512

	
1516 1513
    /// \brief Processes the next node.
1517 1514
    ///
1518 1515
    /// Processes the next node and checks if at least one of reached
1519 1516
    /// nodes has \c true value in the \c nm node map. If one node
1520 1517
    /// with \c true value is reachable from the processed node, then the
1521 1518
    /// \c rnode parameter will be set to the first of such nodes.
1522 1519
    ///
1523 1520
    /// \param nm A \c bool (or convertible) node map that indicates the
1524 1521
    /// possible targets.
1525 1522
    /// \retval rnode The reached target node.
1526 1523
    /// It should be initially \c INVALID.
1527 1524
    ///
1528 1525
    /// \return The processed node.
1529 1526
    ///
1530 1527
    /// \pre The queue must not be empty.
1531 1528
    template <typename NM>
1532 1529
    Node processNextNode(const NM& nm, Node& rnode) {
1533 1530
      Node n = _list[++_list_front];
1534 1531
      _visitor->process(n);
1535 1532
      Arc e;
1536 1533
      for (_digraph->firstOut(e, n); e != INVALID; _digraph->nextOut(e)) {
1537 1534
        Node m = _digraph->target(e);
1538 1535
        if (!(*_reached)[m]) {
1539 1536
          _visitor->discover(e);
1540 1537
          _visitor->reach(m);
1541 1538
          _reached->set(m, true);
1542 1539
          _list[++_list_back] = m;
1543 1540
          if (nm[m] && rnode == INVALID) rnode = m;
1544 1541
        } else {
1545 1542
          _visitor->examine(e);
1546 1543
        }
1547 1544
      }
1548 1545
      return n;
1549 1546
    }
1550 1547

	
1551 1548
    /// \brief The next node to be processed.
1552 1549
    ///
1553 1550
    /// Returns the next node to be processed or \c INVALID if the queue
1554 1551
    /// is empty.
1555 1552
    Node nextNode() const {
1556 1553
      return _list_front != _list_back ? _list[_list_front + 1] : INVALID;
1557 1554
    }
1558 1555

	
1559 1556
    /// \brief Returns \c false if there are nodes
1560 1557
    /// to be processed.
1561 1558
    ///
1562 1559
    /// Returns \c false if there are nodes
1563 1560
    /// to be processed in the queue.
1564 1561
    bool emptyQueue() const { return _list_front == _list_back; }
1565 1562

	
1566 1563
    /// \brief Returns the number of the nodes to be processed.
1567 1564
    ///
1568 1565
    /// Returns the number of the nodes to be processed in the queue.
1569 1566
    int queueSize() const { return _list_back - _list_front; }
1570 1567

	
1571 1568
    /// \brief Executes the algorithm.
1572 1569
    ///
1573 1570
    /// Executes the algorithm.
1574 1571
    ///
1575 1572
    /// This method runs the %BFS algorithm from the root node(s)
1576 1573
    /// in order to compute the shortest path to each node.
1577 1574
    ///
1578 1575
    /// The algorithm computes
1579 1576
    /// - the shortest path tree (forest),
1580 1577
    /// - the distance of each node from the root(s).
1581 1578
    ///
1582 1579
    /// \pre init() must be called and at least one root node should be added
1583 1580
    /// with addSource() before using this function.
1584 1581
    ///
1585 1582
    /// \note <tt>b.start()</tt> is just a shortcut of the following code.
1586 1583
    /// \code
1587 1584
    ///   while ( !b.emptyQueue() ) {
1588 1585
    ///     b.processNextNode();
1589 1586
    ///   }
1590 1587
    /// \endcode
1591 1588
    void start() {
1592 1589
      while ( !emptyQueue() ) processNextNode();
1593 1590
    }
1594 1591

	
1595 1592
    /// \brief Executes the algorithm until the given target node is reached.
1596 1593
    ///
1597 1594
    /// Executes the algorithm until the given target node is reached.
1598 1595
    ///
1599 1596
    /// This method runs the %BFS algorithm from the root node(s)
1600 1597
    /// in order to compute the shortest path to \c t.
1601 1598
    ///
1602 1599
    /// The algorithm computes
1603 1600
    /// - the shortest path to \c t,
1604 1601
    /// - the distance of \c t from the root(s).
1605 1602
    ///
1606 1603
    /// \pre init() must be called and at least one root node should be
1607 1604
    /// added with addSource() before using this function.
1608 1605
    ///
1609 1606
    /// \note <tt>b.start(t)</tt> is just a shortcut of the following code.
1610 1607
    /// \code
1611 1608
    ///   bool reach = false;
1612 1609
    ///   while ( !b.emptyQueue() && !reach ) {
1613 1610
    ///     b.processNextNode(t, reach);
1614 1611
    ///   }
1615 1612
    /// \endcode
1616 1613
    void start(Node t) {
1617 1614
      bool reach = false;
1618 1615
      while ( !emptyQueue() && !reach ) processNextNode(t, reach);
1619 1616
    }
1620 1617

	
1621 1618
    /// \brief Executes the algorithm until a condition is met.
1622 1619
    ///
1623 1620
    /// Executes the algorithm until a condition is met.
1624 1621
    ///
1625 1622
    /// This method runs the %BFS algorithm from the root node(s) in
1626 1623
    /// order to compute the shortest path to a node \c v with
1627 1624
    /// <tt>nm[v]</tt> true, if such a node can be found.
1628 1625
    ///
1629 1626
    /// \param nm must be a bool (or convertible) node map. The
1630 1627
    /// algorithm will stop when it reaches a node \c v with
1631 1628
    /// <tt>nm[v]</tt> true.
1632 1629
    ///
1633 1630
    /// \return The reached node \c v with <tt>nm[v]</tt> true or
1634 1631
    /// \c INVALID if no such node was found.
1635 1632
    ///
1636 1633
    /// \pre init() must be called and at least one root node should be
1637 1634
    /// added with addSource() before using this function.
1638 1635
    ///
1639 1636
    /// \note <tt>b.start(nm)</tt> is just a shortcut of the following code.
1640 1637
    /// \code
1641 1638
    ///   Node rnode = INVALID;
1642 1639
    ///   while ( !b.emptyQueue() && rnode == INVALID ) {
1643 1640
    ///     b.processNextNode(nm, rnode);
1644 1641
    ///   }
1645 1642
    ///   return rnode;
1646 1643
    /// \endcode
1647 1644
    template <typename NM>
1648 1645
    Node start(const NM &nm) {
1649 1646
      Node rnode = INVALID;
1650 1647
      while ( !emptyQueue() && rnode == INVALID ) {
1651 1648
        processNextNode(nm, rnode);
1652 1649
      }
1653 1650
      return rnode;
1654 1651
    }
1655 1652

	
1656 1653
    /// \brief Runs the algorithm from the given source node.
1657 1654
    ///
1658 1655
    /// This method runs the %BFS algorithm from node \c s
1659 1656
    /// in order to compute the shortest path to each node.
1660 1657
    ///
1661 1658
    /// The algorithm computes
1662 1659
    /// - the shortest path tree,
1663 1660
    /// - the distance of each node from the root.
1664 1661
    ///
1665 1662
    /// \note <tt>b.run(s)</tt> is just a shortcut of the following code.
1666 1663
    ///\code
1667 1664
    ///   b.init();
1668 1665
    ///   b.addSource(s);
1669 1666
    ///   b.start();
1670 1667
    ///\endcode
1671 1668
    void run(Node s) {
1672 1669
      init();
1673 1670
      addSource(s);
1674 1671
      start();
1675 1672
    }
1676 1673

	
1677 1674
    /// \brief Finds the shortest path between \c s and \c t.
1678 1675
    ///
1679 1676
    /// This method runs the %BFS algorithm from node \c s
1680 1677
    /// in order to compute the shortest path to node \c t
1681 1678
    /// (it stops searching when \c t is processed).
1682 1679
    ///
1683 1680
    /// \return \c true if \c t is reachable form \c s.
1684 1681
    ///
1685 1682
    /// \note Apart from the return value, <tt>b.run(s,t)</tt> is just a
1686 1683
    /// shortcut of the following code.
1687 1684
    ///\code
1688 1685
    ///   b.init();
1689 1686
    ///   b.addSource(s);
1690 1687
    ///   b.start(t);
1691 1688
    ///\endcode
1692 1689
    bool run(Node s,Node t) {
1693 1690
      init();
1694 1691
      addSource(s);
1695 1692
      start(t);
1696 1693
      return reached(t);
1697 1694
    }
1698 1695

	
1699 1696
    /// \brief Runs the algorithm to visit all nodes in the digraph.
1700 1697
    ///
1701 1698
    /// This method runs the %BFS algorithm in order to
1702 1699
    /// compute the shortest path to each node.
1703 1700
    ///
1704 1701
    /// The algorithm computes
1705 1702
    /// - the shortest path tree (forest),
1706 1703
    /// - the distance of each node from the root(s).
1707 1704
    ///
1708 1705
    /// \note <tt>b.run(s)</tt> is just a shortcut of the following code.
1709 1706
    ///\code
1710 1707
    ///  b.init();
1711 1708
    ///  for (NodeIt n(gr); n != INVALID; ++n) {
1712 1709
    ///    if (!b.reached(n)) {
1713 1710
    ///      b.addSource(n);
1714 1711
    ///      b.start();
1715 1712
    ///    }
1716 1713
    ///  }
1717 1714
    ///\endcode
1718 1715
    void run() {
1719 1716
      init();
1720 1717
      for (NodeIt it(*_digraph); it != INVALID; ++it) {
1721 1718
        if (!reached(it)) {
1722 1719
          addSource(it);
1723 1720
          start();
1724 1721
        }
1725 1722
      }
1726 1723
    }
1727 1724

	
1728 1725
    ///@}
1729 1726

	
1730 1727
    /// \name Query Functions
1731 1728
    /// The results of the BFS algorithm can be obtained using these
1732 1729
    /// functions.\n
1733 1730
    /// Either \ref run(Node) "run()" or \ref start() should be called
1734 1731
    /// before using them.
1735 1732

	
1736 1733
    ///@{
1737 1734

	
1738
    /// \brief Checks if a node is reached from the root(s).
1735
    /// \brief Checks if the given node is reached from the root(s).
1739 1736
    ///
1740 1737
    /// Returns \c true if \c v is reached from the root(s).
1741 1738
    ///
1742 1739
    /// \pre Either \ref run(Node) "run()" or \ref init()
1743 1740
    /// must be called before using this function.
1744 1741
    bool reached(Node v) const { return (*_reached)[v]; }
1745 1742

	
1746 1743
    ///@}
1747 1744

	
1748 1745
  };
1749 1746

	
1750 1747
} //END OF NAMESPACE LEMON
1751 1748

	
1752 1749
#endif
Ignore white space 6 line context
1 1
/* -*- mode: C++; indent-tabs-mode: nil; -*-
2 2
 *
3 3
 * This file is a part of LEMON, a generic C++ optimization library.
4 4
 *
5 5
 * Copyright (C) 2003-2009
6 6
 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 7
 * (Egervary Research Group on Combinatorial Optimization, EGRES).
8 8
 *
9 9
 * Permission to use, modify and distribute this software is granted
10 10
 * provided that this copyright notice appears in all copies. For
11 11
 * precise terms see the accompanying LICENSE file.
12 12
 *
13 13
 * This software is provided "AS IS" with no warranty of any kind,
14 14
 * express or implied, and with no claim as to its suitability for any
15 15
 * purpose.
16 16
 *
17 17
 */
18 18

	
19 19
#ifndef LEMON_BIN_HEAP_H
20 20
#define LEMON_BIN_HEAP_H
21 21

	
22
///\ingroup auxdat
22
///\ingroup heaps
23 23
///\file
24
///\brief Binary Heap implementation.
24
///\brief Binary heap implementation.
25 25

	
26 26
#include <vector>
27 27
#include <utility>
28 28
#include <functional>
29 29

	
30 30
namespace lemon {
31 31

	
32
  ///\ingroup auxdat
32
  /// \ingroup heaps
33 33
  ///
34
  ///\brief A Binary Heap implementation.
34
  /// \brief Binary heap data structure.
35 35
  ///
36
  ///This class implements the \e binary \e heap data structure.
36
  /// This class implements the \e binary \e heap data structure.
37
  /// It fully conforms to the \ref concepts::Heap "heap concept".
37 38
  ///
38
  ///A \e heap is a data structure for storing items with specified values
39
  ///called \e priorities in such a way that finding the item with minimum
40
  ///priority is efficient. \c CMP specifies the ordering of the priorities.
41
  ///In a heap one can change the priority of an item, add or erase an
42
  ///item, etc.
43
  ///
44
  ///\tparam PR Type of the priority of the items.
45
  ///\tparam IM A read and writable item map with int values, used internally
46
  ///to handle the cross references.
47
  ///\tparam CMP A functor class for the ordering of the priorities.
48
  ///The default is \c std::less<PR>.
49
  ///
50
  ///\sa FibHeap
51
  ///\sa Dijkstra
39
  /// \tparam PR Type of the priorities of the items.
40
  /// \tparam IM A read-writable item map with \c int values, used
41
  /// internally to handle the cross references.
42
  /// \tparam CMP A functor class for comparing the priorities.
43
  /// The default is \c std::less<PR>.
44
#ifdef DOXYGEN
45
  template <typename PR, typename IM, typename CMP>
46
#else
52 47
  template <typename PR, typename IM, typename CMP = std::less<PR> >
48
#endif
53 49
  class BinHeap {
50
  public:
54 51

	
55
  public:
56
    ///\e
52
    /// Type of the item-int map.
57 53
    typedef IM ItemIntMap;
58
    ///\e
54
    /// Type of the priorities.
59 55
    typedef PR Prio;
60
    ///\e
56
    /// Type of the items stored in the heap.
61 57
    typedef typename ItemIntMap::Key Item;
62
    ///\e
58
    /// Type of the item-priority pairs.
63 59
    typedef std::pair<Item,Prio> Pair;
64
    ///\e
60
    /// Functor type for comparing the priorities.
65 61
    typedef CMP Compare;
66 62

	
67
    /// \brief Type to represent the items states.
63
    /// \brief Type to represent the states of the items.
68 64
    ///
69
    /// Each Item element have a state associated to it. It may be "in heap",
70
    /// "pre heap" or "post heap". The latter two are indifferent from the
65
    /// Each item has a state associated to it. It can be "in heap",
66
    /// "pre-heap" or "post-heap". The latter two are indifferent from the
71 67
    /// heap's point of view, but may be useful to the user.
72 68
    ///
73 69
    /// The item-int map must be initialized in such way that it assigns
74 70
    /// \c PRE_HEAP (<tt>-1</tt>) to any element to be put in the heap.
75 71
    enum State {
76 72
      IN_HEAP = 0,    ///< = 0.
77 73
      PRE_HEAP = -1,  ///< = -1.
78 74
      POST_HEAP = -2  ///< = -2.
79 75
    };
80 76

	
81 77
  private:
82 78
    std::vector<Pair> _data;
83 79
    Compare _comp;
84 80
    ItemIntMap &_iim;
85 81

	
86 82
  public:
87
    /// \brief The constructor.
83

	
84
    /// \brief Constructor.
88 85
    ///
89
    /// The constructor.
90
    /// \param map should be given to the constructor, since it is used
91
    /// internally to handle the cross references. The value of the map
92
    /// must be \c PRE_HEAP (<tt>-1</tt>) for every item.
86
    /// Constructor.
87
    /// \param map A map that assigns \c int values to the items.
88
    /// It is used internally to handle the cross references.
89
    /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
93 90
    explicit BinHeap(ItemIntMap &map) : _iim(map) {}
94 91

	
95
    /// \brief The constructor.
92
    /// \brief Constructor.
96 93
    ///
97
    /// The constructor.
98
    /// \param map should be given to the constructor, since it is used
99
    /// internally to handle the cross references. The value of the map
100
    /// should be PRE_HEAP (-1) for each element.
101
    ///
102
    /// \param comp The comparator function object.
94
    /// Constructor.
95
    /// \param map A map that assigns \c int values to the items.
96
    /// It is used internally to handle the cross references.
97
    /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
98
    /// \param comp The function object used for comparing the priorities.
103 99
    BinHeap(ItemIntMap &map, const Compare &comp)
104 100
      : _iim(map), _comp(comp) {}
105 101

	
106 102

	
107
    /// The number of items stored in the heap.
103
    /// \brief The number of items stored in the heap.
108 104
    ///
109
    /// \brief Returns the number of items stored in the heap.
105
    /// This function returns the number of items stored in the heap.
110 106
    int size() const { return _data.size(); }
111 107

	
112
    /// \brief Checks if the heap stores no items.
108
    /// \brief Check if the heap is empty.
113 109
    ///
114
    /// Returns \c true if and only if the heap stores no items.
110
    /// This function returns \c true if the heap is empty.
115 111
    bool empty() const { return _data.empty(); }
116 112

	
117
    /// \brief Make empty this heap.
113
    /// \brief Make the heap empty.
118 114
    ///
119
    /// Make empty this heap. It does not change the cross reference map.
120
    /// If you want to reuse what is not surely empty you should first clear
121
    /// the heap and after that you should set the cross reference map for
122
    /// each item to \c PRE_HEAP.
115
    /// This functon makes the heap empty.
116
    /// It does not change the cross reference map. If you want to reuse
117
    /// a heap that is not surely empty, you should first clear it and
118
    /// then you should set the cross reference map to \c PRE_HEAP
119
    /// for each item.
123 120
    void clear() {
124 121
      _data.clear();
125 122
    }
126 123

	
127 124
  private:
128 125
    static int parent(int i) { return (i-1)/2; }
129 126

	
130
    static int second_child(int i) { return 2*i+2; }
127
    static int secondChild(int i) { return 2*i+2; }
131 128
    bool less(const Pair &p1, const Pair &p2) const {
132 129
      return _comp(p1.second, p2.second);
133 130
    }
134 131

	
135
    int bubble_up(int hole, Pair p) {
132
    int bubbleUp(int hole, Pair p) {
136 133
      int par = parent(hole);
137 134
      while( hole>0 && less(p,_data[par]) ) {
138 135
        move(_data[par],hole);
139 136
        hole = par;
140 137
        par = parent(hole);
141 138
      }
142 139
      move(p, hole);
143 140
      return hole;
144 141
    }
145 142

	
146
    int bubble_down(int hole, Pair p, int length) {
147
      int child = second_child(hole);
143
    int bubbleDown(int hole, Pair p, int length) {
144
      int child = secondChild(hole);
148 145
      while(child < length) {
149 146
        if( less(_data[child-1], _data[child]) ) {
150 147
          --child;
151 148
        }
152 149
        if( !less(_data[child], p) )
153 150
          goto ok;
154 151
        move(_data[child], hole);
155 152
        hole = child;
156
        child = second_child(hole);
153
        child = secondChild(hole);
157 154
      }
158 155
      child--;
159 156
      if( child<length && less(_data[child], p) ) {
160 157
        move(_data[child], hole);
161 158
        hole=child;
162 159
      }
163 160
    ok:
164 161
      move(p, hole);
165 162
      return hole;
166 163
    }
167 164

	
168 165
    void move(const Pair &p, int i) {
169 166
      _data[i] = p;
170 167
      _iim.set(p.first, i);
171 168
    }
172 169

	
173 170
  public:
171

	
174 172
    /// \brief Insert a pair of item and priority into the heap.
175 173
    ///
176
    /// Adds \c p.first to the heap with priority \c p.second.
174
    /// This function inserts \c p.first to the heap with priority
175
    /// \c p.second.
177 176
    /// \param p The pair to insert.
177
    /// \pre \c p.first must not be stored in the heap.
178 178
    void push(const Pair &p) {
179 179
      int n = _data.size();
180 180
      _data.resize(n+1);
181
      bubble_up(n, p);
181
      bubbleUp(n, p);
182 182
    }
183 183

	
184
    /// \brief Insert an item into the heap with the given heap.
184
    /// \brief Insert an item into the heap with the given priority.
185 185
    ///
186
    /// Adds \c i to the heap with priority \c p.
186
    /// This function inserts the given item into the heap with the
187
    /// given priority.
187 188
    /// \param i The item to insert.
188 189
    /// \param p The priority of the item.
190
    /// \pre \e i must not be stored in the heap.
189 191
    void push(const Item &i, const Prio &p) { push(Pair(i,p)); }
190 192

	
191
    /// \brief Returns the item with minimum priority relative to \c Compare.
193
    /// \brief Return the item having minimum priority.
192 194
    ///
193
    /// This method returns the item with minimum priority relative to \c
194
    /// Compare.
195
    /// \pre The heap must be nonempty.
195
    /// This function returns the item having minimum priority.
196
    /// \pre The heap must be non-empty.
196 197
    Item top() const {
197 198
      return _data[0].first;
198 199
    }
199 200

	
200
    /// \brief Returns the minimum priority relative to \c Compare.
201
    /// \brief The minimum priority.
201 202
    ///
202
    /// It returns the minimum priority relative to \c Compare.
203
    /// \pre The heap must be nonempty.
203
    /// This function returns the minimum priority.
204
    /// \pre The heap must be non-empty.
204 205
    Prio prio() const {
205 206
      return _data[0].second;
206 207
    }
207 208

	
208
    /// \brief Deletes the item with minimum priority relative to \c Compare.
209
    /// \brief Remove the item having minimum priority.
209 210
    ///
210
    /// This method deletes the item with minimum priority relative to \c
211
    /// Compare from the heap.
211
    /// This function removes the item having minimum priority.
212 212
    /// \pre The heap must be non-empty.
213 213
    void pop() {
214 214
      int n = _data.size()-1;
215 215
      _iim.set(_data[0].first, POST_HEAP);
216 216
      if (n > 0) {
217
        bubble_down(0, _data[n], n);
217
        bubbleDown(0, _data[n], n);
218 218
      }
219 219
      _data.pop_back();
220 220
    }
221 221

	
222
    /// \brief Deletes \c i from the heap.
222
    /// \brief Remove the given item from the heap.
223 223
    ///
224
    /// This method deletes item \c i from the heap.
225
    /// \param i The item to erase.
226
    /// \pre The item should be in the heap.
224
    /// This function removes the given item from the heap if it is
225
    /// already stored.
226
    /// \param i The item to delete.
227
    /// \pre \e i must be in the heap.
227 228
    void erase(const Item &i) {
228 229
      int h = _iim[i];
229 230
      int n = _data.size()-1;
230 231
      _iim.set(_data[h].first, POST_HEAP);
231 232
      if( h < n ) {
232
        if ( bubble_up(h, _data[n]) == h) {
233
          bubble_down(h, _data[n], n);
233
        if ( bubbleUp(h, _data[n]) == h) {
234
          bubbleDown(h, _data[n], n);
234 235
        }
235 236
      }
236 237
      _data.pop_back();
237 238
    }
238 239

	
239

	
240
    /// \brief Returns the priority of \c i.
240
    /// \brief The priority of the given item.
241 241
    ///
242
    /// This function returns the priority of item \c i.
242
    /// This function returns the priority of the given item.
243 243
    /// \param i The item.
244
    /// \pre \c i must be in the heap.
244
    /// \pre \e i must be in the heap.
245 245
    Prio operator[](const Item &i) const {
246 246
      int idx = _iim[i];
247 247
      return _data[idx].second;
248 248
    }
249 249

	
250
    /// \brief \c i gets to the heap with priority \c p independently
251
    /// if \c i was already there.
250
    /// \brief Set the priority of an item or insert it, if it is
251
    /// not stored in the heap.
252 252
    ///
253
    /// This method calls \ref push(\c i, \c p) if \c i is not stored
254
    /// in the heap and sets the priority of \c i to \c p otherwise.
253
    /// This method sets the priority of the given item if it is
254
    /// already stored in the heap. Otherwise it inserts the given
255
    /// item into the heap with the given priority.
255 256
    /// \param i The item.
256 257
    /// \param p The priority.
257 258
    void set(const Item &i, const Prio &p) {
258 259
      int idx = _iim[i];
259 260
      if( idx < 0 ) {
260 261
        push(i,p);
261 262
      }
262 263
      else if( _comp(p, _data[idx].second) ) {
263
        bubble_up(idx, Pair(i,p));
264
        bubbleUp(idx, Pair(i,p));
264 265
      }
265 266
      else {
266
        bubble_down(idx, Pair(i,p), _data.size());
267
        bubbleDown(idx, Pair(i,p), _data.size());
267 268
      }
268 269
    }
269 270

	
270
    /// \brief Decreases the priority of \c i to \c p.
271
    /// \brief Decrease the priority of an item to the given value.
271 272
    ///
272
    /// This method decreases the priority of item \c i to \c p.
273
    /// This function decreases the priority of an item to the given value.
273 274
    /// \param i The item.
274 275
    /// \param p The priority.
275
    /// \pre \c i must be stored in the heap with priority at least \c
276
    /// p relative to \c Compare.
276
    /// \pre \e i must be stored in the heap with priority at least \e p.
277 277
    void decrease(const Item &i, const Prio &p) {
278 278
      int idx = _iim[i];
279
      bubble_up(idx, Pair(i,p));
279
      bubbleUp(idx, Pair(i,p));
280 280
    }
281 281

	
282
    /// \brief Increases the priority of \c i to \c p.
282
    /// \brief Increase the priority of an item to the given value.
283 283
    ///
284
    /// This method sets the priority of item \c i to \c p.
284
    /// This function increases the priority of an item to the given value.
285 285
    /// \param i The item.
286 286
    /// \param p The priority.
287
    /// \pre \c i must be stored in the heap with priority at most \c
288
    /// p relative to \c Compare.
287
    /// \pre \e i must be stored in the heap with priority at most \e p.
289 288
    void increase(const Item &i, const Prio &p) {
290 289
      int idx = _iim[i];
291
      bubble_down(idx, Pair(i,p), _data.size());
290
      bubbleDown(idx, Pair(i,p), _data.size());
292 291
    }
293 292

	
294
    /// \brief Returns if \c item is in, has already been in, or has
295
    /// never been in the heap.
293
    /// \brief Return the state of an item.
296 294
    ///
297
    /// This method returns PRE_HEAP if \c item has never been in the
298
    /// heap, IN_HEAP if it is in the heap at the moment, and POST_HEAP
299
    /// otherwise. In the latter case it is possible that \c item will
300
    /// get back to the heap again.
295
    /// This method returns \c PRE_HEAP if the given item has never
296
    /// been in the heap, \c IN_HEAP if it is in the heap at the moment,
297
    /// and \c POST_HEAP otherwise.
298
    /// In the latter case it is possible that the item will get back
299
    /// to the heap again.
301 300
    /// \param i The item.
302 301
    State state(const Item &i) const {
303 302
      int s = _iim[i];
304 303
      if( s>=0 )
305 304
        s=0;
306 305
      return State(s);
307 306
    }
308 307

	
309
    /// \brief Sets the state of the \c item in the heap.
308
    /// \brief Set the state of an item in the heap.
310 309
    ///
311
    /// Sets the state of the \c item in the heap. It can be used to
312
    /// manually clear the heap when it is important to achive the
313
    /// better time complexity.
310
    /// This function sets the state of the given item in the heap.
311
    /// It can be used to manually clear the heap when it is important
312
    /// to achive better time complexity.
314 313
    /// \param i The item.
315 314
    /// \param st The state. It should not be \c IN_HEAP.
316 315
    void state(const Item& i, State st) {
317 316
      switch (st) {
318 317
      case POST_HEAP:
319 318
      case PRE_HEAP:
320 319
        if (state(i) == IN_HEAP) {
321 320
          erase(i);
322 321
        }
323 322
        _iim[i] = st;
324 323
        break;
325 324
      case IN_HEAP:
326 325
        break;
327 326
      }
328 327
    }
329 328

	
330
    /// \brief Replaces an item in the heap.
329
    /// \brief Replace an item in the heap.
331 330
    ///
332
    /// The \c i item is replaced with \c j item. The \c i item should
333
    /// be in the heap, while the \c j should be out of the heap. The
334
    /// \c i item will out of the heap and \c j will be in the heap
335
    /// with the same prioriority as prevoiusly the \c i item.
331
    /// This function replaces item \c i with item \c j.
332
    /// Item \c i must be in the heap, while \c j must be out of the heap.
333
    /// After calling this method, item \c i will be out of the
334
    /// heap and \c j will be in the heap with the same prioriority
335
    /// as item \c i had before.
336 336
    void replace(const Item& i, const Item& j) {
337 337
      int idx = _iim[i];
338 338
      _iim.set(i, _iim[j]);
339 339
      _iim.set(j, idx);
340 340
      _data[idx].first = j;
341 341
    }
342 342

	
343 343
  }; // class BinHeap
344 344

	
345 345
} // namespace lemon
346 346

	
347 347
#endif // LEMON_BIN_HEAP_H
Ignore white space 6 line context
1 1
/* -*- C++ -*-
2 2
 *
3 3
 * This file is a part of LEMON, a generic C++ optimization library
4 4
 *
5 5
 * Copyright (C) 2003-2008
6 6
 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 7
 * (Egervary Research Group on Combinatorial Optimization, EGRES).
8 8
 *
9 9
 * Permission to use, modify and distribute this software is granted
10 10
 * provided that this copyright notice appears in all copies. For
11 11
 * precise terms see the accompanying LICENSE file.
12 12
 *
13 13
 * This software is provided "AS IS" with no warranty of any kind,
14 14
 * express or implied, and with no claim as to its suitability for any
15 15
 * purpose.
16 16
 *
17 17
 */
18 18

	
19 19
#ifndef LEMON_BITS_EDGE_SET_EXTENDER_H
20 20
#define LEMON_BITS_EDGE_SET_EXTENDER_H
21 21

	
22 22
#include <lemon/core.h>
23 23
#include <lemon/error.h>
24 24
#include <lemon/bits/default_map.h>
25 25
#include <lemon/bits/map_extender.h>
26 26

	
27 27
//\ingroup digraphbits
28 28
//\file
29 29
//\brief Extenders for the arc set types
30 30
namespace lemon {
31 31

	
32 32
  // \ingroup digraphbits
33 33
  //
34 34
  // \brief Extender for the ArcSets
35 35
  template <typename Base>
36 36
  class ArcSetExtender : public Base {
37 37
    typedef Base Parent;
38 38

	
39 39
  public:
40 40

	
41 41
    typedef ArcSetExtender Digraph;
42 42

	
43 43
    // Base extensions
44 44

	
45 45
    typedef typename Parent::Node Node;
46 46
    typedef typename Parent::Arc Arc;
47 47

	
48 48
    int maxId(Node) const {
49 49
      return Parent::maxNodeId();
50 50
    }
51 51

	
52 52
    int maxId(Arc) const {
53 53
      return Parent::maxArcId();
54 54
    }
55 55

	
56 56
    Node fromId(int id, Node) const {
57 57
      return Parent::nodeFromId(id);
58 58
    }
59 59

	
60 60
    Arc fromId(int id, Arc) const {
61 61
      return Parent::arcFromId(id);
62 62
    }
63 63

	
64 64
    Node oppositeNode(const Node &n, const Arc &e) const {
65 65
      if (n == Parent::source(e))
66 66
	return Parent::target(e);
67 67
      else if(n==Parent::target(e))
68 68
	return Parent::source(e);
69 69
      else
70 70
	return INVALID;
71 71
    }
72 72

	
73 73

	
74 74
    // Alteration notifier extensions
75 75

	
76 76
    // The arc observer registry.
77 77
    typedef AlterationNotifier<ArcSetExtender, Arc> ArcNotifier;
78 78

	
79 79
  protected:
80 80

	
81 81
    mutable ArcNotifier arc_notifier;
82 82

	
83 83
  public:
84 84

	
85 85
    using Parent::notifier;
86 86

	
87 87
    // Gives back the arc alteration notifier.
88 88
    ArcNotifier& notifier(Arc) const {
89 89
      return arc_notifier;
90 90
    }
91 91

	
92 92
    // Iterable extensions
93 93

	
94 94
    class NodeIt : public Node { 
95 95
      const Digraph* digraph;
96 96
    public:
97 97

	
98 98
      NodeIt() {}
99 99

	
100 100
      NodeIt(Invalid i) : Node(i) { }
101 101

	
102 102
      explicit NodeIt(const Digraph& _graph) : digraph(&_graph) {
103 103
	_graph.first(static_cast<Node&>(*this));
104 104
      }
105 105

	
106 106
      NodeIt(const Digraph& _graph, const Node& node) 
107 107
	: Node(node), digraph(&_graph) {}
108 108

	
109 109
      NodeIt& operator++() { 
110 110
	digraph->next(*this);
111 111
	return *this; 
112 112
      }
113 113

	
114 114
    };
115 115

	
116 116

	
117 117
    class ArcIt : public Arc { 
118 118
      const Digraph* digraph;
119 119
    public:
120 120

	
121 121
      ArcIt() { }
122 122

	
123 123
      ArcIt(Invalid i) : Arc(i) { }
124 124

	
125 125
      explicit ArcIt(const Digraph& _graph) : digraph(&_graph) {
126 126
	_graph.first(static_cast<Arc&>(*this));
127 127
      }
128 128

	
129 129
      ArcIt(const Digraph& _graph, const Arc& e) : 
130 130
	Arc(e), digraph(&_graph) { }
131 131

	
132 132
      ArcIt& operator++() { 
133 133
	digraph->next(*this);
134 134
	return *this; 
135 135
      }
136 136

	
137 137
    };
138 138

	
139 139

	
140 140
    class OutArcIt : public Arc { 
141 141
      const Digraph* digraph;
142 142
    public:
143 143

	
144 144
      OutArcIt() { }
145 145

	
146 146
      OutArcIt(Invalid i) : Arc(i) { }
147 147

	
148 148
      OutArcIt(const Digraph& _graph, const Node& node) 
149 149
	: digraph(&_graph) {
150 150
	_graph.firstOut(*this, node);
151 151
      }
152 152

	
153 153
      OutArcIt(const Digraph& _graph, const Arc& arc) 
154 154
	: Arc(arc), digraph(&_graph) {}
155 155

	
156 156
      OutArcIt& operator++() { 
157 157
	digraph->nextOut(*this);
158 158
	return *this; 
159 159
      }
160 160

	
161 161
    };
162 162

	
163 163

	
164 164
    class InArcIt : public Arc { 
165 165
      const Digraph* digraph;
166 166
    public:
167 167

	
168 168
      InArcIt() { }
169 169

	
170 170
      InArcIt(Invalid i) : Arc(i) { }
171 171

	
172 172
      InArcIt(const Digraph& _graph, const Node& node) 
173 173
	: digraph(&_graph) {
174 174
	_graph.firstIn(*this, node);
175 175
      }
176 176

	
177 177
      InArcIt(const Digraph& _graph, const Arc& arc) : 
178 178
	Arc(arc), digraph(&_graph) {}
179 179

	
180 180
      InArcIt& operator++() { 
181 181
	digraph->nextIn(*this);
182 182
	return *this; 
183 183
      }
184 184

	
185 185
    };
186 186

	
187 187
    // \brief Base node of the iterator
188 188
    //
189 189
    // Returns the base node (ie. the source in this case) of the iterator
190 190
    Node baseNode(const OutArcIt &e) const {
191 191
      return Parent::source(static_cast<const Arc&>(e));
192 192
    }
193 193
    // \brief Running node of the iterator
194 194
    //
195 195
    // Returns the running node (ie. the target in this case) of the
196 196
    // iterator
197 197
    Node runningNode(const OutArcIt &e) const {
198 198
      return Parent::target(static_cast<const Arc&>(e));
199 199
    }
200 200

	
201 201
    // \brief Base node of the iterator
202 202
    //
203 203
    // Returns the base node (ie. the target in this case) of the iterator
204 204
    Node baseNode(const InArcIt &e) const {
205 205
      return Parent::target(static_cast<const Arc&>(e));
206 206
    }
207 207
    // \brief Running node of the iterator
208 208
    //
209 209
    // Returns the running node (ie. the source in this case) of the
210 210
    // iterator
211 211
    Node runningNode(const InArcIt &e) const {
212 212
      return Parent::source(static_cast<const Arc&>(e));
213 213
    }
214 214

	
215 215
    using Parent::first;
216 216

	
217 217
    // Mappable extension
218 218
    
219 219
    template <typename _Value>
220 220
    class ArcMap 
221 221
      : public MapExtender<DefaultMap<Digraph, Arc, _Value> > {
222 222
      typedef MapExtender<DefaultMap<Digraph, Arc, _Value> > Parent;
223 223

	
224 224
    public:
225 225
      explicit ArcMap(const Digraph& _g) 
226 226
	: Parent(_g) {}
227 227
      ArcMap(const Digraph& _g, const _Value& _v) 
228 228
	: Parent(_g, _v) {}
229 229

	
230 230
      ArcMap& operator=(const ArcMap& cmap) {
231 231
	return operator=<ArcMap>(cmap);
232 232
      }
233 233

	
234 234
      template <typename CMap>
235 235
      ArcMap& operator=(const CMap& cmap) {
236 236
        Parent::operator=(cmap);
237 237
	return *this;
238 238
      }
239 239

	
240 240
    };
241 241

	
242 242

	
243 243
    // Alteration extension
244 244

	
245 245
    Arc addArc(const Node& from, const Node& to) {
246 246
      Arc arc = Parent::addArc(from, to);
247 247
      notifier(Arc()).add(arc);
248 248
      return arc;
249 249
    }
250 250
    
251 251
    void clear() {
252 252
      notifier(Arc()).clear();
253 253
      Parent::clear();
254 254
    }
255 255

	
256 256
    void erase(const Arc& arc) {
257 257
      notifier(Arc()).erase(arc);
258 258
      Parent::erase(arc);
259 259
    }
260 260

	
261 261
    ArcSetExtender() {
262 262
      arc_notifier.setContainer(*this);
263 263
    }
264 264

	
265 265
    ~ArcSetExtender() {
266 266
      arc_notifier.clear();
267 267
    }
268 268

	
269 269
  };
270 270

	
271 271

	
272 272
  // \ingroup digraphbits
273 273
  //
274 274
  // \brief Extender for the EdgeSets
275 275
  template <typename Base>
276 276
  class EdgeSetExtender : public Base {
277 277
    typedef Base Parent;
278 278

	
279 279
  public:
280 280

	
281 281
    typedef EdgeSetExtender Graph;
282 282

	
283 283
    typedef typename Parent::Node Node;
284 284
    typedef typename Parent::Arc Arc;
285 285
    typedef typename Parent::Edge Edge;
286 286

	
287 287
    int maxId(Node) const {
288 288
      return Parent::maxNodeId();
289 289
    }
290 290

	
291 291
    int maxId(Arc) const {
292 292
      return Parent::maxArcId();
293 293
    }
294 294

	
295 295
    int maxId(Edge) const {
296 296
      return Parent::maxEdgeId();
297 297
    }
298 298

	
299 299
    Node fromId(int id, Node) const {
300 300
      return Parent::nodeFromId(id);
301 301
    }
302 302

	
303 303
    Arc fromId(int id, Arc) const {
304 304
      return Parent::arcFromId(id);
305 305
    }
306 306

	
307 307
    Edge fromId(int id, Edge) const {
308 308
      return Parent::edgeFromId(id);
309 309
    }
310 310

	
311 311
    Node oppositeNode(const Node &n, const Edge &e) const {
312 312
      if( n == Parent::u(e))
313 313
	return Parent::v(e);
314 314
      else if( n == Parent::v(e))
315 315
	return Parent::u(e);
316 316
      else
317 317
	return INVALID;
318 318
    }
319 319

	
320 320
    Arc oppositeArc(const Arc &e) const {
321 321
      return Parent::direct(e, !Parent::direction(e));
322 322
    }
323 323

	
324 324
    using Parent::direct;
325 325
    Arc direct(const Edge &e, const Node &s) const {
326 326
      return Parent::direct(e, Parent::u(e) == s);
327 327
    }
328 328

	
329 329
    typedef AlterationNotifier<EdgeSetExtender, Arc> ArcNotifier;
330 330
    typedef AlterationNotifier<EdgeSetExtender, Edge> EdgeNotifier;
331 331

	
332 332

	
333 333
  protected:
334 334

	
335 335
    mutable ArcNotifier arc_notifier;
336 336
    mutable EdgeNotifier edge_notifier;
337 337

	
338 338
  public:
339 339

	
340 340
    using Parent::notifier;
341 341
    
342 342
    ArcNotifier& notifier(Arc) const {
343 343
      return arc_notifier;
344 344
    }
345 345

	
346 346
    EdgeNotifier& notifier(Edge) const {
347 347
      return edge_notifier;
348 348
    }
349 349

	
350 350

	
351 351
    class NodeIt : public Node { 
352 352
      const Graph* graph;
353 353
    public:
354 354

	
355 355
      NodeIt() {}
356 356

	
357 357
      NodeIt(Invalid i) : Node(i) { }
358 358

	
359 359
      explicit NodeIt(const Graph& _graph) : graph(&_graph) {
360 360
	_graph.first(static_cast<Node&>(*this));
361 361
      }
362 362

	
363 363
      NodeIt(const Graph& _graph, const Node& node) 
364 364
	: Node(node), graph(&_graph) {}
365 365

	
366 366
      NodeIt& operator++() { 
367 367
	graph->next(*this);
368 368
	return *this; 
369 369
      }
370 370

	
371 371
    };
372 372

	
373 373

	
374 374
    class ArcIt : public Arc { 
375 375
      const Graph* graph;
376 376
    public:
377 377

	
378 378
      ArcIt() { }
379 379

	
380 380
      ArcIt(Invalid i) : Arc(i) { }
381 381

	
382 382
      explicit ArcIt(const Graph& _graph) : graph(&_graph) {
383 383
	_graph.first(static_cast<Arc&>(*this));
384 384
      }
385 385

	
386 386
      ArcIt(const Graph& _graph, const Arc& e) : 
387 387
	Arc(e), graph(&_graph) { }
388 388

	
389 389
      ArcIt& operator++() { 
390 390
	graph->next(*this);
391 391
	return *this; 
392 392
      }
393 393

	
394 394
    };
395 395

	
396 396

	
397 397
    class OutArcIt : public Arc { 
398 398
      const Graph* graph;
399 399
    public:
400 400

	
401 401
      OutArcIt() { }
402 402

	
403 403
      OutArcIt(Invalid i) : Arc(i) { }
404 404

	
405 405
      OutArcIt(const Graph& _graph, const Node& node) 
406 406
	: graph(&_graph) {
407 407
	_graph.firstOut(*this, node);
408 408
      }
409 409

	
410 410
      OutArcIt(const Graph& _graph, const Arc& arc) 
411 411
	: Arc(arc), graph(&_graph) {}
412 412

	
413 413
      OutArcIt& operator++() { 
414 414
	graph->nextOut(*this);
415 415
	return *this; 
416 416
      }
417 417

	
418 418
    };
419 419

	
420 420

	
421 421
    class InArcIt : public Arc { 
422 422
      const Graph* graph;
423 423
    public:
424 424

	
425 425
      InArcIt() { }
426 426

	
427 427
      InArcIt(Invalid i) : Arc(i) { }
428 428

	
429 429
      InArcIt(const Graph& _graph, const Node& node) 
430 430
	: graph(&_graph) {
431 431
	_graph.firstIn(*this, node);
432 432
      }
433 433

	
434 434
      InArcIt(const Graph& _graph, const Arc& arc) : 
435 435
	Arc(arc), graph(&_graph) {}
436 436

	
437 437
      InArcIt& operator++() { 
438 438
	graph->nextIn(*this);
439 439
	return *this; 
440 440
      }
441 441

	
442 442
    };
443 443

	
444 444

	
445 445
    class EdgeIt : public Parent::Edge { 
446 446
      const Graph* graph;
447 447
    public:
448 448

	
449 449
      EdgeIt() { }
450 450

	
451 451
      EdgeIt(Invalid i) : Edge(i) { }
452 452

	
453 453
      explicit EdgeIt(const Graph& _graph) : graph(&_graph) {
454 454
	_graph.first(static_cast<Edge&>(*this));
455 455
      }
456 456

	
457 457
      EdgeIt(const Graph& _graph, const Edge& e) : 
458 458
	Edge(e), graph(&_graph) { }
459 459

	
460 460
      EdgeIt& operator++() { 
461 461
	graph->next(*this);
462 462
	return *this; 
463 463
      }
464 464

	
465 465
    };
466 466

	
467 467
    class IncEdgeIt : public Parent::Edge {
468 468
      friend class EdgeSetExtender;
469 469
      const Graph* graph;
470 470
      bool direction;
471 471
    public:
472 472

	
473 473
      IncEdgeIt() { }
474 474

	
475 475
      IncEdgeIt(Invalid i) : Edge(i), direction(false) { }
476 476

	
477 477
      IncEdgeIt(const Graph& _graph, const Node &n) : graph(&_graph) {
478 478
	_graph.firstInc(*this, direction, n);
479 479
      }
480 480

	
481 481
      IncEdgeIt(const Graph& _graph, const Edge &ue, const Node &n)
482 482
	: graph(&_graph), Edge(ue) {
483 483
	direction = (_graph.source(ue) == n);
484 484
      }
485 485

	
486 486
      IncEdgeIt& operator++() {
487 487
	graph->nextInc(*this, direction);
488 488
	return *this; 
489 489
      }
490 490
    };
491 491

	
492 492
    // \brief Base node of the iterator
493 493
    //
494 494
    // Returns the base node (ie. the source in this case) of the iterator
495 495
    Node baseNode(const OutArcIt &e) const {
496 496
      return Parent::source(static_cast<const Arc&>(e));
497 497
    }
498 498
    // \brief Running node of the iterator
499 499
    //
500 500
    // Returns the running node (ie. the target in this case) of the
501 501
    // iterator
502 502
    Node runningNode(const OutArcIt &e) const {
503 503
      return Parent::target(static_cast<const Arc&>(e));
504 504
    }
505 505

	
506 506
    // \brief Base node of the iterator
507 507
    //
508 508
    // Returns the base node (ie. the target in this case) of the iterator
509 509
    Node baseNode(const InArcIt &e) const {
510 510
      return Parent::target(static_cast<const Arc&>(e));
511 511
    }
512 512
    // \brief Running node of the iterator
513 513
    //
514 514
    // Returns the running node (ie. the source in this case) of the
515 515
    // iterator
516 516
    Node runningNode(const InArcIt &e) const {
517 517
      return Parent::source(static_cast<const Arc&>(e));
518 518
    }
519 519

	
520 520
    // Base node of the iterator
521 521
    //
522 522
    // Returns the base node of the iterator
523 523
    Node baseNode(const IncEdgeIt &e) const {
524 524
      return e.direction ? u(e) : v(e);
525 525
    }
526 526
    // Running node of the iterator
527 527
    //
528 528
    // Returns the running node of the iterator
529 529
    Node runningNode(const IncEdgeIt &e) const {
530 530
      return e.direction ? v(e) : u(e);
531 531
    }
532 532

	
533 533

	
534 534
    template <typename _Value>
535 535
    class ArcMap 
536 536
      : public MapExtender<DefaultMap<Graph, Arc, _Value> > {
537 537
      typedef MapExtender<DefaultMap<Graph, Arc, _Value> > Parent;
538 538

	
539 539
    public:
540
      ArcMap(const Graph& _g) 
540
      explicit ArcMap(const Graph& _g) 
541 541
	: Parent(_g) {}
542 542
      ArcMap(const Graph& _g, const _Value& _v) 
543 543
	: Parent(_g, _v) {}
544 544

	
545 545
      ArcMap& operator=(const ArcMap& cmap) {
546 546
	return operator=<ArcMap>(cmap);
547 547
      }
548 548

	
549 549
      template <typename CMap>
550 550
      ArcMap& operator=(const CMap& cmap) {
551 551
        Parent::operator=(cmap);
552 552
	return *this;
553 553
      }
554 554

	
555 555
    };
556 556

	
557 557

	
558 558
    template <typename _Value>
559 559
    class EdgeMap 
560 560
      : public MapExtender<DefaultMap<Graph, Edge, _Value> > {
561 561
      typedef MapExtender<DefaultMap<Graph, Edge, _Value> > Parent;
562 562

	
563 563
    public:
564
      EdgeMap(const Graph& _g) 
564
      explicit EdgeMap(const Graph& _g) 
565 565
	: Parent(_g) {}
566 566

	
567 567
      EdgeMap(const Graph& _g, const _Value& _v) 
568 568
	: Parent(_g, _v) {}
569 569

	
570 570
      EdgeMap& operator=(const EdgeMap& cmap) {
571 571
	return operator=<EdgeMap>(cmap);
572 572
      }
573 573

	
574 574
      template <typename CMap>
575 575
      EdgeMap& operator=(const CMap& cmap) {
576 576
        Parent::operator=(cmap);
577 577
	return *this;
578 578
      }
579 579

	
580 580
    };
581 581

	
582 582

	
583 583
    // Alteration extension
584 584

	
585 585
    Edge addEdge(const Node& from, const Node& to) {
586 586
      Edge edge = Parent::addEdge(from, to);
587 587
      notifier(Edge()).add(edge);
588 588
      std::vector<Arc> arcs;
589 589
      arcs.push_back(Parent::direct(edge, true));
590 590
      arcs.push_back(Parent::direct(edge, false));
591 591
      notifier(Arc()).add(arcs);
592 592
      return edge;
593 593
    }
594 594
    
595 595
    void clear() {
596 596
      notifier(Arc()).clear();
597 597
      notifier(Edge()).clear();
598 598
      Parent::clear();
599 599
    }
600 600

	
601 601
    void erase(const Edge& edge) {
602 602
      std::vector<Arc> arcs;
603 603
      arcs.push_back(Parent::direct(edge, true));
604 604
      arcs.push_back(Parent::direct(edge, false));
605 605
      notifier(Arc()).erase(arcs);
606 606
      notifier(Edge()).erase(edge);
607 607
      Parent::erase(edge);
608 608
    }
609 609

	
610 610

	
611 611
    EdgeSetExtender() {
612 612
      arc_notifier.setContainer(*this);
613 613
      edge_notifier.setContainer(*this);
614 614
    }
615 615

	
616 616
    ~EdgeSetExtender() {
617 617
      edge_notifier.clear();
618 618
      arc_notifier.clear();
619 619
    }
620 620
    
621 621
  };
622 622

	
623 623
}
624 624

	
625 625
#endif
Ignore white space 6 line context
1 1
/* -*- mode: C++; indent-tabs-mode: nil; -*-
2 2
 *
3 3
 * This file is a part of LEMON, a generic C++ optimization library.
4 4
 *
5 5
 * Copyright (C) 2003-2009
6 6
 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 7
 * (Egervary Research Group on Combinatorial Optimization, EGRES).
8 8
 *
9 9
 * Permission to use, modify and distribute this software is granted
10 10
 * provided that this copyright notice appears in all copies. For
11 11
 * precise terms see the accompanying LICENSE file.
12 12
 *
13 13
 * This software is provided "AS IS" with no warranty of any kind,
14 14
 * express or implied, and with no claim as to its suitability for any
15 15
 * purpose.
16 16
 *
17 17
 */
18 18

	
19 19
#ifndef LEMON_BITS_GRAPH_EXTENDER_H
20 20
#define LEMON_BITS_GRAPH_EXTENDER_H
21 21

	
22 22
#include <lemon/core.h>
23 23

	
24 24
#include <lemon/bits/map_extender.h>
25 25
#include <lemon/bits/default_map.h>
26 26

	
27 27
#include <lemon/concept_check.h>
28 28
#include <lemon/concepts/maps.h>
29 29

	
30 30
//\ingroup graphbits
31 31
//\file
32 32
//\brief Extenders for the graph types
33 33
namespace lemon {
34 34

	
35 35
  // \ingroup graphbits
36 36
  //
37 37
  // \brief Extender for the digraph implementations
38 38
  template <typename Base>
39 39
  class DigraphExtender : public Base {
40 40
    typedef Base Parent;
41 41

	
42 42
  public:
43 43

	
44 44
    typedef DigraphExtender Digraph;
45 45

	
46 46
    // Base extensions
47 47

	
48 48
    typedef typename Parent::Node Node;
49 49
    typedef typename Parent::Arc Arc;
50 50

	
51 51
    int maxId(Node) const {
52 52
      return Parent::maxNodeId();
53 53
    }
54 54

	
55 55
    int maxId(Arc) const {
56 56
      return Parent::maxArcId();
57 57
    }
58 58

	
59 59
    Node fromId(int id, Node) const {
60 60
      return Parent::nodeFromId(id);
61 61
    }
62 62

	
63 63
    Arc fromId(int id, Arc) const {
64 64
      return Parent::arcFromId(id);
65 65
    }
66 66

	
67 67
    Node oppositeNode(const Node &node, const Arc &arc) const {
68 68
      if (node == Parent::source(arc))
69 69
        return Parent::target(arc);
70 70
      else if(node == Parent::target(arc))
71 71
        return Parent::source(arc);
72 72
      else
73 73
        return INVALID;
74 74
    }
75 75

	
76 76
    // Alterable extension
77 77

	
78 78
    typedef AlterationNotifier<DigraphExtender, Node> NodeNotifier;
79 79
    typedef AlterationNotifier<DigraphExtender, Arc> ArcNotifier;
80 80

	
81 81

	
82 82
  protected:
83 83

	
84 84
    mutable NodeNotifier node_notifier;
85 85
    mutable ArcNotifier arc_notifier;
86 86

	
87 87
  public:
88 88

	
89 89
    NodeNotifier& notifier(Node) const {
90 90
      return node_notifier;
91 91
    }
92 92

	
93 93
    ArcNotifier& notifier(Arc) const {
94 94
      return arc_notifier;
95 95
    }
96 96

	
97 97
    class NodeIt : public Node {
98 98
      const Digraph* _digraph;
99 99
    public:
100 100

	
101 101
      NodeIt() {}
102 102

	
103 103
      NodeIt(Invalid i) : Node(i) { }
104 104

	
105 105
      explicit NodeIt(const Digraph& digraph) : _digraph(&digraph) {
106 106
        _digraph->first(static_cast<Node&>(*this));
107 107
      }
108 108

	
109 109
      NodeIt(const Digraph& digraph, const Node& node)
110 110
        : Node(node), _digraph(&digraph) {}
111 111

	
112 112
      NodeIt& operator++() {
113 113
        _digraph->next(*this);
114 114
        return *this;
115 115
      }
116 116

	
117 117
    };
118 118

	
119 119

	
120 120
    class ArcIt : public Arc {
121 121
      const Digraph* _digraph;
122 122
    public:
123 123

	
124 124
      ArcIt() { }
125 125

	
126 126
      ArcIt(Invalid i) : Arc(i) { }
127 127

	
128 128
      explicit ArcIt(const Digraph& digraph) : _digraph(&digraph) {
129 129
        _digraph->first(static_cast<Arc&>(*this));
130 130
      }
131 131

	
132 132
      ArcIt(const Digraph& digraph, const Arc& arc) :
133 133
        Arc(arc), _digraph(&digraph) { }
134 134

	
135 135
      ArcIt& operator++() {
136 136
        _digraph->next(*this);
137 137
        return *this;
138 138
      }
139 139

	
140 140
    };
141 141

	
142 142

	
143 143
    class OutArcIt : public Arc {
144 144
      const Digraph* _digraph;
145 145
    public:
146 146

	
147 147
      OutArcIt() { }
148 148

	
149 149
      OutArcIt(Invalid i) : Arc(i) { }
150 150

	
151 151
      OutArcIt(const Digraph& digraph, const Node& node)
152 152
        : _digraph(&digraph) {
153 153
        _digraph->firstOut(*this, node);
154 154
      }
155 155

	
156 156
      OutArcIt(const Digraph& digraph, const Arc& arc)
157 157
        : Arc(arc), _digraph(&digraph) {}
158 158

	
159 159
      OutArcIt& operator++() {
160 160
        _digraph->nextOut(*this);
161 161
        return *this;
162 162
      }
163 163

	
164 164
    };
165 165

	
166 166

	
167 167
    class InArcIt : public Arc {
168 168
      const Digraph* _digraph;
169 169
    public:
170 170

	
171 171
      InArcIt() { }
172 172

	
173 173
      InArcIt(Invalid i) : Arc(i) { }
174 174

	
175 175
      InArcIt(const Digraph& digraph, const Node& node)
176 176
        : _digraph(&digraph) {
177 177
        _digraph->firstIn(*this, node);
178 178
      }
179 179

	
180 180
      InArcIt(const Digraph& digraph, const Arc& arc) :
181 181
        Arc(arc), _digraph(&digraph) {}
182 182

	
183 183
      InArcIt& operator++() {
184 184
        _digraph->nextIn(*this);
185 185
        return *this;
186 186
      }
187 187

	
188 188
    };
189 189

	
190 190
    // \brief Base node of the iterator
191 191
    //
192 192
    // Returns the base node (i.e. the source in this case) of the iterator
193 193
    Node baseNode(const OutArcIt &arc) const {
194 194
      return Parent::source(arc);
195 195
    }
196 196
    // \brief Running node of the iterator
197 197
    //
198 198
    // Returns the running node (i.e. the target in this case) of the
199 199
    // iterator
200 200
    Node runningNode(const OutArcIt &arc) const {
201 201
      return Parent::target(arc);
202 202
    }
203 203

	
204 204
    // \brief Base node of the iterator
205 205
    //
206 206
    // Returns the base node (i.e. the target in this case) of the iterator
207 207
    Node baseNode(const InArcIt &arc) const {
208 208
      return Parent::target(arc);
209 209
    }
210 210
    // \brief Running node of the iterator
211 211
    //
212 212
    // Returns the running node (i.e. the source in this case) of the
213 213
    // iterator
214 214
    Node runningNode(const InArcIt &arc) const {
215 215
      return Parent::source(arc);
216 216
    }
217 217

	
218 218

	
219 219
    template <typename _Value>
220 220
    class NodeMap
221 221
      : public MapExtender<DefaultMap<Digraph, Node, _Value> > {
222 222
      typedef MapExtender<DefaultMap<Digraph, Node, _Value> > Parent;
223 223

	
224 224
    public:
225 225
      explicit NodeMap(const Digraph& digraph)
226 226
        : Parent(digraph) {}
227 227
      NodeMap(const Digraph& digraph, const _Value& value)
228 228
        : Parent(digraph, value) {}
229 229

	
230 230
    private:
231 231
      NodeMap& operator=(const NodeMap& cmap) {
232 232
        return operator=<NodeMap>(cmap);
233 233
      }
234 234

	
235 235
      template <typename CMap>
236 236
      NodeMap& operator=(const CMap& cmap) {
237 237
        Parent::operator=(cmap);
238 238
        return *this;
239 239
      }
240 240

	
241 241
    };
242 242

	
243 243
    template <typename _Value>
244 244
    class ArcMap
245 245
      : public MapExtender<DefaultMap<Digraph, Arc, _Value> > {
246 246
      typedef MapExtender<DefaultMap<Digraph, Arc, _Value> > Parent;
247 247

	
248 248
    public:
249 249
      explicit ArcMap(const Digraph& digraph)
250 250
        : Parent(digraph) {}
251 251
      ArcMap(const Digraph& digraph, const _Value& value)
252 252
        : Parent(digraph, value) {}
253 253

	
254 254
    private:
255 255
      ArcMap& operator=(const ArcMap& cmap) {
256 256
        return operator=<ArcMap>(cmap);
257 257
      }
258 258

	
259 259
      template <typename CMap>
260 260
      ArcMap& operator=(const CMap& cmap) {
261 261
        Parent::operator=(cmap);
262 262
        return *this;
263 263
      }
264 264
    };
265 265

	
266 266

	
267 267
    Node addNode() {
268 268
      Node node = Parent::addNode();
269 269
      notifier(Node()).add(node);
270 270
      return node;
271 271
    }
272 272

	
273 273
    Arc addArc(const Node& from, const Node& to) {
274 274
      Arc arc = Parent::addArc(from, to);
275 275
      notifier(Arc()).add(arc);
276 276
      return arc;
277 277
    }
278 278

	
279 279
    void clear() {
280 280
      notifier(Arc()).clear();
281 281
      notifier(Node()).clear();
282 282
      Parent::clear();
283 283
    }
284 284

	
285 285
    template <typename Digraph, typename NodeRefMap, typename ArcRefMap>
286 286
    void build(const Digraph& digraph, NodeRefMap& nodeRef, ArcRefMap& arcRef) {
287 287
      Parent::build(digraph, nodeRef, arcRef);
288 288
      notifier(Node()).build();
289 289
      notifier(Arc()).build();
290 290
    }
291 291

	
292 292
    void erase(const Node& node) {
293 293
      Arc arc;
294 294
      Parent::firstOut(arc, node);
295 295
      while (arc != INVALID ) {
296 296
        erase(arc);
297 297
        Parent::firstOut(arc, node);
298 298
      }
299 299

	
300 300
      Parent::firstIn(arc, node);
301 301
      while (arc != INVALID ) {
302 302
        erase(arc);
303 303
        Parent::firstIn(arc, node);
304 304
      }
305 305

	
306 306
      notifier(Node()).erase(node);
307 307
      Parent::erase(node);
308 308
    }
309 309

	
310 310
    void erase(const Arc& arc) {
311 311
      notifier(Arc()).erase(arc);
312 312
      Parent::erase(arc);
313 313
    }
314 314

	
315 315
    DigraphExtender() {
316 316
      node_notifier.setContainer(*this);
317 317
      arc_notifier.setContainer(*this);
318 318
    }
319 319

	
320 320

	
321 321
    ~DigraphExtender() {
322 322
      arc_notifier.clear();
323 323
      node_notifier.clear();
324 324
    }
325 325
  };
326 326

	
327 327
  // \ingroup _graphbits
328 328
  //
329 329
  // \brief Extender for the Graphs
330 330
  template <typename Base>
331 331
  class GraphExtender : public Base {
332 332
    typedef Base Parent;
333 333

	
334 334
  public:
335 335

	
336 336
    typedef GraphExtender Graph;
337 337

	
338 338
    typedef True UndirectedTag;
339 339

	
340 340
    typedef typename Parent::Node Node;
341 341
    typedef typename Parent::Arc Arc;
342 342
    typedef typename Parent::Edge Edge;
343 343

	
344 344
    // Graph extension
345 345

	
346 346
    int maxId(Node) const {
347 347
      return Parent::maxNodeId();
348 348
    }
349 349

	
350 350
    int maxId(Arc) const {
351 351
      return Parent::maxArcId();
352 352
    }
353 353

	
354 354
    int maxId(Edge) const {
355 355
      return Parent::maxEdgeId();
356 356
    }
357 357

	
358 358
    Node fromId(int id, Node) const {
359 359
      return Parent::nodeFromId(id);
360 360
    }
361 361

	
362 362
    Arc fromId(int id, Arc) const {
363 363
      return Parent::arcFromId(id);
364 364
    }
365 365

	
366 366
    Edge fromId(int id, Edge) const {
367 367
      return Parent::edgeFromId(id);
368 368
    }
369 369

	
370 370
    Node oppositeNode(const Node &n, const Edge &e) const {
371 371
      if( n == Parent::u(e))
372 372
        return Parent::v(e);
373 373
      else if( n == Parent::v(e))
374 374
        return Parent::u(e);
375 375
      else
376 376
        return INVALID;
377 377
    }
378 378

	
379 379
    Arc oppositeArc(const Arc &arc) const {
380 380
      return Parent::direct(arc, !Parent::direction(arc));
381 381
    }
382 382

	
383 383
    using Parent::direct;
384 384
    Arc direct(const Edge &edge, const Node &node) const {
385 385
      return Parent::direct(edge, Parent::u(edge) == node);
386 386
    }
387 387

	
388 388
    // Alterable extension
389 389

	
390 390
    typedef AlterationNotifier<GraphExtender, Node> NodeNotifier;
391 391
    typedef AlterationNotifier<GraphExtender, Arc> ArcNotifier;
392 392
    typedef AlterationNotifier<GraphExtender, Edge> EdgeNotifier;
393 393

	
394 394

	
395 395
  protected:
396 396

	
397 397
    mutable NodeNotifier node_notifier;
398 398
    mutable ArcNotifier arc_notifier;
399 399
    mutable EdgeNotifier edge_notifier;
400 400

	
401 401
  public:
402 402

	
403 403
    NodeNotifier& notifier(Node) const {
404 404
      return node_notifier;
405 405
    }
406 406

	
407 407
    ArcNotifier& notifier(Arc) const {
408 408
      return arc_notifier;
409 409
    }
410 410

	
411 411
    EdgeNotifier& notifier(Edge) const {
412 412
      return edge_notifier;
413 413
    }
414 414

	
415 415

	
416 416

	
417 417
    class NodeIt : public Node {
418 418
      const Graph* _graph;
419 419
    public:
420 420

	
421 421
      NodeIt() {}
422 422

	
423 423
      NodeIt(Invalid i) : Node(i) { }
424 424

	
425 425
      explicit NodeIt(const Graph& graph) : _graph(&graph) {
426 426
        _graph->first(static_cast<Node&>(*this));
427 427
      }
428 428

	
429 429
      NodeIt(const Graph& graph, const Node& node)
430 430
        : Node(node), _graph(&graph) {}
431 431

	
432 432
      NodeIt& operator++() {
433 433
        _graph->next(*this);
434 434
        return *this;
435 435
      }
436 436

	
437 437
    };
438 438

	
439 439

	
440 440
    class ArcIt : public Arc {
441 441
      const Graph* _graph;
442 442
    public:
443 443

	
444 444
      ArcIt() { }
445 445

	
446 446
      ArcIt(Invalid i) : Arc(i) { }
447 447

	
448 448
      explicit ArcIt(const Graph& graph) : _graph(&graph) {
449 449
        _graph->first(static_cast<Arc&>(*this));
450 450
      }
451 451

	
452 452
      ArcIt(const Graph& graph, const Arc& arc) :
453 453
        Arc(arc), _graph(&graph) { }
454 454

	
455 455
      ArcIt& operator++() {
456 456
        _graph->next(*this);
457 457
        return *this;
458 458
      }
459 459

	
460 460
    };
461 461

	
462 462

	
463 463
    class OutArcIt : public Arc {
464 464
      const Graph* _graph;
465 465
    public:
466 466

	
467 467
      OutArcIt() { }
468 468

	
469 469
      OutArcIt(Invalid i) : Arc(i) { }
470 470

	
471 471
      OutArcIt(const Graph& graph, const Node& node)
472 472
        : _graph(&graph) {
473 473
        _graph->firstOut(*this, node);
474 474
      }
475 475

	
476 476
      OutArcIt(const Graph& graph, const Arc& arc)
477 477
        : Arc(arc), _graph(&graph) {}
478 478

	
479 479
      OutArcIt& operator++() {
480 480
        _graph->nextOut(*this);
481 481
        return *this;
482 482
      }
483 483

	
484 484
    };
485 485

	
486 486

	
487 487
    class InArcIt : public Arc {
488 488
      const Graph* _graph;
489 489
    public:
490 490

	
491 491
      InArcIt() { }
492 492

	
493 493
      InArcIt(Invalid i) : Arc(i) { }
494 494

	
495 495
      InArcIt(const Graph& graph, const Node& node)
496 496
        : _graph(&graph) {
497 497
        _graph->firstIn(*this, node);
498 498
      }
499 499

	
500 500
      InArcIt(const Graph& graph, const Arc& arc) :
501 501
        Arc(arc), _graph(&graph) {}
502 502

	
503 503
      InArcIt& operator++() {
504 504
        _graph->nextIn(*this);
505 505
        return *this;
506 506
      }
507 507

	
508 508
    };
509 509

	
510 510

	
511 511
    class EdgeIt : public Parent::Edge {
512 512
      const Graph* _graph;
513 513
    public:
514 514

	
515 515
      EdgeIt() { }
516 516

	
517 517
      EdgeIt(Invalid i) : Edge(i) { }
518 518

	
519 519
      explicit EdgeIt(const Graph& graph) : _graph(&graph) {
520 520
        _graph->first(static_cast<Edge&>(*this));
521 521
      }
522 522

	
523 523
      EdgeIt(const Graph& graph, const Edge& edge) :
524 524
        Edge(edge), _graph(&graph) { }
525 525

	
526 526
      EdgeIt& operator++() {
527 527
        _graph->next(*this);
528 528
        return *this;
529 529
      }
530 530

	
531 531
    };
532 532

	
533 533
    class IncEdgeIt : public Parent::Edge {
534 534
      friend class GraphExtender;
535 535
      const Graph* _graph;
536 536
      bool _direction;
537 537
    public:
538 538

	
539 539
      IncEdgeIt() { }
540 540

	
541 541
      IncEdgeIt(Invalid i) : Edge(i), _direction(false) { }
542 542

	
543 543
      IncEdgeIt(const Graph& graph, const Node &node) : _graph(&graph) {
544 544
        _graph->firstInc(*this, _direction, node);
545 545
      }
546 546

	
547 547
      IncEdgeIt(const Graph& graph, const Edge &edge, const Node &node)
548 548
        : _graph(&graph), Edge(edge) {
549 549
        _direction = (_graph->source(edge) == node);
550 550
      }
551 551

	
552 552
      IncEdgeIt& operator++() {
553 553
        _graph->nextInc(*this, _direction);
554 554
        return *this;
555 555
      }
556 556
    };
557 557

	
558 558
    // \brief Base node of the iterator
559 559
    //
560 560
    // Returns the base node (ie. the source in this case) of the iterator
561 561
    Node baseNode(const OutArcIt &arc) const {
562 562
      return Parent::source(static_cast<const Arc&>(arc));
563 563
    }
564 564
    // \brief Running node of the iterator
565 565
    //
566 566
    // Returns the running node (ie. the target in this case) of the
567 567
    // iterator
568 568
    Node runningNode(const OutArcIt &arc) const {
569 569
      return Parent::target(static_cast<const Arc&>(arc));
570 570
    }
571 571

	
572 572
    // \brief Base node of the iterator
573 573
    //
574 574
    // Returns the base node (ie. the target in this case) of the iterator
575 575
    Node baseNode(const InArcIt &arc) const {
576 576
      return Parent::target(static_cast<const Arc&>(arc));
577 577
    }
578 578
    // \brief Running node of the iterator
579 579
    //
580 580
    // Returns the running node (ie. the source in this case) of the
581 581
    // iterator
582 582
    Node runningNode(const InArcIt &arc) const {
583 583
      return Parent::source(static_cast<const Arc&>(arc));
584 584
    }
585 585

	
586 586
    // Base node of the iterator
587 587
    //
588 588
    // Returns the base node of the iterator
589 589
    Node baseNode(const IncEdgeIt &edge) const {
590 590
      return edge._direction ? u(edge) : v(edge);
591 591
    }
592 592
    // Running node of the iterator
593 593
    //
594 594
    // Returns the running node of the iterator
595 595
    Node runningNode(const IncEdgeIt &edge) const {
596 596
      return edge._direction ? v(edge) : u(edge);
597 597
    }
598 598

	
599 599
    // Mappable extension
600 600

	
601 601
    template <typename _Value>
602 602
    class NodeMap
603 603
      : public MapExtender<DefaultMap<Graph, Node, _Value> > {
604 604
      typedef MapExtender<DefaultMap<Graph, Node, _Value> > Parent;
605 605

	
606 606
    public:
607
      NodeMap(const Graph& graph)
607
      explicit NodeMap(const Graph& graph)
608 608
        : Parent(graph) {}
609 609
      NodeMap(const Graph& graph, const _Value& value)
610 610
        : Parent(graph, value) {}
611 611

	
612 612
    private:
613 613
      NodeMap& operator=(const NodeMap& cmap) {
614 614
        return operator=<NodeMap>(cmap);
615 615
      }
616 616

	
617 617
      template <typename CMap>
618 618
      NodeMap& operator=(const CMap& cmap) {
619 619
        Parent::operator=(cmap);
620 620
        return *this;
621 621
      }
622 622

	
623 623
    };
624 624

	
625 625
    template <typename _Value>
626 626
    class ArcMap
627 627
      : public MapExtender<DefaultMap<Graph, Arc, _Value> > {
628 628
      typedef MapExtender<DefaultMap<Graph, Arc, _Value> > Parent;
629 629

	
630 630
    public:
631
      ArcMap(const Graph& graph)
631
      explicit ArcMap(const Graph& graph)
632 632
        : Parent(graph) {}
633 633
      ArcMap(const Graph& graph, const _Value& value)
634 634
        : Parent(graph, value) {}
635 635

	
636 636
    private:
637 637
      ArcMap& operator=(const ArcMap& cmap) {
638 638
        return operator=<ArcMap>(cmap);
639 639
      }
640 640

	
641 641
      template <typename CMap>
642 642
      ArcMap& operator=(const CMap& cmap) {
643 643
        Parent::operator=(cmap);
644 644
        return *this;
645 645
      }
646 646
    };
647 647

	
648 648

	
649 649
    template <typename _Value>
650 650
    class EdgeMap
651 651
      : public MapExtender<DefaultMap<Graph, Edge, _Value> > {
652 652
      typedef MapExtender<DefaultMap<Graph, Edge, _Value> > Parent;
653 653

	
654 654
    public:
655
      EdgeMap(const Graph& graph)
655
      explicit EdgeMap(const Graph& graph)
656 656
        : Parent(graph) {}
657 657

	
658 658
      EdgeMap(const Graph& graph, const _Value& value)
659 659
        : Parent(graph, value) {}
660 660

	
661 661
    private:
662 662
      EdgeMap& operator=(const EdgeMap& cmap) {
663 663
        return operator=<EdgeMap>(cmap);
664 664
      }
665 665

	
666 666
      template <typename CMap>
667 667
      EdgeMap& operator=(const CMap& cmap) {
668 668
        Parent::operator=(cmap);
669 669
        return *this;
670 670
      }
671 671

	
672 672
    };
673 673

	
674 674
    // Alteration extension
675 675

	
676 676
    Node addNode() {
677 677
      Node node = Parent::addNode();
678 678
      notifier(Node()).add(node);
679 679
      return node;
680 680
    }
681 681

	
682 682
    Edge addEdge(const Node& from, const Node& to) {
683 683
      Edge edge = Parent::addEdge(from, to);
684 684
      notifier(Edge()).add(edge);
685 685
      std::vector<Arc> ev;
686 686
      ev.push_back(Parent::direct(edge, true));
687 687
      ev.push_back(Parent::direct(edge, false));
688 688
      notifier(Arc()).add(ev);
689 689
      return edge;
690 690
    }
691 691

	
692 692
    void clear() {
693 693
      notifier(Arc()).clear();
694 694
      notifier(Edge()).clear();
695 695
      notifier(Node()).clear();
696 696
      Parent::clear();
697 697
    }
698 698

	
699 699
    template <typename Graph, typename NodeRefMap, typename EdgeRefMap>
700 700
    void build(const Graph& graph, NodeRefMap& nodeRef,
701 701
               EdgeRefMap& edgeRef) {
702 702
      Parent::build(graph, nodeRef, edgeRef);
703 703
      notifier(Node()).build();
704 704
      notifier(Edge()).build();
705 705
      notifier(Arc()).build();
706 706
    }
707 707

	
708 708
    void erase(const Node& node) {
709 709
      Arc arc;
710 710
      Parent::firstOut(arc, node);
711 711
      while (arc != INVALID ) {
712 712
        erase(arc);
713 713
        Parent::firstOut(arc, node);
714 714
      }
715 715

	
716 716
      Parent::firstIn(arc, node);
717 717
      while (arc != INVALID ) {
718 718
        erase(arc);
719 719
        Parent::firstIn(arc, node);
720 720
      }
721 721

	
722 722
      notifier(Node()).erase(node);
723 723
      Parent::erase(node);
724 724
    }
725 725

	
726 726
    void erase(const Edge& edge) {
727 727
      std::vector<Arc> av;
728 728
      av.push_back(Parent::direct(edge, true));
729 729
      av.push_back(Parent::direct(edge, false));
730 730
      notifier(Arc()).erase(av);
731 731
      notifier(Edge()).erase(edge);
732 732
      Parent::erase(edge);
733 733
    }
734 734

	
735 735
    GraphExtender() {
736 736
      node_notifier.setContainer(*this);
737 737
      arc_notifier.setContainer(*this);
738 738
      edge_notifier.setContainer(*this);
739 739
    }
740 740

	
741 741
    ~GraphExtender() {
742 742
      edge_notifier.clear();
743 743
      arc_notifier.clear();
744 744
      node_notifier.clear();
745 745
    }
746 746

	
747 747
  };
748 748

	
749 749
}
750 750

	
751 751
#endif
Ignore white space 6 line context
1 1
/* -*- mode: C++; indent-tabs-mode: nil; -*-
2 2
 *
3 3
 * This file is a part of LEMON, a generic C++ optimization library.
4 4
 *
5 5
 * Copyright (C) 2003-2009
6 6
 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 7
 * (Egervary Research Group on Combinatorial Optimization, EGRES).
8 8
 *
9 9
 * Permission to use, modify and distribute this software is granted
10 10
 * provided that this copyright notice appears in all copies. For
11 11
 * precise terms see the accompanying LICENSE file.
12 12
 *
13 13
 * This software is provided "AS IS" with no warranty of any kind,
14 14
 * express or implied, and with no claim as to its suitability for any
15 15
 * purpose.
16 16
 *
17 17
 */
18 18

	
19 19
#ifndef LEMON_BITS_MAP_EXTENDER_H
20 20
#define LEMON_BITS_MAP_EXTENDER_H
21 21

	
22 22
#include <iterator>
23 23

	
24 24
#include <lemon/bits/traits.h>
25 25

	
26 26
#include <lemon/concept_check.h>
27 27
#include <lemon/concepts/maps.h>
28 28

	
29 29
//\file
30 30
//\brief Extenders for iterable maps.
31 31

	
32 32
namespace lemon {
33 33

	
34 34
  // \ingroup graphbits
35 35
  //
36 36
  // \brief Extender for maps
37 37
  template <typename _Map>
38 38
  class MapExtender : public _Map {
39 39
    typedef _Map Parent;
40 40
    typedef typename Parent::GraphType GraphType;
41 41

	
42 42
  public:
43 43

	
44 44
    typedef MapExtender Map;
45 45
    typedef typename Parent::Key Item;
46 46

	
47 47
    typedef typename Parent::Key Key;
48 48
    typedef typename Parent::Value Value;
49 49
    typedef typename Parent::Reference Reference;
50 50
    typedef typename Parent::ConstReference ConstReference;
51 51

	
52
    typedef typename Parent::ReferenceMapTag ReferenceMapTag;
53

	
52 54
    class MapIt;
53 55
    class ConstMapIt;
54 56

	
55 57
    friend class MapIt;
56 58
    friend class ConstMapIt;
57 59

	
58 60
  public:
59 61

	
60 62
    MapExtender(const GraphType& graph)
61 63
      : Parent(graph) {}
62 64

	
63 65
    MapExtender(const GraphType& graph, const Value& value)
64 66
      : Parent(graph, value) {}
65 67

	
66 68
  private:
67 69
    MapExtender& operator=(const MapExtender& cmap) {
68 70
      return operator=<MapExtender>(cmap);
69 71
    }
70 72

	
71 73
    template <typename CMap>
72 74
    MapExtender& operator=(const CMap& cmap) {
73 75
      Parent::operator=(cmap);
74 76
      return *this;
75 77
    }
76 78

	
77 79
  public:
78 80
    class MapIt : public Item {
79 81
      typedef Item Parent;
80 82

	
81 83
    public:
82 84

	
83 85
      typedef typename Map::Value Value;
84 86

	
85 87
      MapIt() {}
86 88

	
87 89
      MapIt(Invalid i) : Parent(i) { }
88 90

	
89 91
      explicit MapIt(Map& _map) : map(_map) {
90 92
        map.notifier()->first(*this);
91 93
      }
92 94

	
93 95
      MapIt(const Map& _map, const Item& item)
94 96
        : Parent(item), map(_map) {}
95 97

	
96 98
      MapIt& operator++() {
97 99
        map.notifier()->next(*this);
98 100
        return *this;
99 101
      }
100 102

	
101 103
      typename MapTraits<Map>::ConstReturnValue operator*() const {
102 104
        return map[*this];
103 105
      }
104 106

	
105 107
      typename MapTraits<Map>::ReturnValue operator*() {
106 108
        return map[*this];
107 109
      }
108 110

	
109 111
      void set(const Value& value) {
110 112
        map.set(*this, value);
111 113
      }
112 114

	
113 115
    protected:
114 116
      Map& map;
115 117

	
116 118
    };
117 119

	
118 120
    class ConstMapIt : public Item {
119 121
      typedef Item Parent;
120 122

	
121 123
    public:
122 124

	
123 125
      typedef typename Map::Value Value;
124 126

	
125 127
      ConstMapIt() {}
126 128

	
127 129
      ConstMapIt(Invalid i) : Parent(i) { }
128 130

	
129 131
      explicit ConstMapIt(Map& _map) : map(_map) {
130 132
        map.notifier()->first(*this);
131 133
      }
132 134

	
133 135
      ConstMapIt(const Map& _map, const Item& item)
134 136
        : Parent(item), map(_map) {}
135 137

	
136 138
      ConstMapIt& operator++() {
137 139
        map.notifier()->next(*this);
138 140
        return *this;
139 141
      }
140 142

	
141 143
      typename MapTraits<Map>::ConstReturnValue operator*() const {
142 144
        return map[*this];
143 145
      }
144 146

	
145 147
    protected:
146 148
      const Map& map;
147 149
    };
148 150

	
149 151
    class ItemIt : public Item {
150 152
      typedef Item Parent;
151 153

	
152 154
    public:
153 155

	
154 156
      ItemIt() {}
155 157

	
156 158
      ItemIt(Invalid i) : Parent(i) { }
157 159

	
158 160
      explicit ItemIt(Map& _map) : map(_map) {
159 161
        map.notifier()->first(*this);
160 162
      }
161 163

	
162 164
      ItemIt(const Map& _map, const Item& item)
163 165
        : Parent(item), map(_map) {}
164 166

	
165 167
      ItemIt& operator++() {
166 168
        map.notifier()->next(*this);
167 169
        return *this;
168 170
      }
169 171

	
170 172
    protected:
171 173
      const Map& map;
172 174

	
173 175
    };
174 176
  };
175 177

	
176 178
  // \ingroup graphbits
177 179
  //
178 180
  // \brief Extender for maps which use a subset of the items.
179 181
  template <typename _Graph, typename _Map>
180 182
  class SubMapExtender : public _Map {
181 183
    typedef _Map Parent;
182 184
    typedef _Graph GraphType;
183 185

	
184 186
  public:
185 187

	
186 188
    typedef SubMapExtender Map;
187 189
    typedef typename Parent::Key Item;
188 190

	
189 191
    typedef typename Parent::Key Key;
190 192
    typedef typename Parent::Value Value;
191 193
    typedef typename Parent::Reference Reference;
192 194
    typedef typename Parent::ConstReference ConstReference;
193 195

	
196
    typedef typename Parent::ReferenceMapTag ReferenceMapTag;
197

	
194 198
    class MapIt;
195 199
    class ConstMapIt;
196 200

	
197 201
    friend class MapIt;
198 202
    friend class ConstMapIt;
199 203

	
200 204
  public:
201 205

	
202 206
    SubMapExtender(const GraphType& _graph)
203 207
      : Parent(_graph), graph(_graph) {}
204 208

	
205 209
    SubMapExtender(const GraphType& _graph, const Value& _value)
206 210
      : Parent(_graph, _value), graph(_graph) {}
207 211

	
208 212
  private:
209 213
    SubMapExtender& operator=(const SubMapExtender& cmap) {
210 214
      return operator=<MapExtender>(cmap);
211 215
    }
212 216

	
213 217
    template <typename CMap>
214 218
    SubMapExtender& operator=(const CMap& cmap) {
215 219
      checkConcept<concepts::ReadMap<Key, Value>, CMap>();
216 220
      Item it;
217 221
      for (graph.first(it); it != INVALID; graph.next(it)) {
218 222
        Parent::set(it, cmap[it]);
219 223
      }
220 224
      return *this;
221 225
    }
222 226

	
223 227
  public:
224 228
    class MapIt : public Item {
225 229
      typedef Item Parent;
226 230

	
227 231
    public:
228 232
      typedef typename Map::Value Value;
229 233

	
230 234
      MapIt() {}
231 235

	
232 236
      MapIt(Invalid i) : Parent(i) { }
233 237

	
234 238
      explicit MapIt(Map& _map) : map(_map) {
235 239
        map.graph.first(*this);
236 240
      }
237 241

	
238 242
      MapIt(const Map& _map, const Item& item)
239 243
        : Parent(item), map(_map) {}
240 244

	
241 245
      MapIt& operator++() {
242 246
        map.graph.next(*this);
243 247
        return *this;
244 248
      }
245 249

	
246 250
      typename MapTraits<Map>::ConstReturnValue operator*() const {
247 251
        return map[*this];
248 252
      }
249 253

	
250 254
      typename MapTraits<Map>::ReturnValue operator*() {
251 255
        return map[*this];
252 256
      }
253 257

	
254 258
      void set(const Value& value) {
255 259
        map.set(*this, value);
256 260
      }
257 261

	
258 262
    protected:
259 263
      Map& map;
260 264

	
261 265
    };
262 266

	
263 267
    class ConstMapIt : public Item {
264 268
      typedef Item Parent;
265 269

	
266 270
    public:
267 271

	
268 272
      typedef typename Map::Value Value;
269 273

	
270 274
      ConstMapIt() {}
271 275

	
272 276
      ConstMapIt(Invalid i) : Parent(i) { }
273 277

	
274 278
      explicit ConstMapIt(Map& _map) : map(_map) {
275 279
        map.graph.first(*this);
276 280
      }
277 281

	
278 282
      ConstMapIt(const Map& _map, const Item& item)
279 283
        : Parent(item), map(_map) {}
280 284

	
281 285
      ConstMapIt& operator++() {
282 286
        map.graph.next(*this);
283 287
        return *this;
284 288
      }
285 289

	
286 290
      typename MapTraits<Map>::ConstReturnValue operator*() const {
287 291
        return map[*this];
288 292
      }
289 293

	
290 294
    protected:
291 295
      const Map& map;
292 296
    };
293 297

	
294 298
    class ItemIt : public Item {
295 299
      typedef Item Parent;
296 300

	
297 301
    public:
298 302

	
299 303
      ItemIt() {}
300 304

	
301 305
      ItemIt(Invalid i) : Parent(i) { }
302 306

	
303 307
      explicit ItemIt(Map& _map) : map(_map) {
304 308
        map.graph.first(*this);
305 309
      }
306 310

	
307 311
      ItemIt(const Map& _map, const Item& item)
308 312
        : Parent(item), map(_map) {}
309 313

	
310 314
      ItemIt& operator++() {
311 315
        map.graph.next(*this);
312 316
        return *this;
313 317
      }
314 318

	
315 319
    protected:
316 320
      const Map& map;
317 321

	
318 322
    };
319 323

	
320 324
  private:
321 325

	
322 326
    const GraphType& graph;
323 327

	
324 328
  };
325 329

	
326 330
}
327 331

	
328 332
#endif
Ignore white space 393216 line context
1 1
/* -*- mode: C++; indent-tabs-mode: nil; -*-
2 2
 *
3 3
 * This file is a part of LEMON, a generic C++ optimization library.
4 4
 *
5 5
 * Copyright (C) 2003-2009
6 6
 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 7
 * (Egervary Research Group on Combinatorial Optimization, EGRES).
8 8
 *
9 9
 * Permission to use, modify and distribute this software is granted
10 10
 * provided that this copyright notice appears in all copies. For
11 11
 * precise terms see the accompanying LICENSE file.
12 12
 *
13 13
 * This software is provided "AS IS" with no warranty of any kind,
14 14
 * express or implied, and with no claim as to its suitability for any
15 15
 * purpose.
16 16
 *
17 17
 */
18 18

	
19 19
#ifndef LEMON_BUCKET_HEAP_H
20 20
#define LEMON_BUCKET_HEAP_H
21 21

	
22
///\ingroup auxdat
22
///\ingroup heaps
23 23
///\file
24
///\brief Bucket Heap implementation.
24
///\brief Bucket heap implementation.
25 25

	
26 26
#include <vector>
27 27
#include <utility>
28 28
#include <functional>
29 29

	
30 30
namespace lemon {
31 31

	
32 32
  namespace _bucket_heap_bits {
33 33

	
34 34
    template <bool MIN>
35 35
    struct DirectionTraits {
36 36
      static bool less(int left, int right) {
37 37
        return left < right;
38 38
      }
39 39
      static void increase(int& value) {
40 40
        ++value;
41 41
      }
42 42
    };
43 43

	
44 44
    template <>
45 45
    struct DirectionTraits<false> {
46 46
      static bool less(int left, int right) {
47 47
        return left > right;
48 48
      }
49 49
      static void increase(int& value) {
50 50
        --value;
51 51
      }
52 52
    };
53 53

	
54 54
  }
55 55

	
56
  /// \ingroup auxdat
56
  /// \ingroup heaps
57 57
  ///
58
  /// \brief A Bucket Heap implementation.
58
  /// \brief Bucket heap data structure.
59 59
  ///
60
  /// This class implements the \e bucket \e heap data structure. A \e heap
61
  /// is a data structure for storing items with specified values called \e
62
  /// priorities in such a way that finding the item with minimum priority is
63
  /// efficient. The bucket heap is very simple implementation, it can store
64
  /// only integer priorities and it stores for each priority in the
65
  /// \f$ [0..C) \f$ range a list of items. So it should be used only when
66
  /// the priorities are small. It is not intended to use as dijkstra heap.
60
  /// This class implements the \e bucket \e heap data structure.
61
  /// It practically conforms to the \ref concepts::Heap "heap concept",
62
  /// but it has some limitations.
67 63
  ///
68
  /// \param IM A read and write Item int map, used internally
69
  /// to handle the cross references.
70
  /// \param MIN If the given parameter is false then instead of the
71
  /// minimum value the maximum can be retrivied with the top() and
72
  /// prio() member functions.
64
  /// The bucket heap is a very simple structure. It can store only
65
  /// \c int priorities and it maintains a list of items for each priority
66
  /// in the range <tt>[0..C)</tt>. So it should only be used when the
67
  /// priorities are small. It is not intended to use as a Dijkstra heap.
68
  ///
69
  /// \tparam IM A read-writable item map with \c int values, used
70
  /// internally to handle the cross references.
71
  /// \tparam MIN Indicate if the heap is a \e min-heap or a \e max-heap.
72
  /// The default is \e min-heap. If this parameter is set to \c false,
73
  /// then the comparison is reversed, so the top(), prio() and pop()
74
  /// functions deal with the item having maximum priority instead of the
75
  /// minimum.
76
  ///
77
  /// \sa SimpleBucketHeap
73 78
  template <typename IM, bool MIN = true>
74 79
  class BucketHeap {
75 80

	
76 81
  public:
77
    /// \e
78
    typedef typename IM::Key Item;
79
    /// \e
82

	
83
    /// Type of the item-int map.
84
    typedef IM ItemIntMap;
85
    /// Type of the priorities.
80 86
    typedef int Prio;
81
    /// \e
82
    typedef std::pair<Item, Prio> Pair;
83
    /// \e
84
    typedef IM ItemIntMap;
87
    /// Type of the items stored in the heap.
88
    typedef typename ItemIntMap::Key Item;
89
    /// Type of the item-priority pairs.
90
    typedef std::pair<Item,Prio> Pair;
85 91

	
86 92
  private:
87 93

	
88 94
    typedef _bucket_heap_bits::DirectionTraits<MIN> Direction;
89 95

	
90 96
  public:
91 97

	
92
    /// \brief Type to represent the items states.
98
    /// \brief Type to represent the states of the items.
93 99
    ///
94
    /// Each Item element have a state associated to it. It may be "in heap",
95
    /// "pre heap" or "post heap". The latter two are indifferent from the
100
    /// Each item has a state associated to it. It can be "in heap",
101
    /// "pre-heap" or "post-heap". The latter two are indifferent from the
96 102
    /// heap's point of view, but may be useful to the user.
97 103
    ///
98 104
    /// The item-int map must be initialized in such way that it assigns
99 105
    /// \c PRE_HEAP (<tt>-1</tt>) to any element to be put in the heap.
100 106
    enum State {
101 107
      IN_HEAP = 0,    ///< = 0.
102 108
      PRE_HEAP = -1,  ///< = -1.
103 109
      POST_HEAP = -2  ///< = -2.
104 110
    };
105 111

	
106 112
  public:
107
    /// \brief The constructor.
113

	
114
    /// \brief Constructor.
108 115
    ///
109
    /// The constructor.
110
    /// \param map should be given to the constructor, since it is used
111
    /// internally to handle the cross references. The value of the map
112
    /// should be PRE_HEAP (-1) for each element.
116
    /// Constructor.
117
    /// \param map A map that assigns \c int values to the items.
118
    /// It is used internally to handle the cross references.
119
    /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
113 120
    explicit BucketHeap(ItemIntMap &map) : _iim(map), _minimum(0) {}
114 121

	
115
    /// The number of items stored in the heap.
122
    /// \brief The number of items stored in the heap.
116 123
    ///
117
    /// \brief Returns the number of items stored in the heap.
124
    /// This function returns the number of items stored in the heap.
118 125
    int size() const { return _data.size(); }
119 126

	
120
    /// \brief Checks if the heap stores no items.
127
    /// \brief Check if the heap is empty.
121 128
    ///
122
    /// Returns \c true if and only if the heap stores no items.
129
    /// This function returns \c true if the heap is empty.
123 130
    bool empty() const { return _data.empty(); }
124 131

	
125
    /// \brief Make empty this heap.
132
    /// \brief Make the heap empty.
126 133
    ///
127
    /// Make empty this heap. It does not change the cross reference
128
    /// map.  If you want to reuse a heap what is not surely empty you
129
    /// should first clear the heap and after that you should set the
130
    /// cross reference map for each item to \c PRE_HEAP.
134
    /// This functon makes the heap empty.
135
    /// It does not change the cross reference map. If you want to reuse
136
    /// a heap that is not surely empty, you should first clear it and
137
    /// then you should set the cross reference map to \c PRE_HEAP
138
    /// for each item.
131 139
    void clear() {
132 140
      _data.clear(); _first.clear(); _minimum = 0;
133 141
    }
134 142

	
135 143
  private:
136 144

	
137
    void relocate_last(int idx) {
145
    void relocateLast(int idx) {
138 146
      if (idx + 1 < int(_data.size())) {
139 147
        _data[idx] = _data.back();
140 148
        if (_data[idx].prev != -1) {
141 149
          _data[_data[idx].prev].next = idx;
142 150
        } else {
143 151
          _first[_data[idx].value] = idx;
144 152
        }
145 153
        if (_data[idx].next != -1) {
146 154
          _data[_data[idx].next].prev = idx;
147 155
        }
148 156
        _iim[_data[idx].item] = idx;
149 157
      }
150 158
      _data.pop_back();
151 159
    }
152 160

	
153 161
    void unlace(int idx) {
154 162
      if (_data[idx].prev != -1) {
155 163
        _data[_data[idx].prev].next = _data[idx].next;
156 164
      } else {
157 165
        _first[_data[idx].value] = _data[idx].next;
158 166
      }
159 167
      if (_data[idx].next != -1) {
160 168
        _data[_data[idx].next].prev = _data[idx].prev;
161 169
      }
162 170
    }
163 171

	
164 172
    void lace(int idx) {
165 173
      if (int(_first.size()) <= _data[idx].value) {
166 174
        _first.resize(_data[idx].value + 1, -1);
167 175
      }
168 176
      _data[idx].next = _first[_data[idx].value];
169 177
      if (_data[idx].next != -1) {
170 178
        _data[_data[idx].next].prev = idx;
171 179
      }
172 180
      _first[_data[idx].value] = idx;
173 181
      _data[idx].prev = -1;
174 182
    }
175 183

	
176 184
  public:
185

	
177 186
    /// \brief Insert a pair of item and priority into the heap.
178 187
    ///
179
    /// Adds \c p.first to the heap with priority \c p.second.
188
    /// This function inserts \c p.first to the heap with priority
189
    /// \c p.second.
180 190
    /// \param p The pair to insert.
191
    /// \pre \c p.first must not be stored in the heap.
181 192
    void push(const Pair& p) {
182 193
      push(p.first, p.second);
183 194
    }
184 195

	
185 196
    /// \brief Insert an item into the heap with the given priority.
186 197
    ///
187
    /// Adds \c i to the heap with priority \c p.
198
    /// This function inserts the given item into the heap with the
199
    /// given priority.
188 200
    /// \param i The item to insert.
189 201
    /// \param p The priority of the item.
202
    /// \pre \e i must not be stored in the heap.
190 203
    void push(const Item &i, const Prio &p) {
191 204
      int idx = _data.size();
192 205
      _iim[i] = idx;
193 206
      _data.push_back(BucketItem(i, p));
194 207
      lace(idx);
195 208
      if (Direction::less(p, _minimum)) {
196 209
        _minimum = p;
197 210
      }
198 211
    }
199 212

	
200
    /// \brief Returns the item with minimum priority.
213
    /// \brief Return the item having minimum priority.
201 214
    ///
202
    /// This method returns the item with minimum priority.
203
    /// \pre The heap must be nonempty.
215
    /// This function returns the item having minimum priority.
216
    /// \pre The heap must be non-empty.
204 217
    Item top() const {
205 218
      while (_first[_minimum] == -1) {
206 219
        Direction::increase(_minimum);
207 220
      }
208 221
      return _data[_first[_minimum]].item;
209 222
    }
210 223

	
211
    /// \brief Returns the minimum priority.
224
    /// \brief The minimum priority.
212 225
    ///
213
    /// It returns the minimum priority.
214
    /// \pre The heap must be nonempty.
226
    /// This function returns the minimum priority.
227
    /// \pre The heap must be non-empty.
215 228
    Prio prio() const {
216 229
      while (_first[_minimum] == -1) {
217 230
        Direction::increase(_minimum);
218 231
      }
219 232
      return _minimum;
220 233
    }
221 234

	
222
    /// \brief Deletes the item with minimum priority.
235
    /// \brief Remove the item having minimum priority.
223 236
    ///
224
    /// This method deletes the item with minimum priority from the heap.
237
    /// This function removes the item having minimum priority.
225 238
    /// \pre The heap must be non-empty.
226 239
    void pop() {
227 240
      while (_first[_minimum] == -1) {
228 241
        Direction::increase(_minimum);
229 242
      }
230 243
      int idx = _first[_minimum];
231 244
      _iim[_data[idx].item] = -2;
232 245
      unlace(idx);
233
      relocate_last(idx);
246
      relocateLast(idx);
234 247
    }
235 248

	
236
    /// \brief Deletes \c i from the heap.
249
    /// \brief Remove the given item from the heap.
237 250
    ///
238
    /// This method deletes item \c i from the heap, if \c i was
239
    /// already stored in the heap.
240
    /// \param i The item to erase.
251
    /// This function removes the given item from the heap if it is
252
    /// already stored.
253
    /// \param i The item to delete.
254
    /// \pre \e i must be in the heap.
241 255
    void erase(const Item &i) {
242 256
      int idx = _iim[i];
243 257
      _iim[_data[idx].item] = -2;
244 258
      unlace(idx);
245
      relocate_last(idx);
259
      relocateLast(idx);
246 260
    }
247 261

	
248

	
249
    /// \brief Returns the priority of \c i.
262
    /// \brief The priority of the given item.
250 263
    ///
251
    /// This function returns the priority of item \c i.
252
    /// \pre \c i must be in the heap.
264
    /// This function returns the priority of the given item.
253 265
    /// \param i The item.
266
    /// \pre \e i must be in the heap.
254 267
    Prio operator[](const Item &i) const {
255 268
      int idx = _iim[i];
256 269
      return _data[idx].value;
257 270
    }
258 271

	
259
    /// \brief \c i gets to the heap with priority \c p independently
260
    /// if \c i was already there.
272
    /// \brief Set the priority of an item or insert it, if it is
273
    /// not stored in the heap.
261 274
    ///
262
    /// This method calls \ref push(\c i, \c p) if \c i is not stored
263
    /// in the heap and sets the priority of \c i to \c p otherwise.
275
    /// This method sets the priority of the given item if it is
276
    /// already stored in the heap. Otherwise it inserts the given
277
    /// item into the heap with the given priority.
264 278
    /// \param i The item.
265 279
    /// \param p The priority.
266 280
    void set(const Item &i, const Prio &p) {
267 281
      int idx = _iim[i];
268 282
      if (idx < 0) {
269 283
        push(i, p);
270 284
      } else if (Direction::less(p, _data[idx].value)) {
271 285
        decrease(i, p);
272 286
      } else {
273 287
        increase(i, p);
274 288
      }
275 289
    }
276 290

	
277
    /// \brief Decreases the priority of \c i to \c p.
291
    /// \brief Decrease the priority of an item to the given value.
278 292
    ///
279
    /// This method decreases the priority of item \c i to \c p.
280
    /// \pre \c i must be stored in the heap with priority at least \c
281
    /// p relative to \c Compare.
293
    /// This function decreases the priority of an item to the given value.
282 294
    /// \param i The item.
283 295
    /// \param p The priority.
296
    /// \pre \e i must be stored in the heap with priority at least \e p.
284 297
    void decrease(const Item &i, const Prio &p) {
285 298
      int idx = _iim[i];
286 299
      unlace(idx);
287 300
      _data[idx].value = p;
288 301
      if (Direction::less(p, _minimum)) {
289 302
        _minimum = p;
290 303
      }
291 304
      lace(idx);
292 305
    }
293 306

	
294
    /// \brief Increases the priority of \c i to \c p.
307
    /// \brief Increase the priority of an item to the given value.
295 308
    ///
296
    /// This method sets the priority of item \c i to \c p.
297
    /// \pre \c i must be stored in the heap with priority at most \c
298
    /// p relative to \c Compare.
309
    /// This function increases the priority of an item to the given value.
299 310
    /// \param i The item.
300 311
    /// \param p The priority.
312
    /// \pre \e i must be stored in the heap with priority at most \e p.
301 313
    void increase(const Item &i, const Prio &p) {
302 314
      int idx = _iim[i];
303 315
      unlace(idx);
304 316
      _data[idx].value = p;
305 317
      lace(idx);
306 318
    }
307 319

	
308
    /// \brief Returns if \c item is in, has already been in, or has
309
    /// never been in the heap.
320
    /// \brief Return the state of an item.
310 321
    ///
311
    /// This method returns PRE_HEAP if \c item has never been in the
312
    /// heap, IN_HEAP if it is in the heap at the moment, and POST_HEAP
313
    /// otherwise. In the latter case it is possible that \c item will
314
    /// get back to the heap again.
322
    /// This method returns \c PRE_HEAP if the given item has never
323
    /// been in the heap, \c IN_HEAP if it is in the heap at the moment,
324
    /// and \c POST_HEAP otherwise.
325
    /// In the latter case it is possible that the item will get back
326
    /// to the heap again.
315 327
    /// \param i The item.
316 328
    State state(const Item &i) const {
317 329
      int idx = _iim[i];
318 330
      if (idx >= 0) idx = 0;
319 331
      return State(idx);
320 332
    }
321 333

	
322
    /// \brief Sets the state of the \c item in the heap.
334
    /// \brief Set the state of an item in the heap.
323 335
    ///
324
    /// Sets the state of the \c item in the heap. It can be used to
325
    /// manually clear the heap when it is important to achive the
326
    /// better time complexity.
336
    /// This function sets the state of the given item in the heap.
337
    /// It can be used to manually clear the heap when it is important
338
    /// to achive better time complexity.
327 339
    /// \param i The item.
328 340
    /// \param st The state. It should not be \c IN_HEAP.
329 341
    void state(const Item& i, State st) {
330 342
      switch (st) {
331 343
      case POST_HEAP:
332 344
      case PRE_HEAP:
333 345
        if (state(i) == IN_HEAP) {
334 346
          erase(i);
335 347
        }
336 348
        _iim[i] = st;
337 349
        break;
338 350
      case IN_HEAP:
339 351
        break;
340 352
      }
341 353
    }
342 354

	
343 355
  private:
344 356

	
345 357
    struct BucketItem {
346 358
      BucketItem(const Item& _item, int _value)
347 359
        : item(_item), value(_value) {}
348 360

	
349 361
      Item item;
350 362
      int value;
351 363

	
352 364
      int prev, next;
353 365
    };
354 366

	
355 367
    ItemIntMap& _iim;
356 368
    std::vector<int> _first;
357 369
    std::vector<BucketItem> _data;
358 370
    mutable int _minimum;
359 371

	
360 372
  }; // class BucketHeap
361 373

	
362
  /// \ingroup auxdat
374
  /// \ingroup heaps
363 375
  ///
364
  /// \brief A Simplified Bucket Heap implementation.
376
  /// \brief Simplified bucket heap data structure.
365 377
  ///
366 378
  /// This class implements a simplified \e bucket \e heap data
367
  /// structure.  It does not provide some functionality but it faster
368
  /// and simplier data structure than the BucketHeap. The main
369
  /// difference is that the BucketHeap stores for every key a double
370
  /// linked list while this class stores just simple lists. In the
371
  /// other way it does not support erasing each elements just the
372
  /// minimal and it does not supports key increasing, decreasing.
379
  /// structure. It does not provide some functionality, but it is
380
  /// faster and simpler than BucketHeap. The main difference is
381
  /// that BucketHeap stores a doubly-linked list for each key while
382
  /// this class stores only simply-linked lists. It supports erasing
383
  /// only for the item having minimum priority and it does not support
384
  /// key increasing and decreasing.
373 385
  ///
374
  /// \param IM A read and write Item int map, used internally
375
  /// to handle the cross references.
376
  /// \param MIN If the given parameter is false then instead of the
377
  /// minimum value the maximum can be retrivied with the top() and
378
  /// prio() member functions.
386
  /// Note that this implementation does not conform to the
387
  /// \ref concepts::Heap "heap concept" due to the lack of some 
388
  /// functionality.
389
  ///
390
  /// \tparam IM A read-writable item map with \c int values, used
391
  /// internally to handle the cross references.
392
  /// \tparam MIN Indicate if the heap is a \e min-heap or a \e max-heap.
393
  /// The default is \e min-heap. If this parameter is set to \c false,
394
  /// then the comparison is reversed, so the top(), prio() and pop()
395
  /// functions deal with the item having maximum priority instead of the
396
  /// minimum.
379 397
  ///
380 398
  /// \sa BucketHeap
381 399
  template <typename IM, bool MIN = true >
382 400
  class SimpleBucketHeap {
383 401

	
384 402
  public:
385
    typedef typename IM::Key Item;
403

	
404
    /// Type of the item-int map.
405
    typedef IM ItemIntMap;
406
    /// Type of the priorities.
386 407
    typedef int Prio;
387
    typedef std::pair<Item, Prio> Pair;
388
    typedef IM ItemIntMap;
408
    /// Type of the items stored in the heap.
409
    typedef typename ItemIntMap::Key Item;
410
    /// Type of the item-priority pairs.
411
    typedef std::pair<Item,Prio> Pair;
389 412

	
390 413
  private:
391 414

	
392 415
    typedef _bucket_heap_bits::DirectionTraits<MIN> Direction;
393 416

	
394 417
  public:
395 418

	
396
    /// \brief Type to represent the items states.
419
    /// \brief Type to represent the states of the items.
397 420
    ///
398
    /// Each Item element have a state associated to it. It may be "in heap",
399
    /// "pre heap" or "post heap". The latter two are indifferent from the
421
    /// Each item has a state associated to it. It can be "in heap",
422
    /// "pre-heap" or "post-heap". The latter two are indifferent from the
400 423
    /// heap's point of view, but may be useful to the user.
401 424
    ///
402 425
    /// The item-int map must be initialized in such way that it assigns
403 426
    /// \c PRE_HEAP (<tt>-1</tt>) to any element to be put in the heap.
404 427
    enum State {
405 428
      IN_HEAP = 0,    ///< = 0.
406 429
      PRE_HEAP = -1,  ///< = -1.
407 430
      POST_HEAP = -2  ///< = -2.
408 431
    };
409 432

	
410 433
  public:
411 434

	
412
    /// \brief The constructor.
435
    /// \brief Constructor.
413 436
    ///
414
    /// The constructor.
415
    /// \param map should be given to the constructor, since it is used
416
    /// internally to handle the cross references. The value of the map
417
    /// should be PRE_HEAP (-1) for each element.
437
    /// Constructor.
438
    /// \param map A map that assigns \c int values to the items.
439
    /// It is used internally to handle the cross references.
440
    /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
418 441
    explicit SimpleBucketHeap(ItemIntMap &map)
419 442
      : _iim(map), _free(-1), _num(0), _minimum(0) {}
420 443

	
421
    /// \brief Returns the number of items stored in the heap.
444
    /// \brief The number of items stored in the heap.
422 445
    ///
423
    /// The number of items stored in the heap.
446
    /// This function returns the number of items stored in the heap.
424 447
    int size() const { return _num; }
425 448

	
426
    /// \brief Checks if the heap stores no items.
449
    /// \brief Check if the heap is empty.
427 450
    ///
428
    /// Returns \c true if and only if the heap stores no items.
451
    /// This function returns \c true if the heap is empty.
429 452
    bool empty() const { return _num == 0; }
430 453

	
431
    /// \brief Make empty this heap.
454
    /// \brief Make the heap empty.
432 455
    ///
433
    /// Make empty this heap. It does not change the cross reference
434
    /// map.  If you want to reuse a heap what is not surely empty you
435
    /// should first clear the heap and after that you should set the
436
    /// cross reference map for each item to \c PRE_HEAP.
456
    /// This functon makes the heap empty.
457
    /// It does not change the cross reference map. If you want to reuse
458
    /// a heap that is not surely empty, you should first clear it and
459
    /// then you should set the cross reference map to \c PRE_HEAP
460
    /// for each item.
437 461
    void clear() {
438 462
      _data.clear(); _first.clear(); _free = -1; _num = 0; _minimum = 0;
439 463
    }
440 464

	
441 465
    /// \brief Insert a pair of item and priority into the heap.
442 466
    ///
443
    /// Adds \c p.first to the heap with priority \c p.second.
467
    /// This function inserts \c p.first to the heap with priority
468
    /// \c p.second.
444 469
    /// \param p The pair to insert.
470
    /// \pre \c p.first must not be stored in the heap.
445 471
    void push(const Pair& p) {
446 472
      push(p.first, p.second);
447 473
    }
448 474

	
449 475
    /// \brief Insert an item into the heap with the given priority.
450 476
    ///
451
    /// Adds \c i to the heap with priority \c p.
477
    /// This function inserts the given item into the heap with the
478
    /// given priority.
452 479
    /// \param i The item to insert.
453 480
    /// \param p The priority of the item.
481
    /// \pre \e i must not be stored in the heap.
454 482
    void push(const Item &i, const Prio &p) {
455 483
      int idx;
456 484
      if (_free == -1) {
457 485
        idx = _data.size();
458 486
        _data.push_back(BucketItem(i));
459 487
      } else {
460 488
        idx = _free;
461 489
        _free = _data[idx].next;
462 490
        _data[idx].item = i;
463 491
      }
464 492
      _iim[i] = idx;
465 493
      if (p >= int(_first.size())) _first.resize(p + 1, -1);
466 494
      _data[idx].next = _first[p];
467 495
      _first[p] = idx;
468 496
      if (Direction::less(p, _minimum)) {
469 497
        _minimum = p;
470 498
      }
471 499
      ++_num;
472 500
    }
473 501

	
474
    /// \brief Returns the item with minimum priority.
502
    /// \brief Return the item having minimum priority.
475 503
    ///
476
    /// This method returns the item with minimum priority.
477
    /// \pre The heap must be nonempty.
504
    /// This function returns the item having minimum priority.
505
    /// \pre The heap must be non-empty.
478 506
    Item top() const {
479 507
      while (_first[_minimum] == -1) {
480 508
        Direction::increase(_minimum);
481 509
      }
482 510
      return _data[_first[_minimum]].item;
483 511
    }
484 512

	
485
    /// \brief Returns the minimum priority.
513
    /// \brief The minimum priority.
486 514
    ///
487
    /// It returns the minimum priority.
488
    /// \pre The heap must be nonempty.
515
    /// This function returns the minimum priority.
516
    /// \pre The heap must be non-empty.
489 517
    Prio prio() const {
490 518
      while (_first[_minimum] == -1) {
491 519
        Direction::increase(_minimum);
492 520
      }
493 521
      return _minimum;
494 522
    }
495 523

	
496
    /// \brief Deletes the item with minimum priority.
524
    /// \brief Remove the item having minimum priority.
497 525
    ///
498
    /// This method deletes the item with minimum priority from the heap.
526
    /// This function removes the item having minimum priority.
499 527
    /// \pre The heap must be non-empty.
500 528
    void pop() {
501 529
      while (_first[_minimum] == -1) {
502 530
        Direction::increase(_minimum);
503 531
      }
504 532
      int idx = _first[_minimum];
505 533
      _iim[_data[idx].item] = -2;
506 534
      _first[_minimum] = _data[idx].next;
507 535
      _data[idx].next = _free;
508 536
      _free = idx;
509 537
      --_num;
510 538
    }
511 539

	
512
    /// \brief Returns the priority of \c i.
540
    /// \brief The priority of the given item.
513 541
    ///
514
    /// This function returns the priority of item \c i.
515
    /// \warning This operator is not a constant time function
516
    /// because it scans the whole data structure to find the proper
517
    /// value.
518
    /// \pre \c i must be in the heap.
542
    /// This function returns the priority of the given item.
519 543
    /// \param i The item.
544
    /// \pre \e i must be in the heap.
545
    /// \warning This operator is not a constant time function because
546
    /// it scans the whole data structure to find the proper value.
520 547
    Prio operator[](const Item &i) const {
521
      for (int k = 0; k < _first.size(); ++k) {
548
      for (int k = 0; k < int(_first.size()); ++k) {
522 549
        int idx = _first[k];
523 550
        while (idx != -1) {
524 551
          if (_data[idx].item == i) {
525 552
            return k;
526 553
          }
527 554
          idx = _data[idx].next;
528 555
        }
529 556
      }
530 557
      return -1;
531 558
    }
532 559

	
533
    /// \brief Returns if \c item is in, has already been in, or has
534
    /// never been in the heap.
560
    /// \brief Return the state of an item.
535 561
    ///
536
    /// This method returns PRE_HEAP if \c item has never been in the
537
    /// heap, IN_HEAP if it is in the heap at the moment, and POST_HEAP
538
    /// otherwise. In the latter case it is possible that \c item will
539
    /// get back to the heap again.
562
    /// This method returns \c PRE_HEAP if the given item has never
563
    /// been in the heap, \c IN_HEAP if it is in the heap at the moment,
564
    /// and \c POST_HEAP otherwise.
565
    /// In the latter case it is possible that the item will get back
566
    /// to the heap again.
540 567
    /// \param i The item.
541 568
    State state(const Item &i) const {
542 569
      int idx = _iim[i];
543 570
      if (idx >= 0) idx = 0;
544 571
      return State(idx);
545 572
    }
546 573

	
547 574
  private:
548 575

	
549 576
    struct BucketItem {
550 577
      BucketItem(const Item& _item)
551 578
        : item(_item) {}
552 579

	
553 580
      Item item;
554 581
      int next;
555 582
    };
556 583

	
557 584
    ItemIntMap& _iim;
558 585
    std::vector<int> _first;
559 586
    std::vector<BucketItem> _data;
560 587
    int _free, _num;
561 588
    mutable int _minimum;
562 589

	
563 590
  }; // class SimpleBucketHeap
564 591

	
565 592
}
566 593

	
567 594
#endif
Ignore white space 6 line context
1 1
/* -*- mode: C++; indent-tabs-mode: nil; -*-
2 2
 *
3 3
 * This file is a part of LEMON, a generic C++ optimization library.
4 4
 *
5 5
 * Copyright (C) 2003-2009
6 6
 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 7
 * (Egervary Research Group on Combinatorial Optimization, EGRES).
8 8
 *
9 9
 * Permission to use, modify and distribute this software is granted
10 10
 * provided that this copyright notice appears in all copies. For
11 11
 * precise terms see the accompanying LICENSE file.
12 12
 *
13 13
 * This software is provided "AS IS" with no warranty of any kind,
14 14
 * express or implied, and with no claim as to its suitability for any
15 15
 * purpose.
16 16
 *
17 17
 */
18 18

	
19 19
#ifndef LEMON_CIRCULATION_H
20 20
#define LEMON_CIRCULATION_H
21 21

	
22 22
#include <lemon/tolerance.h>
23 23
#include <lemon/elevator.h>
24 24
#include <limits>
25 25

	
26 26
///\ingroup max_flow
27 27
///\file
28 28
///\brief Push-relabel algorithm for finding a feasible circulation.
29 29
///
30 30
namespace lemon {
31 31

	
32 32
  /// \brief Default traits class of Circulation class.
33 33
  ///
34 34
  /// Default traits class of Circulation class.
35 35
  ///
36 36
  /// \tparam GR Type of the digraph the algorithm runs on.
37 37
  /// \tparam LM The type of the lower bound map.
38 38
  /// \tparam UM The type of the upper bound (capacity) map.
39 39
  /// \tparam SM The type of the supply map.
40 40
  template <typename GR, typename LM,
41 41
            typename UM, typename SM>
42 42
  struct CirculationDefaultTraits {
43 43

	
44 44
    /// \brief The type of the digraph the algorithm runs on.
45 45
    typedef GR Digraph;
46 46

	
47 47
    /// \brief The type of the lower bound map.
48 48
    ///
49 49
    /// The type of the map that stores the lower bounds on the arcs.
50 50
    /// It must conform to the \ref concepts::ReadMap "ReadMap" concept.
51 51
    typedef LM LowerMap;
52 52

	
53 53
    /// \brief The type of the upper bound (capacity) map.
54 54
    ///
55 55
    /// The type of the map that stores the upper bounds (capacities)
56 56
    /// on the arcs.
57 57
    /// It must conform to the \ref concepts::ReadMap "ReadMap" concept.
58 58
    typedef UM UpperMap;
59 59

	
60 60
    /// \brief The type of supply map.
61 61
    ///
62 62
    /// The type of the map that stores the signed supply values of the 
63 63
    /// nodes. 
64 64
    /// It must conform to the \ref concepts::ReadMap "ReadMap" concept.
65 65
    typedef SM SupplyMap;
66 66

	
67 67
    /// \brief The type of the flow and supply values.
68 68
    typedef typename SupplyMap::Value Value;
69 69

	
70 70
    /// \brief The type of the map that stores the flow values.
71 71
    ///
72 72
    /// The type of the map that stores the flow values.
73 73
    /// It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap"
74 74
    /// concept.
75
#ifdef DOXYGEN
76
    typedef GR::ArcMap<Value> FlowMap;
77
#else
75 78
    typedef typename Digraph::template ArcMap<Value> FlowMap;
79
#endif
76 80

	
77 81
    /// \brief Instantiates a FlowMap.
78 82
    ///
79 83
    /// This function instantiates a \ref FlowMap.
80 84
    /// \param digraph The digraph for which we would like to define
81 85
    /// the flow map.
82 86
    static FlowMap* createFlowMap(const Digraph& digraph) {
83 87
      return new FlowMap(digraph);
84 88
    }
85 89

	
86 90
    /// \brief The elevator type used by the algorithm.
87 91
    ///
88 92
    /// The elevator type used by the algorithm.
89 93
    ///
90
    /// \sa Elevator
91
    /// \sa LinkedElevator
94
    /// \sa Elevator, LinkedElevator
95
#ifdef DOXYGEN
96
    typedef lemon::Elevator<GR, GR::Node> Elevator;
97
#else
92 98
    typedef lemon::Elevator<Digraph, typename Digraph::Node> Elevator;
99
#endif
93 100

	
94 101
    /// \brief Instantiates an Elevator.
95 102
    ///
96 103
    /// This function instantiates an \ref Elevator.
97 104
    /// \param digraph The digraph for which we would like to define
98 105
    /// the elevator.
99 106
    /// \param max_level The maximum level of the elevator.
100 107
    static Elevator* createElevator(const Digraph& digraph, int max_level) {
101 108
      return new Elevator(digraph, max_level);
102 109
    }
103 110

	
104 111
    /// \brief The tolerance used by the algorithm
105 112
    ///
106 113
    /// The tolerance used by the algorithm to handle inexact computation.
107 114
    typedef lemon::Tolerance<Value> Tolerance;
108 115

	
109 116
  };
110 117

	
111 118
  /**
112 119
     \brief Push-relabel algorithm for the network circulation problem.
113 120

	
114 121
     \ingroup max_flow
115 122
     This class implements a push-relabel algorithm for the \e network
116 123
     \e circulation problem.
117 124
     It is to find a feasible circulation when lower and upper bounds
118 125
     are given for the flow values on the arcs and lower bounds are
119 126
     given for the difference between the outgoing and incoming flow
120 127
     at the nodes.
121 128

	
122 129
     The exact formulation of this problem is the following.
123 130
     Let \f$G=(V,A)\f$ be a digraph, \f$lower: A\rightarrow\mathbf{R}\f$
124 131
     \f$upper: A\rightarrow\mathbf{R}\cup\{\infty\}\f$ denote the lower and
125 132
     upper bounds on the arcs, for which \f$lower(uv) \leq upper(uv)\f$
126 133
     holds for all \f$uv\in A\f$, and \f$sup: V\rightarrow\mathbf{R}\f$
127 134
     denotes the signed supply values of the nodes.
128 135
     If \f$sup(u)>0\f$, then \f$u\f$ is a supply node with \f$sup(u)\f$
129 136
     supply, if \f$sup(u)<0\f$, then \f$u\f$ is a demand node with
130 137
     \f$-sup(u)\f$ demand.
131 138
     A feasible circulation is an \f$f: A\rightarrow\mathbf{R}\f$
132 139
     solution of the following problem.
133 140

	
134 141
     \f[ \sum_{uv\in A} f(uv) - \sum_{vu\in A} f(vu)
135 142
     \geq sup(u) \quad \forall u\in V, \f]
136 143
     \f[ lower(uv) \leq f(uv) \leq upper(uv) \quad \forall uv\in A. \f]
137 144
     
138 145
     The sum of the supply values, i.e. \f$\sum_{u\in V} sup(u)\f$ must be
139 146
     zero or negative in order to have a feasible solution (since the sum
140 147
     of the expressions on the left-hand side of the inequalities is zero).
141 148
     It means that the total demand must be greater or equal to the total
142 149
     supply and all the supplies have to be carried out from the supply nodes,
143 150
     but there could be demands that are not satisfied.
144 151
     If \f$\sum_{u\in V} sup(u)\f$ is zero, then all the supply/demand
145 152
     constraints have to be satisfied with equality, i.e. all demands
146 153
     have to be satisfied and all supplies have to be used.
147 154
     
148 155
     If you need the opposite inequalities in the supply/demand constraints
149 156
     (i.e. the total demand is less than the total supply and all the demands
150 157
     have to be satisfied while there could be supplies that are not used),
151 158
     then you could easily transform the problem to the above form by reversing
152 159
     the direction of the arcs and taking the negative of the supply values
153 160
     (e.g. using \ref ReverseDigraph and \ref NegMap adaptors).
154 161

	
155 162
     This algorithm either calculates a feasible circulation, or provides
156 163
     a \ref barrier() "barrier", which prooves that a feasible soultion
157 164
     cannot exist.
158 165

	
159 166
     Note that this algorithm also provides a feasible solution for the
160 167
     \ref min_cost_flow "minimum cost flow problem".
161 168

	
162 169
     \tparam GR The type of the digraph the algorithm runs on.
163 170
     \tparam LM The type of the lower bound map. The default
164 171
     map type is \ref concepts::Digraph::ArcMap "GR::ArcMap<int>".
165 172
     \tparam UM The type of the upper bound (capacity) map.
166 173
     The default map type is \c LM.
167 174
     \tparam SM The type of the supply map. The default map type is
168 175
     \ref concepts::Digraph::NodeMap "GR::NodeMap<UM::Value>".
169 176
  */
170 177
#ifdef DOXYGEN
171 178
template< typename GR,
172 179
          typename LM,
173 180
          typename UM,
174 181
          typename SM,
175 182
          typename TR >
176 183
#else
177 184
template< typename GR,
178 185
          typename LM = typename GR::template ArcMap<int>,
179 186
          typename UM = LM,
180 187
          typename SM = typename GR::template NodeMap<typename UM::Value>,
181 188
          typename TR = CirculationDefaultTraits<GR, LM, UM, SM> >
182 189
#endif
183 190
  class Circulation {
184 191
  public:
185 192

	
186 193
    ///The \ref CirculationDefaultTraits "traits class" of the algorithm.
187 194
    typedef TR Traits;
188 195
    ///The type of the digraph the algorithm runs on.
189 196
    typedef typename Traits::Digraph Digraph;
190 197
    ///The type of the flow and supply values.
191 198
    typedef typename Traits::Value Value;
192 199

	
193 200
    ///The type of the lower bound map.
194 201
    typedef typename Traits::LowerMap LowerMap;
195 202
    ///The type of the upper bound (capacity) map.
196 203
    typedef typename Traits::UpperMap UpperMap;
197 204
    ///The type of the supply map.
198 205
    typedef typename Traits::SupplyMap SupplyMap;
199 206
    ///The type of the flow map.
200 207
    typedef typename Traits::FlowMap FlowMap;
201 208

	
202 209
    ///The type of the elevator.
203 210
    typedef typename Traits::Elevator Elevator;
204 211
    ///The type of the tolerance.
205 212
    typedef typename Traits::Tolerance Tolerance;
206 213

	
207 214
  private:
208 215

	
209 216
    TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
210 217

	
211 218
    const Digraph &_g;
212 219
    int _node_num;
213 220

	
214 221
    const LowerMap *_lo;
215 222
    const UpperMap *_up;
216 223
    const SupplyMap *_supply;
217 224

	
218 225
    FlowMap *_flow;
219 226
    bool _local_flow;
220 227

	
221 228
    Elevator* _level;
222 229
    bool _local_level;
223 230

	
224 231
    typedef typename Digraph::template NodeMap<Value> ExcessMap;
225 232
    ExcessMap* _excess;
226 233

	
227 234
    Tolerance _tol;
228 235
    int _el;
229 236

	
230 237
  public:
231 238

	
232 239
    typedef Circulation Create;
233 240

	
234 241
    ///\name Named Template Parameters
235 242

	
236 243
    ///@{
237 244

	
238 245
    template <typename T>
239 246
    struct SetFlowMapTraits : public Traits {
240 247
      typedef T FlowMap;
241 248
      static FlowMap *createFlowMap(const Digraph&) {
242 249
        LEMON_ASSERT(false, "FlowMap is not initialized");
243 250
        return 0; // ignore warnings
244 251
      }
245 252
    };
246 253

	
247 254
    /// \brief \ref named-templ-param "Named parameter" for setting
248 255
    /// FlowMap type
249 256
    ///
250 257
    /// \ref named-templ-param "Named parameter" for setting FlowMap
251 258
    /// type.
252 259
    template <typename T>
253 260
    struct SetFlowMap
254 261
      : public Circulation<Digraph, LowerMap, UpperMap, SupplyMap,
255 262
                           SetFlowMapTraits<T> > {
256 263
      typedef Circulation<Digraph, LowerMap, UpperMap, SupplyMap,
257 264
                          SetFlowMapTraits<T> > Create;
258 265
    };
259 266

	
260 267
    template <typename T>
261 268
    struct SetElevatorTraits : public Traits {
262 269
      typedef T Elevator;
263 270
      static Elevator *createElevator(const Digraph&, int) {
264 271
        LEMON_ASSERT(false, "Elevator is not initialized");
265 272
        return 0; // ignore warnings
266 273
      }
267 274
    };
268 275

	
269 276
    /// \brief \ref named-templ-param "Named parameter" for setting
270 277
    /// Elevator type
271 278
    ///
272 279
    /// \ref named-templ-param "Named parameter" for setting Elevator
273 280
    /// type. If this named parameter is used, then an external
274 281
    /// elevator object must be passed to the algorithm using the
275 282
    /// \ref elevator(Elevator&) "elevator()" function before calling
276 283
    /// \ref run() or \ref init().
277 284
    /// \sa SetStandardElevator
278 285
    template <typename T>
279 286
    struct SetElevator
280 287
      : public Circulation<Digraph, LowerMap, UpperMap, SupplyMap,
281 288
                           SetElevatorTraits<T> > {
282 289
      typedef Circulation<Digraph, LowerMap, UpperMap, SupplyMap,
283 290
                          SetElevatorTraits<T> > Create;
284 291
    };
285 292

	
286 293
    template <typename T>
287 294
    struct SetStandardElevatorTraits : public Traits {
288 295
      typedef T Elevator;
289 296
      static Elevator *createElevator(const Digraph& digraph, int max_level) {
290 297
        return new Elevator(digraph, max_level);
291 298
      }
292 299
    };
293 300

	
294 301
    /// \brief \ref named-templ-param "Named parameter" for setting
295 302
    /// Elevator type with automatic allocation
296 303
    ///
297 304
    /// \ref named-templ-param "Named parameter" for setting Elevator
298 305
    /// type with automatic allocation.
299 306
    /// The Elevator should have standard constructor interface to be
300 307
    /// able to automatically created by the algorithm (i.e. the
301 308
    /// digraph and the maximum level should be passed to it).
302 309
    /// However an external elevator object could also be passed to the
303 310
    /// algorithm with the \ref elevator(Elevator&) "elevator()" function
304 311
    /// before calling \ref run() or \ref init().
305 312
    /// \sa SetElevator
306 313
    template <typename T>
307 314
    struct SetStandardElevator
308 315
      : public Circulation<Digraph, LowerMap, UpperMap, SupplyMap,
309 316
                       SetStandardElevatorTraits<T> > {
310 317
      typedef Circulation<Digraph, LowerMap, UpperMap, SupplyMap,
311 318
                      SetStandardElevatorTraits<T> > Create;
312 319
    };
313 320

	
314 321
    /// @}
315 322

	
316 323
  protected:
317 324

	
318 325
    Circulation() {}
319 326

	
320 327
  public:
321 328

	
322 329
    /// Constructor.
323 330

	
324 331
    /// The constructor of the class.
325 332
    ///
326 333
    /// \param graph The digraph the algorithm runs on.
327 334
    /// \param lower The lower bounds for the flow values on the arcs.
328 335
    /// \param upper The upper bounds (capacities) for the flow values 
329 336
    /// on the arcs.
330 337
    /// \param supply The signed supply values of the nodes.
331 338
    Circulation(const Digraph &graph, const LowerMap &lower,
332 339
                const UpperMap &upper, const SupplyMap &supply)
333 340
      : _g(graph), _lo(&lower), _up(&upper), _supply(&supply),
334 341
        _flow(NULL), _local_flow(false), _level(NULL), _local_level(false),
335 342
        _excess(NULL) {}
336 343

	
337 344
    /// Destructor.
338 345
    ~Circulation() {
339 346
      destroyStructures();
340 347
    }
341 348

	
342 349

	
343 350
  private:
344 351

	
345 352
    bool checkBoundMaps() {
346 353
      for (ArcIt e(_g);e!=INVALID;++e) {
347 354
        if (_tol.less((*_up)[e], (*_lo)[e])) return false;
348 355
      }
349 356
      return true;
350 357
    }
351 358

	
352 359
    void createStructures() {
353 360
      _node_num = _el = countNodes(_g);
354 361

	
355 362
      if (!_flow) {
356 363
        _flow = Traits::createFlowMap(_g);
357 364
        _local_flow = true;
358 365
      }
359 366
      if (!_level) {
360 367
        _level = Traits::createElevator(_g, _node_num);
361 368
        _local_level = true;
362 369
      }
363 370
      if (!_excess) {
364 371
        _excess = new ExcessMap(_g);
365 372
      }
366 373
    }
367 374

	
368 375
    void destroyStructures() {
369 376
      if (_local_flow) {
370 377
        delete _flow;
371 378
      }
372 379
      if (_local_level) {
373 380
        delete _level;
374 381
      }
375 382
      if (_excess) {
376 383
        delete _excess;
377 384
      }
378 385
    }
379 386

	
380 387
  public:
381 388

	
382 389
    /// Sets the lower bound map.
383 390

	
384 391
    /// Sets the lower bound map.
385 392
    /// \return <tt>(*this)</tt>
386 393
    Circulation& lowerMap(const LowerMap& map) {
387 394
      _lo = &map;
388 395
      return *this;
389 396
    }
390 397

	
391 398
    /// Sets the upper bound (capacity) map.
392 399

	
393 400
    /// Sets the upper bound (capacity) map.
394 401
    /// \return <tt>(*this)</tt>
395 402
    Circulation& upperMap(const UpperMap& map) {
396 403
      _up = &map;
397 404
      return *this;
398 405
    }
399 406

	
400 407
    /// Sets the supply map.
401 408

	
402 409
    /// Sets the supply map.
403 410
    /// \return <tt>(*this)</tt>
404 411
    Circulation& supplyMap(const SupplyMap& map) {
405 412
      _supply = &map;
406 413
      return *this;
407 414
    }
408 415

	
409 416
    /// \brief Sets the flow map.
410 417
    ///
411 418
    /// Sets the flow map.
412 419
    /// If you don't use this function before calling \ref run() or
413 420
    /// \ref init(), an instance will be allocated automatically.
414 421
    /// The destructor deallocates this automatically allocated map,
415 422
    /// of course.
416 423
    /// \return <tt>(*this)</tt>
417 424
    Circulation& flowMap(FlowMap& map) {
418 425
      if (_local_flow) {
419 426
        delete _flow;
420 427
        _local_flow = false;
421 428
      }
422 429
      _flow = &map;
423 430
      return *this;
424 431
    }
425 432

	
426 433
    /// \brief Sets the elevator used by algorithm.
427 434
    ///
428 435
    /// Sets the elevator used by algorithm.
429 436
    /// If you don't use this function before calling \ref run() or
430 437
    /// \ref init(), an instance will be allocated automatically.
431 438
    /// The destructor deallocates this automatically allocated elevator,
432 439
    /// of course.
433 440
    /// \return <tt>(*this)</tt>
434 441
    Circulation& elevator(Elevator& elevator) {
435 442
      if (_local_level) {
436 443
        delete _level;
437 444
        _local_level = false;
438 445
      }
439 446
      _level = &elevator;
440 447
      return *this;
441 448
    }
442 449

	
443 450
    /// \brief Returns a const reference to the elevator.
444 451
    ///
445 452
    /// Returns a const reference to the elevator.
446 453
    ///
447 454
    /// \pre Either \ref run() or \ref init() must be called before
448 455
    /// using this function.
449 456
    const Elevator& elevator() const {
450 457
      return *_level;
451 458
    }
452 459

	
453
    /// \brief Sets the tolerance used by algorithm.
460
    /// \brief Sets the tolerance used by the algorithm.
454 461
    ///
455
    /// Sets the tolerance used by algorithm.
456
    Circulation& tolerance(const Tolerance& tolerance) const {
462
    /// Sets the tolerance object used by the algorithm.
463
    /// \return <tt>(*this)</tt>
464
    Circulation& tolerance(const Tolerance& tolerance) {
457 465
      _tol = tolerance;
458 466
      return *this;
459 467
    }
460 468

	
461 469
    /// \brief Returns a const reference to the tolerance.
462 470
    ///
463
    /// Returns a const reference to the tolerance.
471
    /// Returns a const reference to the tolerance object used by
472
    /// the algorithm.
464 473
    const Tolerance& tolerance() const {
465
      return tolerance;
474
      return _tol;
466 475
    }
467 476

	
468 477
    /// \name Execution Control
469 478
    /// The simplest way to execute the algorithm is to call \ref run().\n
470
    /// If you need more control on the initial solution or the execution,
471
    /// first you have to call one of the \ref init() functions, then
479
    /// If you need better control on the initial solution or the execution,
480
    /// you have to call one of the \ref init() functions first, then
472 481
    /// the \ref start() function.
473 482

	
474 483
    ///@{
475 484

	
476 485
    /// Initializes the internal data structures.
477 486

	
478 487
    /// Initializes the internal data structures and sets all flow values
479 488
    /// to the lower bound.
480 489
    void init()
481 490
    {
482 491
      LEMON_DEBUG(checkBoundMaps(),
483 492
        "Upper bounds must be greater or equal to the lower bounds");
484 493

	
485 494
      createStructures();
486 495

	
487 496
      for(NodeIt n(_g);n!=INVALID;++n) {
488 497
        (*_excess)[n] = (*_supply)[n];
489 498
      }
490 499

	
491 500
      for (ArcIt e(_g);e!=INVALID;++e) {
492 501
        _flow->set(e, (*_lo)[e]);
493 502
        (*_excess)[_g.target(e)] += (*_flow)[e];
494 503
        (*_excess)[_g.source(e)] -= (*_flow)[e];
495 504
      }
496 505

	
497 506
      // global relabeling tested, but in general case it provides
498 507
      // worse performance for random digraphs
499 508
      _level->initStart();
500 509
      for(NodeIt n(_g);n!=INVALID;++n)
501 510
        _level->initAddItem(n);
502 511
      _level->initFinish();
503 512
      for(NodeIt n(_g);n!=INVALID;++n)
504 513
        if(_tol.positive((*_excess)[n]))
505 514
          _level->activate(n);
506 515
    }
507 516

	
508 517
    /// Initializes the internal data structures using a greedy approach.
509 518

	
510 519
    /// Initializes the internal data structures using a greedy approach
511 520
    /// to construct the initial solution.
512 521
    void greedyInit()
513 522
    {
514 523
      LEMON_DEBUG(checkBoundMaps(),
515 524
        "Upper bounds must be greater or equal to the lower bounds");
516 525

	
517 526
      createStructures();
518 527

	
519 528
      for(NodeIt n(_g);n!=INVALID;++n) {
520 529
        (*_excess)[n] = (*_supply)[n];
521 530
      }
522 531

	
523 532
      for (ArcIt e(_g);e!=INVALID;++e) {
524 533
        if (!_tol.less(-(*_excess)[_g.target(e)], (*_up)[e])) {
525 534
          _flow->set(e, (*_up)[e]);
526 535
          (*_excess)[_g.target(e)] += (*_up)[e];
527 536
          (*_excess)[_g.source(e)] -= (*_up)[e];
528 537
        } else if (_tol.less(-(*_excess)[_g.target(e)], (*_lo)[e])) {
529 538
          _flow->set(e, (*_lo)[e]);
530 539
          (*_excess)[_g.target(e)] += (*_lo)[e];
531 540
          (*_excess)[_g.source(e)] -= (*_lo)[e];
532 541
        } else {
533 542
          Value fc = -(*_excess)[_g.target(e)];
534 543
          _flow->set(e, fc);
535 544
          (*_excess)[_g.target(e)] = 0;
536 545
          (*_excess)[_g.source(e)] -= fc;
537 546
        }
538 547
      }
539 548

	
540 549
      _level->initStart();
541 550
      for(NodeIt n(_g);n!=INVALID;++n)
542 551
        _level->initAddItem(n);
543 552
      _level->initFinish();
544 553
      for(NodeIt n(_g);n!=INVALID;++n)
545 554
        if(_tol.positive((*_excess)[n]))
546 555
          _level->activate(n);
547 556
    }
548 557

	
549 558
    ///Executes the algorithm
550 559

	
551 560
    ///This function executes the algorithm.
552 561
    ///
553 562
    ///\return \c true if a feasible circulation is found.
554 563
    ///
555 564
    ///\sa barrier()
556 565
    ///\sa barrierMap()
557 566
    bool start()
558 567
    {
559 568

	
560 569
      Node act;
561 570
      Node bact=INVALID;
562 571
      Node last_activated=INVALID;
563 572
      while((act=_level->highestActive())!=INVALID) {
564 573
        int actlevel=(*_level)[act];
565 574
        int mlevel=_node_num;
566 575
        Value exc=(*_excess)[act];
567 576

	
568 577
        for(OutArcIt e(_g,act);e!=INVALID; ++e) {
569 578
          Node v = _g.target(e);
570 579
          Value fc=(*_up)[e]-(*_flow)[e];
571 580
          if(!_tol.positive(fc)) continue;
572 581
          if((*_level)[v]<actlevel) {
573 582
            if(!_tol.less(fc, exc)) {
574 583
              _flow->set(e, (*_flow)[e] + exc);
575 584
              (*_excess)[v] += exc;
576 585
              if(!_level->active(v) && _tol.positive((*_excess)[v]))
577 586
                _level->activate(v);
578 587
              (*_excess)[act] = 0;
579 588
              _level->deactivate(act);
580 589
              goto next_l;
581 590
            }
582 591
            else {
583 592
              _flow->set(e, (*_up)[e]);
584 593
              (*_excess)[v] += fc;
585 594
              if(!_level->active(v) && _tol.positive((*_excess)[v]))
586 595
                _level->activate(v);
587 596
              exc-=fc;
588 597
            }
589 598
          }
590 599
          else if((*_level)[v]<mlevel) mlevel=(*_level)[v];
591 600
        }
592 601
        for(InArcIt e(_g,act);e!=INVALID; ++e) {
593 602
          Node v = _g.source(e);
594 603
          Value fc=(*_flow)[e]-(*_lo)[e];
595 604
          if(!_tol.positive(fc)) continue;
596 605
          if((*_level)[v]<actlevel) {
597 606
            if(!_tol.less(fc, exc)) {
598 607
              _flow->set(e, (*_flow)[e] - exc);
599 608
              (*_excess)[v] += exc;
600 609
              if(!_level->active(v) && _tol.positive((*_excess)[v]))
601 610
                _level->activate(v);
602 611
              (*_excess)[act] = 0;
603 612
              _level->deactivate(act);
604 613
              goto next_l;
605 614
            }
606 615
            else {
607 616
              _flow->set(e, (*_lo)[e]);
608 617
              (*_excess)[v] += fc;
609 618
              if(!_level->active(v) && _tol.positive((*_excess)[v]))
610 619
                _level->activate(v);
611 620
              exc-=fc;
612 621
            }
613 622
          }
614 623
          else if((*_level)[v]<mlevel) mlevel=(*_level)[v];
615 624
        }
616 625

	
617 626
        (*_excess)[act] = exc;
618 627
        if(!_tol.positive(exc)) _level->deactivate(act);
619 628
        else if(mlevel==_node_num) {
620 629
          _level->liftHighestActiveToTop();
621 630
          _el = _node_num;
622 631
          return false;
623 632
        }
624 633
        else {
625 634
          _level->liftHighestActive(mlevel+1);
626 635
          if(_level->onLevel(actlevel)==0) {
627 636
            _el = actlevel;
628 637
            return false;
629 638
          }
630 639
        }
631 640
      next_l:
632 641
        ;
633 642
      }
634 643
      return true;
635 644
    }
636 645

	
637 646
    /// Runs the algorithm.
638 647

	
639 648
    /// This function runs the algorithm.
640 649
    ///
641 650
    /// \return \c true if a feasible circulation is found.
642 651
    ///
643 652
    /// \note Apart from the return value, c.run() is just a shortcut of
644 653
    /// the following code.
645 654
    /// \code
646 655
    ///   c.greedyInit();
647 656
    ///   c.start();
648 657
    /// \endcode
649 658
    bool run() {
650 659
      greedyInit();
651 660
      return start();
652 661
    }
653 662

	
654 663
    /// @}
655 664

	
656 665
    /// \name Query Functions
657 666
    /// The results of the circulation algorithm can be obtained using
658 667
    /// these functions.\n
659 668
    /// Either \ref run() or \ref start() should be called before
660 669
    /// using them.
661 670

	
662 671
    ///@{
663 672

	
664 673
    /// \brief Returns the flow value on the given arc.
665 674
    ///
666 675
    /// Returns the flow value on the given arc.
667 676
    ///
668 677
    /// \pre Either \ref run() or \ref init() must be called before
669 678
    /// using this function.
670 679
    Value flow(const Arc& arc) const {
671 680
      return (*_flow)[arc];
672 681
    }
673 682

	
674 683
    /// \brief Returns a const reference to the flow map.
675 684
    ///
676 685
    /// Returns a const reference to the arc map storing the found flow.
677 686
    ///
678 687
    /// \pre Either \ref run() or \ref init() must be called before
679 688
    /// using this function.
680 689
    const FlowMap& flowMap() const {
681 690
      return *_flow;
682 691
    }
683 692

	
684 693
    /**
685 694
       \brief Returns \c true if the given node is in a barrier.
686 695

	
687 696
       Barrier is a set \e B of nodes for which
688 697

	
689 698
       \f[ \sum_{uv\in A: u\in B} upper(uv) -
690 699
           \sum_{uv\in A: v\in B} lower(uv) < \sum_{v\in B} sup(v) \f]
691 700

	
692 701
       holds. The existence of a set with this property prooves that a
693 702
       feasible circualtion cannot exist.
694 703

	
695 704
       This function returns \c true if the given node is in the found
696 705
       barrier. If a feasible circulation is found, the function
697 706
       gives back \c false for every node.
698 707

	
699 708
       \pre Either \ref run() or \ref init() must be called before
700 709
       using this function.
701 710

	
702 711
       \sa barrierMap()
703 712
       \sa checkBarrier()
704 713
    */
705 714
    bool barrier(const Node& node) const
706 715
    {
707 716
      return (*_level)[node] >= _el;
708 717
    }
709 718

	
710 719
    /// \brief Gives back a barrier.
711 720
    ///
712 721
    /// This function sets \c bar to the characteristic vector of the
713 722
    /// found barrier. \c bar should be a \ref concepts::WriteMap "writable"
714 723
    /// node map with \c bool (or convertible) value type.
715 724
    ///
716 725
    /// If a feasible circulation is found, the function gives back an
717 726
    /// empty set, so \c bar[v] will be \c false for all nodes \c v.
718 727
    ///
719 728
    /// \note This function calls \ref barrier() for each node,
720 729
    /// so it runs in O(n) time.
721 730
    ///
722 731
    /// \pre Either \ref run() or \ref init() must be called before
723 732
    /// using this function.
724 733
    ///
725 734
    /// \sa barrier()
726 735
    /// \sa checkBarrier()
727 736
    template<class BarrierMap>
728 737
    void barrierMap(BarrierMap &bar) const
729 738
    {
730 739
      for(NodeIt n(_g);n!=INVALID;++n)
731 740
        bar.set(n, (*_level)[n] >= _el);
732 741
    }
733 742

	
734 743
    /// @}
735 744

	
736 745
    /// \name Checker Functions
737 746
    /// The feasibility of the results can be checked using
738 747
    /// these functions.\n
739 748
    /// Either \ref run() or \ref start() should be called before
740 749
    /// using them.
741 750

	
742 751
    ///@{
743 752

	
744 753
    ///Check if the found flow is a feasible circulation
745 754

	
746 755
    ///Check if the found flow is a feasible circulation,
747 756
    ///
748 757
    bool checkFlow() const {
749 758
      for(ArcIt e(_g);e!=INVALID;++e)
750 759
        if((*_flow)[e]<(*_lo)[e]||(*_flow)[e]>(*_up)[e]) return false;
751 760
      for(NodeIt n(_g);n!=INVALID;++n)
752 761
        {
753 762
          Value dif=-(*_supply)[n];
754 763
          for(InArcIt e(_g,n);e!=INVALID;++e) dif-=(*_flow)[e];
755 764
          for(OutArcIt e(_g,n);e!=INVALID;++e) dif+=(*_flow)[e];
756 765
          if(_tol.negative(dif)) return false;
757 766
        }
758 767
      return true;
759 768
    }
760 769

	
761 770
    ///Check whether or not the last execution provides a barrier
762 771

	
763 772
    ///Check whether or not the last execution provides a barrier.
764 773
    ///\sa barrier()
765 774
    ///\sa barrierMap()
766 775
    bool checkBarrier() const
767 776
    {
768 777
      Value delta=0;
769 778
      Value inf_cap = std::numeric_limits<Value>::has_infinity ?
770 779
        std::numeric_limits<Value>::infinity() :
771 780
        std::numeric_limits<Value>::max();
772 781
      for(NodeIt n(_g);n!=INVALID;++n)
773 782
        if(barrier(n))
774 783
          delta-=(*_supply)[n];
775 784
      for(ArcIt e(_g);e!=INVALID;++e)
776 785
        {
777 786
          Node s=_g.source(e);
778 787
          Node t=_g.target(e);
779 788
          if(barrier(s)&&!barrier(t)) {
780 789
            if (_tol.less(inf_cap - (*_up)[e], delta)) return false;
781 790
            delta+=(*_up)[e];
782 791
          }
783 792
          else if(barrier(t)&&!barrier(s)) delta-=(*_lo)[e];
784 793
        }
785 794
      return _tol.negative(delta);
786 795
    }
787 796

	
788 797
    /// @}
789 798

	
790 799
  };
791 800

	
792 801
}
793 802

	
794 803
#endif

Changeset was too big and was cut off... Show full diff

0 comments (0 inline)