ceph/src/boost/libs/graph/doc/bgl_named_params.html

   1 <HTML>
   2 <!--
   3      Copyright (c) Jeremy Siek 2000
   4
   5      Distributed under the Boost Software License, Version 1.0.
   6      (See accompanying file LICENSE_1_0.txt or copy at
   7      http://www.boost.org/LICENSE_1_0.txt)
   8   -->
   9 <Head>
  10 <Title>Boost Graph Library: Named Parameters</Title>
  11 <BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b"
  12         ALINK="#ff0000">
  13 <IMG SRC="../../../boost.png"
  14      ALT="C++ Boost" width="277" height="86">
  15
  16 <BR Clear>
  17
  18 <H1><A NAME="sec:bgl-named-params"></A>
  19 <pre>
  20 bgl_named_params&lt;Param, Type, Rest&gt;
  21 </pre>
  22 </H1>
  23
  24 <p>
  25 Many of the Boost.Graph algorithms have a long list of parameters,
  26 most of which have default values. This causes several problems.
  27 First, C++ does not provide a mechanism for handling default
  28 parameters of template functions. However, this can be overcome by
  29 creating multiply version of an algorithm with different numbers of
  30 parameters with each version providing defaults for some subset of
  31 the parameters. This is the approach used in previous versions of
  32 Boost.Graph. This solution is still unsatisfactory for several
  33 reasons:
  34
  35 <ul>
  36   <li>The defaults for parameters can only been used in a particular
  37   order. If the ordering of the defaults does not fit the users situation
  38   he or she has to resort to providing all the parameters.
  39
  40   <li>Since the list of parameters is long, it is easy to forget
  41    the ordering.
  42 </ul>
  43
  44 <p>
  45 A better solution is provided by <tt>bgl_named_params</tt>. This class
  46 allows users to provide parameters is any order, and matches
  47 arguments to parameters based on parameter names.
  48
  49 <p>
  50 The following code shows an example of calling
  51 <tt>bellman_ford_shortest_paths</tt> using the named parameter
  52 technique. Each of the arguments is passed to a function whose name
  53 indicates which parameter the argument is for. Each of the named
  54 parameters is separated by a <b>period</b>, not a comma.
  55
  56 <pre>
  57   bool r = boost::bellman_ford_shortest_paths(g, int(N),
  58      boost::weight_map(weight).
  59      distance_map(&amp;distance[0]).
  60      predecessor_map(&amp;parent[0]));
  61 </pre>
  62
  63 <p>The order in which the arguments are provided does not matter as
  64 long as they are matched with the correct parameter function.  Here is
  65 an call to <tt>bellman_ford_shortest_paths</tt> that is equivalent to
  66 the one above.
  67
  68 <pre>
  69   bool r = boost::bellman_ford_shortest_paths(g, int(N),
  70      boost::predecessor_map(&amp;parent[0]).
  71      distance_map(&amp;distance[0]).
  72      weight_map(weight));
  73 </pre>
  74
  75 <p>Typically the user never needs to deal with the
  76 <tt>bgl_named_params</tt> class directly, since there are functions
  77 like <tt>boost::weight_map</tt> that create an instance of
  78 <tt>bgl_named_params</tt>.
  79
  80
  81 <br>
  82 <HR>
  83 <TABLE>
  84 <TR valign=top>
  85 <TD nowrap>Copyright &copy; 2000-2001</TD><TD>
  86 <A HREF="http://www.boost.org/people/jeremy_siek.htm">Jeremy Siek</A>,
  87 Indiana University (<A
  88 HREF="mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</A>)<br>
  89 <A HREF="http://www.boost.org/people/liequan_lee.htm">Lie-Quan Lee</A>, Indiana University (<A HREF="mailto:llee@cs.indiana.edu">llee@cs.indiana.edu</A>)<br>
  90 <A HREF="http://www.osl.iu.edu/~lums">Andrew Lumsdaine</A>,
  91 Indiana University (<A
  92 HREF="mailto:lums@osl.iu.edu">lums@osl.iu.edu</A>)
  93 </TD></TR></TABLE>
  94
  95 </BODY>
  96 </HTML>