doc/migration.dox
changeset 309 e57e10a8ea1b
parent 307 47ec522b838e
child 314 2cc60866a0c9
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/doc/migration.dox	Wed Oct 08 17:05:01 2008 +0100
     1.3 @@ -0,0 +1,143 @@
     1.4 +/* -*- mode: C++; indent-tabs-mode: nil; -*-
     1.5 + *
     1.6 + * This file is a part of LEMON, a generic C++ optimization library.
     1.7 + *
     1.8 + * Copyright (C) 2003-2008
     1.9 + * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
    1.10 + * (Egervary Research Group on Combinatorial Optimization, EGRES).
    1.11 + *
    1.12 + * Permission to use, modify and distribute this software is granted
    1.13 + * provided that this copyright notice appears in all copies. For
    1.14 + * precise terms see the accompanying LICENSE file.
    1.15 + *
    1.16 + * This software is provided "AS IS" with no warranty of any kind,
    1.17 + * express or implied, and with no claim as to its suitability for any
    1.18 + * purpose.
    1.19 + *
    1.20 + */
    1.21 +
    1.22 +namespace lemon {
    1.23 +/*!
    1.24 +
    1.25 +\page migration Migration from the 0.x Series
    1.26 +
    1.27 +This guide gives an in depth description on what has changed compared
    1.28 +to the 0.x release series.
    1.29 +
    1.30 +Many of these changes adjusted automatically by the
    1.31 +<tt>script/lemon-0.x-to-1.x.sh</tt> tool. Those requiring manual
    1.32 +update are typeset <b>boldface</b>.
    1.33 +
    1.34 +\section migration-graph Graph Related Name Changes
    1.35 +
    1.36 +- \ref concepts::Digraph "Directed graphs" are called \c Digraph and
    1.37 +  they have <tt>Arc</tt>s (instead of <tt>Edge</tt>s), while
    1.38 +  \ref concepts::Graph "undirected graphs" are called \c Graph
    1.39 +  (instead of \c UGraph) and they have <tt>Edge</tt>s (instead of
    1.40 +  <tt>UEdge</tt>s). These changes reflected thoroughly everywhere in
    1.41 +  the library. Namely,
    1.42 +  - \c Graph -> \c Digraph
    1.43 +    - \c %ListGraph -> \c ListDigraph, \c %SmartGraph -> \c SmartDigraph etc.
    1.44 +  - \c UGraph -> \c Graph
    1.45 +    - \c ListUGraph -> \c ListGraph, \c SmartUGraph -> \c SmartGraph etc.
    1.46 +  - \c Edge -> \c Arc, \c UEdge -> \c Edge
    1.47 +  - \c EdgeMap -> \c ArcMap, \c UEdgeMap -> \c EdgeMap
    1.48 +  - \c EdgeIt -> \c ArcIt, \c UEdgeIt -> \c EdgeIt
    1.49 +  - Class names and function names containing the words \c graph,
    1.50 +    \c ugraph, \e edge or \e arc should also be updated.
    1.51 +- <b>The two endpoints of an (\e undirected) \c Edge can be obtained by the
    1.52 +  <tt>u()</tt> and <tt>v()</tt> member function of the graph
    1.53 +  (instead of <tt>source()</tt> and <tt>target()</tt>). This change
    1.54 +  must be done by hand.</b>
    1.55 +  \n Of course, you can still use <tt>source()</tt> and <tt>target()</tt>
    1.56 +  for <tt>Arc</tt>s (directed edges).
    1.57 +
    1.58 +\warning
    1.59 +<b>The <tt>script/lemon-0.x-to-1.x.sh</tt> tool replaces all instances of
    1.60 +the words \c graph, \c digraph, \c edge and \c arc, so it replaces them
    1.61 +in strings, comments etc. as well as in all identifiers.</b>
    1.62 +
    1.63 +\section migration-lgf LGF tools 
    1.64 + - The \ref lgf-format "LGF file format" has changed,
    1.65 +   <tt>\@nodeset</tt> has changed to <tt>\@nodes</tt>,
    1.66 +   <tt>\@edgeset</tt> and <tt>\@uedgeset</tt> to <tt>\@arcs</tt> or
    1.67 +   <tt>\@edges</tt>, which become completely equivalents. The
    1.68 +   <tt>\@nodes</tt>, <tt>\@edges</tt> and <tt>\@uedges</tt> sections are
    1.69 +   removed from the format, the content of them should be
    1.70 +   the part of <tt>\@attributes</tt> section. The data fields in
    1.71 +   the sections must follow a strict format, they must be either character
    1.72 +   sequences without whitespaces or quoted strings.
    1.73 + - The <tt>LemonReader</tt> and <tt>LemonWriter</tt> core interfaces
    1.74 +   are no longer available.
    1.75 + - The implementation of the general section readers and writers has changed
    1.76 +   they are simple functors now. Beside the old
    1.77 +   stream based section handling, currently line oriented section
    1.78 +   reading and writing are also supported. In the
    1.79 +   section readers the lines must be counted manually. The sections
    1.80 +   should be read and written with the SectionWriter and SectionReader
    1.81 +   classes.
    1.82 + - Instead of the item readers and writers, item converters should be
    1.83 +   used. The converters are functors, which map the type to
    1.84 +   std::string or std::string to the type. The converters for standard
    1.85 +   containers hasn't yet been implemented in the new LEMON. The converters
    1.86 +   can return strings in any format, because if it is necessary, the LGF
    1.87 +   writer and reader will quote and unquote the given value.
    1.88 + - The DigraphReader and DigraphWriter can used similarly to the
    1.89 +   0.x series, however the <tt>read</tt> or <tt>write</tt> prefix of
    1.90 +   the member functions are removed.
    1.91 + - The new LEMON supports the function like interface, the \c
    1.92 +   digraphReader and \c digraphWriter functions are more convenient than
    1.93 +   using the classes directly.
    1.94 +
    1.95 +\section migration-search BFS, DFS and Dijkstra
    1.96 +- <b>Using the function interface of BFS, DFS and %Dijkstra both source and
    1.97 +  target nodes can be given as parameters of the <tt>run()</tt> function
    1.98 +  (instead of \c bfs(), \c dfs() or \c dijkstra() itself).</b>
    1.99 +- \ref named-templ-param "Named class template parameters" of \c Bfs,
   1.100 +  \c Dfs, \c Dijkstra, \c BfsVisit, \c DfsVisit are renamed to start
   1.101 +  with "Set" instead of "Def". Namely,
   1.102 +  - \c DefPredMap -> \c SetPredMap
   1.103 +  - \c DefDistMap -> \c SetDistMap
   1.104 +  - \c DefReachedMap -> \c SetReachedMap
   1.105 +  - \c DefProcessedMap -> \c SetProcessedMap
   1.106 +  - \c DefHeap -> \c SetHeap
   1.107 +  - \c DefStandardHeap -> \c SetStandardHeap
   1.108 +  - \c DefOperationTraits -> \c SetOperationTraits
   1.109 +  - \c DefProcessedMapToBeDefaultMap -> \c SetStandardProcessedMap
   1.110 +
   1.111 +\section migration-error Exceptions and Debug tools
   1.112 +
   1.113 +<b>The class hierarchy of exceptions has largely been simplified. Now,
   1.114 +only the i/o related tools may throw exceptions. All other exceptions
   1.115 +have been replaced with either the \c LEMON_ASSERT or the \c LEMON_DEBUG
   1.116 +macros.</b>
   1.117 +
   1.118 +<b>On the other hand, the parameter order of constructors of the
   1.119 +exceptions has been changed. See \ref IoError and \ref FormatError for
   1.120 +more details.</b>
   1.121 +
   1.122 +\section migration-other Others
   1.123 +- <b>The contents of <tt>graph_utils.h</tt> are moved to <tt>core.h</tt>
   1.124 +  and <tt>maps.h</tt>. <tt>core.h</tt> is included by all graph types,
   1.125 +  therefore it usually do not have to be included directly.</b>
   1.126 +- <b><tt>path_utils.h</tt> is merged to \c path.h.</b>
   1.127 +- <b>The semantic of the assignment operations and copy constructors of maps
   1.128 +  are still under discussion. So, you must copy them by hand (i.e. copy
   1.129 +  each entry one-by-one)</b>
   1.130 +- <b>The parameters of the graph copying tools (i.e. \c GraphCopy,
   1.131 +  \c DigraphCopy) have to be given in the from-to order.</b>
   1.132 +- \c copyDigraph() and \c copyGraph() are renamed to \c digraphCopy()
   1.133 +  and \c graphCopy(), respectively.
   1.134 +- <b>The interface of \ref DynArcLookUp has changed. It is now the same as
   1.135 +  of \ref ArcLookUp and \ref AllArcLookUp</b>
   1.136 +- Some map types should also been renamed. Namely,
   1.137 +  - \c IntegerMap -> \c RangeMap
   1.138 +  - \c StdMap -> \c SparseMap
   1.139 +  - \c FunctorMap -> \c FunctorToMap
   1.140 +  - \c MapFunctor -> \c MapToFunctor
   1.141 +  - \c ForkWriteMap -> \c ForkMap
   1.142 +  - \c StoreBoolMap -> \c LoggerBoolMap
   1.143 +- \c dim2::BoundingBox -> \c dim2::Box
   1.144 +
   1.145 +*/
   1.146 +}