COIN-OR::LEMON - Graph Library

source: lemon-1.2/doc/migration.dox @ 416:76287c8caa26

Last change on this file since 416:76287c8caa26 was 343:956a29f30887, checked in by Peter Kovacs <kpeter@…>, 16 years ago

Improve the migration script and guide (#166)

  • Safer replacement of 'graph' and 'edge'.
  • Fix the erroneous renaming of [Gg]raphToEps.
  • Fixes and improvements in the migration guide.
File size: 6.5 KB
Line 
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-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
19namespace lemon {
20/*!
21
22\page migration Migration from the 0.x Series
23
24This guide gives an in depth description on what has changed compared
25to the 0.x release series.
26
27Many of these changes adjusted automatically by the
28<tt>lemon-0.x-to-1.x.sh</tt> tool. Those requiring manual
29update are typeset <b>boldface</b>.
30
31\section migration-graph Graph Related Name Changes
32
33- \ref concepts::Digraph "Directed graphs" are called \c Digraph and
34  they have <tt>Arc</tt>s (instead of <tt>Edge</tt>s), while
35  \ref concepts::Graph "undirected graphs" are called \c Graph
36  (instead of \c UGraph) and they have <tt>Edge</tt>s (instead of
37  <tt>UEdge</tt>s). These changes reflected thoroughly everywhere in
38  the library. Namely,
39  - \c Graph -> \c Digraph
40    - \c %ListGraph -> \c ListDigraph, \c %SmartGraph -> \c SmartDigraph etc.
41  - \c UGraph -> \c Graph
42    - \c ListUGraph -> \c ListGraph, \c SmartUGraph -> \c SmartGraph etc.
43  - \c Edge -> \c Arc, \c UEdge -> \c Edge
44  - \c EdgeMap -> \c ArcMap, \c UEdgeMap -> \c EdgeMap
45  - \c EdgeIt -> \c ArcIt, \c UEdgeIt -> \c EdgeIt
46  - Class names and function names containing the words \c graph,
47    \c ugraph, \e edge or \e arc should also be updated.
48- <b>The two endpoints of an (\e undirected) \c Edge can be obtained by the
49  <tt>u()</tt> and <tt>v()</tt> member function of the graph
50  (instead of <tt>source()</tt> and <tt>target()</tt>). This change
51  must be done by hand.</b>
52  \n Of course, you can still use <tt>source()</tt> and <tt>target()</tt>
53  for <tt>Arc</tt>s (directed edges).
54
55\warning
56<b>The <tt>lemon-0.x-to-1.x.sh</tt> script replaces the words \c graph,
57\c ugraph, \c edge and \c uedge in your own identifiers and in
58strings, comments etc. as well as in all LEMON specific identifiers.
59So use the script carefully and make a backup copy of your source files
60before applying the script to them.</b>
61
62\section migration-lgf LGF tools
63 - The \ref lgf-format "LGF file format" has changed,
64   <tt>\@nodeset</tt> has changed to <tt>\@nodes</tt>,
65   <tt>\@edgeset</tt> and <tt>\@uedgeset</tt> to <tt>\@arcs</tt> or
66   <tt>\@edges</tt>, which become completely equivalents. The
67   <tt>\@nodes</tt>, <tt>\@edges</tt> and <tt>\@uedges</tt> sections are
68   removed from the format, the content of them should be
69   the part of <tt>\@attributes</tt> section. The data fields in
70   the sections must follow a strict format, they must be either character
71   sequences without whitespaces or quoted strings.
72 - The <tt>LemonReader</tt> and <tt>LemonWriter</tt> core interfaces
73   are no longer available.
74 - The implementation of the general section readers and writers has changed
75   they are simple functors now. Beside the old
76   stream based section handling, currently line oriented section
77   reading and writing are also supported. In the
78   section readers the lines must be counted manually. The sections
79   should be read and written with the SectionWriter and SectionReader
80   classes.
81 - Instead of the item readers and writers, item converters should be
82   used. The converters are functors, which map the type to
83   std::string or std::string to the type. The converters for standard
84   containers hasn't yet been implemented in the new LEMON. The converters
85   can return strings in any format, because if it is necessary, the LGF
86   writer and reader will quote and unquote the given value.
87 - The DigraphReader and DigraphWriter can used similarly to the
88   0.x series, however the <tt>read</tt> or <tt>write</tt> prefix of
89   the member functions are removed.
90 - The new LEMON supports the function like interface, the \c
91   digraphReader and \c digraphWriter functions are more convenient than
92   using the classes directly.
93
94\section migration-search BFS, DFS and Dijkstra
95- <b>Using the function interface of BFS, DFS and %Dijkstra both source and
96  target nodes can be given as parameters of the <tt>run()</tt> function
97  (instead of \c bfs(), \c dfs() or \c dijkstra() itself).</b>
98- \ref named-templ-param "Named class template parameters" of \c Bfs,
99  \c Dfs, \c Dijkstra, \c BfsVisit, \c DfsVisit are renamed to start
100  with "Set" instead of "Def". Namely,
101  - \c DefPredMap -> \c SetPredMap
102  - \c DefDistMap -> \c SetDistMap
103  - \c DefReachedMap -> \c SetReachedMap
104  - \c DefProcessedMap -> \c SetProcessedMap
105  - \c DefHeap -> \c SetHeap
106  - \c DefStandardHeap -> \c SetStandardHeap
107  - \c DefOperationTraits -> \c SetOperationTraits
108  - \c DefProcessedMapToBeDefaultMap -> \c SetStandardProcessedMap
109
110\section migration-error Exceptions and Debug tools
111
112<b>The class hierarchy of exceptions has largely been simplified. Now,
113only the i/o related tools may throw exceptions. All other exceptions
114have been replaced with either the \c LEMON_ASSERT or the \c LEMON_DEBUG
115macros.</b>
116
117<b>On the other hand, the parameter order of constructors of the
118exceptions has been changed. See \ref IoError and \ref FormatError for
119more details.</b>
120
121\section migration-other Others
122- <b>The contents of <tt>graph_utils.h</tt> are moved to <tt>core.h</tt>
123  and <tt>maps.h</tt>. <tt>core.h</tt> is included by all graph types,
124  therefore it usually do not have to be included directly.</b>
125- <b><tt>path_utils.h</tt> is merged to \c path.h.</b>
126- <b>The semantic of the assignment operations and copy constructors of maps
127  are still under discussion. So, you must copy them by hand (i.e. copy
128  each entry one-by-one)</b>
129- <b>The parameters of the graph copying tools (i.e. \c GraphCopy,
130  \c DigraphCopy) have to be given in the from-to order.</b>
131- \c copyDigraph() and \c copyGraph() are renamed to \c digraphCopy()
132  and \c graphCopy(), respectively.
133- <b>The interface of \ref DynArcLookUp has changed. It is now the same as
134  of \ref ArcLookUp and \ref AllArcLookUp</b>
135- Some map types should also been renamed. Namely,
136  - \c IntegerMap -> \c RangeMap
137  - \c StdMap -> \c SparseMap
138  - \c FunctorMap -> \c FunctorToMap
139  - \c MapFunctor -> \c MapToFunctor
140  - \c ForkWriteMap -> \c ForkMap
141  - \c StoreBoolMap -> \c LoggerBoolMap
142- \c dim2::BoundingBox -> \c dim2::Box
143
144*/
145}
Note: See TracBrowser for help on using the repository browser.