alpar@2391: /* -*- C++ -*-
alpar@2391:  *
alpar@2391:  * This file is a part of LEMON, a generic C++ optimization library
alpar@2391:  *
alpar@2391:  * Copyright (C) 2003-2007
alpar@2391:  * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
alpar@2391:  * (Egervary Research Group on Combinatorial Optimization, EGRES).
alpar@2391:  *
alpar@2391:  * Permission to use, modify and distribute this software is granted
alpar@2391:  * provided that this copyright notice appears in all copies. For
alpar@2391:  * precise terms see the accompanying LICENSE file.
alpar@2391:  *
alpar@2391:  * This software is provided "AS IS" with no warranty of any kind,
alpar@2391:  * express or implied, and with no claim as to its suitability for any
alpar@2391:  * purpose.
alpar@2391:  *
alpar@2391:  */
alpar@2391: 
alpar@2195: /**
alpar@2195: \page getting_started Getting Started
alpar@2195: 
athos@2288: At the beginning we strongly suggest that you open your favorite text
athos@2288: editor and enter the code simultaneously as you read it. Compiling the
athos@2288: demos is also a good exercise.
alpar@2195: 
athos@2288: As the first example we show you a lemon style "Hello World"
athos@2288: program. Now we explain almost every line, but later we will skip the
athos@2288: basics and focus on new things.
alpar@2195: 
alpar@2195: \section hello_world Hello World in LEMON
alpar@2195: 
alpar@2195: In this little program we give you a taste of the LEMON programming.
alpar@2195: 
alpar@2195: Let's see the code fragment to fragment!
alpar@2195: 
alpar@2195: \dontinclude hello_world.cc
alpar@2195: \skip include
alpar@2195: \until iostream
alpar@2195: 
alpar@2195: We want to use a \c lemon::ListGraph so the include goes like this:
alpar@2195: \skip include
alpar@2195: \until list_graph
alpar@2195: 
alpar@2195: The next few lines are not necessary but useful shortcuts, if you don't
alpar@2195: want to type \c lemon::ListGraph::Node every time.
alpar@2195: \skip using
alpar@2195: \until Edge
alpar@2195: 
athos@2288: For this demo we need to declare a ListGraph and a special NodeMap to
athos@2288: store the characters associated to the graph's nodes.  
alpar@2195: \skip main
alpar@2195: \until char_map
alpar@2195: 
alpar@2195: Adding nodes to the graph is very easy.
alpar@2195: \skip new_node
alpar@2195: \until addNode
alpar@2195: 
athos@2288: When a new node or edge is added to the graph the assigned maps are automatically resized.
athos@2288: So graphs can be built dynamically. The usage of a map is very natural.
alpar@2195: \skip char_map
alpar@2195: \until char_map
alpar@2195: 
athos@2288: Notice that no reference or additional assignment is needed to work with nodes.
alpar@2195: They won't become illegal or won't lead to throwing any exceptions.
athos@2288: You can declare and handle a node like every other basic type such as \c int.
alpar@2195: \skip Store
alpar@2195: \until char_map
alpar@2195: 
alpar@2195: As one expects adding an Edge is similar. You need to define the \b source node
alpar@2195: and the \b destination node. The nodes must belong to the graph of course. The
athos@2288: Edge has the direction from the source to the destination. In some cases you don't
alpar@2195: want the edges to be directed - then you use an undirected graph. For example
alpar@2195: lemon::ListUGraph.
alpar@2195: \skip addEdge
alpar@2195: \until addEdge
alpar@2195: 
alpar@2195: In the next few lines we add some more nodes and edges and to the graph we need.
alpar@2195: Those lines are not very interesting so we skip them, but you find the whole
alpar@2408: working program in file hello_world.cc in the demo section.
alpar@2195: 
alpar@2195: The next statement must be familiar. But what is that INVALID in the \c while
alpar@2195: test statement? In LEMON we usually use the INVALID to check if an object
alpar@2195: contains valid information.
alpar@2195: \skip current_node
alpar@2195: \until {
alpar@2195: 
alpar@2195: We take the current node and write out the character assigned to it. Is's easy
alpar@2195: with the \c char_map.
alpar@2195: \skip std
alpar@2195: \until std
alpar@2195: 
alpar@2195: And here comes the trick. OutEdgeIt iterates on outgoing edges of a given node.
alpar@2195: We pass the current node as argument to it, so the \c edge iterator will stand
alpar@2195: on the first outgoing edge of the current node, or will be INVALID if the node
alpar@2195: has no outgoing edges.
alpar@2195: \skip edge
alpar@2195: \until edge
alpar@2195: 
alpar@2195: The graph we built before is linear, so we know that it ends, when no more outgoing
alpar@2195: edges found. Otherwise the current node must be the node the edge points to.
alpar@2195: Basic information about an edge can be requested from the graph.
alpar@2195: \skip if
alpar@2195: \until }
alpar@2195: 
alpar@2195: Finish the code, just to be precise.
alpar@2195: \skip return
alpar@2195: \until }
alpar@2195: 
alpar@2195: 
alpar@2195: \section compile_hw Compiling Hello World
alpar@2195: To compile this program all you have to do is type in
alpar@2449: \code g++ -ohello_world hello_world.cc \endcode
alpar@2195: and press \c Enter! This is the case if you installed LEMON on your system.
alpar@2195: (For more information see the LEMON installation instructions.)
alpar@2195: 
alpar@2195: This is because LEMON is template library and most of it's code has to be available
alpar@2195: as source code during compilation.
alpar@2195:  
alpar@2195: Most programs using LEMON will compile as easy as this one unless you want to
alpar@2195: use some performance measuring tools LEMON can provide. Then you need to link
alpar@2195: an additional library against your program.
alpar@2195: */