doc/migration.dox
author Alpar Juttner <alpar@cs.elte.hu>
Tue, 02 Dec 2008 10:17:30 +0000
changeset 442 31d224a3c0af
parent 308 dd4f08b7e203
child 343 956a29f30887
permissions -rw-r--r--
Doc improvements and source unification in radix_sort (#72)
     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 
    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>script/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>script/lemon-0.x-to-1.x.sh</tt> tool replaces all instances of
    57 the words \c graph, \c digraph, \c edge and \c arc, so it replaces them
    58 in strings, comments etc. as well as in all identifiers.</b>
    59 
    60 \section migration-lgf LGF tools
    61  - The \ref lgf-format "LGF file format" has changed,
    62    <tt>\@nodeset</tt> has changed to <tt>\@nodes</tt>,
    63    <tt>\@edgeset</tt> and <tt>\@uedgeset</tt> to <tt>\@arcs</tt> or
    64    <tt>\@edges</tt>, which become completely equivalents. The
    65    <tt>\@nodes</tt>, <tt>\@edges</tt> and <tt>\@uedges</tt> sections are
    66    removed from the format, the content of them should be
    67    the part of <tt>\@attributes</tt> section. The data fields in
    68    the sections must follow a strict format, they must be either character
    69    sequences without whitespaces or quoted strings.
    70  - The <tt>LemonReader</tt> and <tt>LemonWriter</tt> core interfaces
    71    are no longer available.
    72  - The implementation of the general section readers and writers has changed
    73    they are simple functors now. Beside the old
    74    stream based section handling, currently line oriented section
    75    reading and writing are also supported. In the
    76    section readers the lines must be counted manually. The sections
    77    should be read and written with the SectionWriter and SectionReader
    78    classes.
    79  - Instead of the item readers and writers, item converters should be
    80    used. The converters are functors, which map the type to
    81    std::string or std::string to the type. The converters for standard
    82    containers hasn't yet been implemented in the new LEMON. The converters
    83    can return strings in any format, because if it is necessary, the LGF
    84    writer and reader will quote and unquote the given value.
    85  - The DigraphReader and DigraphWriter can used similarly to the
    86    0.x series, however the <tt>read</tt> or <tt>write</tt> prefix of
    87    the member functions are removed.
    88  - The new LEMON supports the function like interface, the \c
    89    digraphReader and \c digraphWriter functions are more convenient than
    90    using the classes directly.
    91 
    92 \section migration-search BFS, DFS and Dijkstra
    93 - <b>Using the function interface of BFS, DFS and %Dijkstra both source and
    94   target nodes can be given as parameters of the <tt>run()</tt> function
    95   (instead of \c bfs(), \c dfs() or \c dijkstra() itself).</b>
    96 - \ref named-templ-param "Named class template parameters" of \c Bfs,
    97   \c Dfs, \c Dijkstra, \c BfsVisit, \c DfsVisit are renamed to start
    98   with "Set" instead of "Def". Namely,
    99   - \c DefPredMap -> \c SetPredMap
   100   - \c DefDistMap -> \c SetDistMap
   101   - \c DefReachedMap -> \c SetReachedMap
   102   - \c DefProcessedMap -> \c SetProcessedMap
   103   - \c DefHeap -> \c SetHeap
   104   - \c DefStandardHeap -> \c SetStandardHeap
   105   - \c DefOperationTraits -> \c SetOperationTraits
   106   - \c DefProcessedMapToBeDefaultMap -> \c SetStandardProcessedMap
   107 
   108 \section migration-error Exceptions and Debug tools
   109 
   110 <b>The class hierarchy of exceptions has largely been simplified. Now,
   111 only the i/o related tools may throw exceptions. All other exceptions
   112 have been replaced with either the \c LEMON_ASSERT or the \c LEMON_DEBUG
   113 macros.</b>
   114 
   115 <b>On the other hand, the parameter order of constructors of the
   116 exceptions has been changed. See \ref IoError and \ref FormatError for
   117 more details.</b>
   118 
   119 \section migration-other Others
   120 - <b>The contents of <tt>graph_utils.h</tt> are moved to <tt>core.h</tt>
   121   and <tt>maps.h</tt>. <tt>core.h</tt> is included by all graph types,
   122   therefore it usually do not have to be included directly.</b>
   123 - <b><tt>path_utils.h</tt> is merged to \c path.h.</b>
   124 - <b>The semantic of the assignment operations and copy constructors of maps
   125   are still under discussion. So, you must copy them by hand (i.e. copy
   126   each entry one-by-one)</b>
   127 - <b>The parameters of the graph copying tools (i.e. \c GraphCopy,
   128   \c DigraphCopy) have to be given in the from-to order.</b>
   129 - \c copyDigraph() and \c copyGraph() are renamed to \c digraphCopy()
   130   and \c graphCopy(), respectively.
   131 - <b>The interface of \ref DynArcLookUp has changed. It is now the same as
   132   of \ref ArcLookUp and \ref AllArcLookUp</b>
   133 - Some map types should also been renamed. Namely,
   134   - \c IntegerMap -> \c RangeMap
   135   - \c StdMap -> \c SparseMap
   136   - \c FunctorMap -> \c FunctorToMap
   137   - \c MapFunctor -> \c MapToFunctor
   138   - \c ForkWriteMap -> \c ForkMap
   139   - \c StoreBoolMap -> \c LoggerBoolMap
   140 - \c dim2::BoundingBox -> \c dim2::Box
   141 
   142 */
   143 }