doc/migration.dox
 author Alpar Juttner Thu, 07 May 2009 12:19:41 +0100 changeset 699 e2f99a473998 parent 355 956a29f30887 permissions -rw-r--r--
Merge
     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 namespace lemon {

    20 /*!

    21

    22 \page migration Migration from the 0.x Series

    23

    24 This guide gives an in depth description on what has changed compared

    25 to the 0.x release series.

    26

    27 Many of these changes adjusted automatically by the

    28 <tt>lemon-0.x-to-1.x.sh</tt> tool. Those requiring manual

    29 update 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

    58 strings, comments etc. as well as in all LEMON specific identifiers.

    59 So use the script carefully and make a backup copy of your source files

    60 before 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,

   113 only the i/o related tools may throw exceptions. All other exceptions

   114 have been replaced with either the \c LEMON_ASSERT or the \c LEMON_DEBUG

   115 macros.</b>

   116

   117 <b>On the other hand, the parameter order of constructors of the

   118 exceptions has been changed. See \ref IoError and \ref FormatError for

   119 more 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 }