COIN-OR::LEMON - Graph Library

Changeset 1532:aa7428d22aaf in lemon-0.x for doc


Ignore:
Timestamp:
07/04/05 17:03:25 (19 years ago)
Author:
Balazs Dezso
Branch:
default
Phase:
public
Convert:
svn:c9d7d8f5-90d6-0310-b91f-818b3a526b0e/lemon/trunk@2023
Message:

Updated but not complete doc for IO.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/graph_io.dox

    r1527 r1532  
    1010\section format The general file format
    1111
    12 The file contains at most four sections in the following order:
     12The file contains sections in the following order:
    1313
    1414\li nodeset
     
    1616\li nodes
    1717\li edges
     18\li attributes
    1819
    1920The nodeset section starts with the following line:
     
    7980start with an \c # character.
    8081
     82The attributes section can handle some information about the graph. It
     83contains in each line an key and the mapped value to key. The key should
     84be a string without whitespace, the value can be from various type.
     85
     86\code
     87@attributes
     88title "Four colored plan graph"
     89author "Balazs DEZSO"
     90copyright "Lemon Library"
     91version 12
     92\endcode
     93
     94\code
     95@end
     96\endcode
     97=======
    8198The file ends with the
    8299
     
    140157
    141158writer.writeEdge("observed", edge);
     159\endcode
     160
     161With \c writeAttribute() function you can write an attribute to the file.
     162
     163\code
     164writer.writeAttribute("author", "Balazs DEZSO");
     165writer.writeAttribute("version", 12);
    142166\endcode
    143167
     
    198222
    199223reader.readEdge("observed", edge);
     224\endcode
     225
     226With \c readAttribute() function you can read an attribute from the file.
     227
     228\code
     229std::string author;
     230writer.readAttribute("author", author);
     231int version;
     232writer.writeAttribute("version", version);
    200233\endcode
    201234
     
    257290The specialization of  writing should be very similar to that of reading.
    258291
     292\section undir Undir graphs
     293
     294In the undir graph format there is an \c undiredgeset section instead of
     295the \c edgeset section. The first line of the section describes the
     296undirected egdes' names and all next lines describes one undirected edge
     297with the the incident nodes and the values of the map.
     298
     299The format handles the directed edge maps as a syntactical sugar, if there
     300is two map which names are the same with a \c '+' and a \c '-' prefix
     301then it can be read as an directed map.
     302
     303\code
     304@undiredgeset
     305             id    capacity +flow -flow
     30632   2       1     4.3      2.0   0.0
     30721   21      5     2.6      0.0   2.6
     30821   12      8     3.4      0.0   0.0
     309\endcode
     310
     311The \c edges section changed to \c undiredges section. This section
     312describes labeled edges and undirected edges. The directed edge label
     313should start with a \c '+' and a \c '-' prefix what decide the direction
     314of the edge.
     315
     316\code
     317@undiredges
     318undiredge 1
     319+edge 5
     320-back 5
     321\endcode
     322
     323There are similar classes to the \c GraphReader ans \c GraphWriter
     324which handle the undirected graphs. These classes are the
     325\c UndirGraphReader and \UndirGraphWriter.
     326
     327The \c readUndirMap() function reads an undirected map and the
     328\c readUndirEdge() reads an undirected edge from the file,
     329
     330\code
     331reader.readUndirEdgeMap("capacity", capacityMap);
     332reader.readEdgeMap("flow", flowMap);
     333...
     334reader.readUndirEdge("undir_edge", undir_edge);
     335reader.readEdge("edge", edge);
     336\endcode
     337
     338\section advanced Advanced features
     339
     340The graph reader and writer classes gives an easy way to read and write
     341graphs. But sometimes we want more advanced features. This way we can
     342use the more general lemon reader and writer interface.
     343
     344The lemon format is an section oriented file format. It contains one or
     345more section, each starts with a line with \c \@ first character.
     346The content of the section this way cannot contain line with \c \@ first
     347character. The file may contains comment lines with \c # first character.
     348
     349The \c LemonReader and \c LemonWriter gives a framework to read and
     350write sections. There are various section reader and section writer
     351classes which can be attached to a \c LemonReader or a \c LemonWriter.
     352
     353There are default section readers and writers for reading and writing
     354item sets, and labeled items in the graph. These reads and writes
     355the format described above. Other type of data can be handled with own
     356section reader and writer classes which are inherited from the
     357\c LemonReader::SectionReader or the \c LemonWriter::SectionWriter classes.
     358
     359The next example defines a special section reader which reads the
     360\c \@description sections into a string:
     361
     362\code
     363class DescriptionReader : LemonReader::SectionReader {
     364protected:
     365  virtual bool header(const std::string& line) {
     366    std::istringstream ls(line);
     367    std::string head;
     368    ls >> head;
     369    return head == "@description";
     370  }
     371
     372  virtual void read(std::istream& is) {
     373    std::string line;
     374    while (getline(is, line)) {
     375      desc += line;
     376    }
     377  }
     378public:
     379
     380  typedef LemonReader::SectionReader Parent;
     381 
     382  DescriptionReader(LemonReader& reader) : Parent(reader) {}
     383
     384  const std::string& description() const {
     385    return description;
     386  }
     387
     388private:
     389  std::string desc;
     390};
     391\endcode
     392
     393The other advanced stuff of the generalized file format is that
     394multiple edgesets can be stored to the same nodeset. It can be used
     395by example as a network traffic matrix.
     396
     397In example there is a network with symmetric links and there are assymetric
     398traffic request on the network. This construction can be stored in an
     399undirected graph and in an directed NewEdgeSetAdaptor class. The example
     400shows the input with the LemonReader class:
     401
     402\code
     403UndirListGraph network;
     404UndirListGraph::UndirEdgeSet<double> capacity;
     405NewEdgeSetAdaptor<UndirListGraph> traffic(network);
     406NewEdgeSetAdaptor<UndirListGraph>::EdgeSet<double> request(network);
     407
     408LemonReader reader(std::cin);
     409NodeSetReader nodesetReader(reader, network);
     410UndirEdgeSetReader undirEdgesetReader(reader, network, nodesetReader);
     411undirEdgesetReader.readEdgeMap("capacity", capacity);
     412EdgeSetReader edgesetReader(reader, traffic, nodesetReader);
     413edgesetReader.readEdgeMap("request", request);
     414
     415reader.run();
     416\endcode
     417
     418Because the GraphReader and the UndirGraphReader can be converted
     419to LemonReader and it can resolve the ID's of the items, the previous
     420result can be achived with the UndirGraphReader class also.
     421
     422
     423\code
     424UndirListGraph network;
     425UndirListGraph::UndirEdgeSet<double> capacity;
     426NewEdgeSetAdaptor<UndirListGraph> traffic(network);
     427NewEdgeSetAdaptor<UndirListGraph>::EdgeSet<double> request(network);
     428
     429UndirGraphReader reader(std::cin, network);
     430reader.readEdgeMap("capacity", capacity);
     431EdgeSetReader edgesetReader(reader, traffic, reader);
     432edgesetReader.readEdgeMap("request", request);
     433
     434reader.run();
     435\endcode
     436
    259437\author Balazs Dezso
    260438*/
Note: See TracChangeset for help on using the changeset viewer.