reference.rst

C++的一个好库。。。现在很流行

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 The Boost Parameter Library Reference Documentation 
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

|(logo)|__

.. |(logo)| image:: ../../../../boost.png
   :alt: Boost

__ ../../../../index.htm

:Authors:       David Abrahams, Daniel Wallin
:Contact:       [e-mail], [e-mail]
:organization:  `Boost Consulting`_
:date:          $Date: 2005/07/17 19:53:01 $

:copyright:     Copyright David Abrahams, Daniel Wallin
                2005. Distributed under the Boost Software License,
                Version 1.0. (See accompanying file LICENSE_1_0.txt
                or copy at http://www.boost.org/LICENSE_1_0.txt)

.. _`Boost Consulting`: http://www.boost-consulting.com


//////////////////////////////////////////////////////////////////////////////

.. contents::
    :depth: 2

//////////////////////////////////////////////////////////////////////////////

.. role:: class
    :class: class

.. role:: concept
    :class: concept

.. role:: function
    :class: function

.. |ArgumentPack| replace:: :concept:`ArgumentPack`
.. |ParameterSpec| replace:: :concept:`ParameterSpec`

.. role:: vellipsis
   :class: vellipsis

.. section-numbering::
    :depth: 2

Preliminaries
=============

This section covers some basic information you'll need to know in
order to understand this reference

Namespaces
----------

In this document, all unqualified identifiers should be assumed to
be defined in namespace ``boost::parameter`` unless otherwise
specified.

Exceptions
----------

No operation described in this document
throws an exception unless otherwise specified.

Thread Safety
-------------

All components of this library can be used safely from multiple
threads without synchronization.  [#thread]_

Typography
----------

Names written in :concept:`sans serif type` represent concepts_.

In code blocks, *italic type* represents unspecified text that
satisfies the requirements given in the detailed description that
follows the code block.

In a specification of the tokens generated by a macro, **bold
type** is used to highlight the position of the expanded macro
argument in the result.

The special character β represents the value of |BOOST_PARAMETER_MAX_ARITY|_.

//////////////////////////////////////////////////////////////////////////////

Terminology
===========

.. |kw| replace:: keyword
.. _kw:

keyword
  The name of a function parameter.

.. _keyword tag type:
.. |keyword tag type| replace:: `keyword tag type`_

keyword tag type
  A type used to uniquely identify a function parameter.  Typically
  its name will be the same as that of the parameter.

.. _positional:
.. |positional| replace:: `positional`_

positional argument
  An argument passed with no explicit |kw|.  Its parameter is
  determined in the usual C++ way: by position with respect to a
  parameter list.

.. _tag type:
.. |tag type| replace:: `tag type`_

tag type
  Shorthand for “\ |keyword tag type|.”

.. _keyword object:
.. |keyword object| replace:: `keyword object`_

keyword object
  An instance of |keyword|_ ``<T>`` for some |tag
  type| ``T``.

.. _tagged reference:
.. |tagged reference| replace:: `tagged reference`_

tagged reference
  An object whose type is associated with a |keyword tag type| (the
  object's *keyword*), and that holds a reference (to the object's
  *value*).  

  As a shorthand, a “tagged reference to ``x``\ ” means a tagged
  reference whose *value* is ``x``.

.. _tagged default:
.. |tagged default| replace:: `tagged default`_

tagged default 
  A |tagged reference| whose *value* represents the value of a
  default argument. 

.. _tagged lazy default:
.. |tagged lazy default| replace:: `tagged lazy default`_

tagged lazy default 
  A |tagged reference| whose *value*, when invoked with no
  arguments, computes a default argument value.

.. _intended argument type:
.. |intended argument type| replace:: `intended argument type`_

intended argument type
  The *intended argument type* of a single-element |ArgumentPack|_ is the
  type of its element's *value*.  The intended argument type of any other
  type ``X`` is ``X`` itself.

.. Note::

   In this reference, we will use concept names (and other names)
   to describe both types and objects, depending on context.  So
   for example, “an |ArgumentPack|_\ ” can refer to a type that
   models |ArgumentPack|_ *or* an object of such a type. 

//////////////////////////////////////////////////////////////////////////////

Concepts
========

This section describes the generic type concepts_ used by the Parameter library. 

.. _concepts: ../../../../more/generic_programming.html#concept

|ArgumentPack|
--------------

An |ArgumentPack| is a collection of |tagged reference|\ s to the
actual arguments passed to a function.

Requirements
............

In the table below, 

* ``A`` is a model of |ArgumentPack|
* ``x`` is an instance of ``A``
* ``u`` is a |keyword object| of type ``K``
* ``v`` is a |tagged default| with |tag type| ``L`` and *value* of type ``D``
* ``w`` is a |tagged lazy default| with |tag type| ``M`` and *value* of type ``E const``
* ``z`` is an |ArgumentPack| containing a single element (as created by |keyword|_\ ``<…>::operator=``)

Any exceptions are thrown from the invocation of ``w``\ 's *value*
will be propagated to the caller.

.. table:: |ArgumentPack| requirements

   +----------+-----------------------------+------------------+--------------------------------------+
   |Expression| Type                        |Requirements      |Semantics/Notes                       |
   +==========+=============================+==================+======================================+
   |``x[u]``  |``binding<A,K>::type``       |``x`` contains an |Returns *b*\ 's *value* (by           |
   |          |                             |element *b* whose |reference).                           |
   |          |                             ||kw|_ is ``K``    |                                      |
   +----------+-----------------------------+------------------+--------------------------------------+
   |``x[u]``  |``binding<A,L,D>::type``     |*none*            |If ``x`` contains an element *b* whose|
   |          |                             |                  ||kw|_ is the same as ``u``\ 's,       |
   |          |                             |                  |returns *b*\ 's *value* (by           |
   |          |                             |                  |reference).  Otherwise, returns ``u``\|
   |          |                             |                  |'s *value*.                           |
   +----------+-----------------------------+------------------+--------------------------------------+
   |``x[w]``  |``lazy_binding<A,M,E>::type``|*none*            |If ``x`` contains an element *b* whose|
   |          |                             |                  ||kw|_ is the same as ``w``\ 's,       |
   |          |                             |                  |returns *b*\ 's *value* (by           |
   |          |                             |                  |reference).  Otherwise, invokes ``w``\|
   |          |                             |                  |'s *value* and returns the result.    |
   +----------+-----------------------------+------------------+--------------------------------------+
   |``x, z``  |Model of |ArgumentPack|      |*none*            |Returns an |ArgumentPack|_ containing |
   |          |                             |                  |all the elements of both ``x`` and    |
   |          |                             |                  |``z``.                                |
   +----------+-----------------------------+------------------+--------------------------------------+



.. _parameterspec:

|ParameterSpec|
---------------

A |ParameterSpec| describes the type requirements for arguments
corresponding to a given |kw|_ and indicates whether the argument
is optional or required.  The table below details the allowed forms
and describes their condition for satisfaction by an actual
argument type. In each row,

.. _conditions:

* ``K`` is the |ParameterSpec|\ 's |keyword tag type|
* ``A`` is an |intended argument type| associated with ``K``, if any
* ``F`` is a unary `MPL lambda expression`_

.. _`MPL lambda expression`: ../../../mpl/doc/refmanual/lambda-expression.html

.. table:: |ParameterSpec| allowed forms and conditions of satisfaction

   +----------------------+--------------+--------------------------------+
   |Type                  |``A`` required|Condition ``A`` must satisfy    |
   +======================+==============+================================+
   ||keyword|_\ ``<K>``   |no            |*n/a*                           |
   +----------------------+--------------+--------------------------------+
   ||optional|_\ ``<K,F>``|no            |``mpl::apply<F,A>::type::value``|
   |                      |              |is ``true``.                    |
   +----------------------+--------------+--------------------------------+
   ||required|_\ ``<K,F>``|yes           |``mpl::apply<F,A>::type::value``|
   |                      |              |is ``true``.                    |
   +----------------------+--------------+--------------------------------+

The information in a |ParameterSpec| is used to `limit`__ the
arguments that will be matched by `forwarding functions`_.  

__ overloadcontrol_
.. _overloadcontrol: index.html#controlling-overload-resolution
.. _forwarding functions: index.html#forwarding-functions


//////////////////////////////////////////////////////////////////////////////

Class Templates
===============

.. |keyword| replace:: ``keyword``
.. _keyword:

``keyword``
-----------

The type of every |keyword object| is a specialization of |keyword|.

:Defined in: `boost/parameter/keyword.hpp`__

__ ../../../../boost/parameter/keyword.hpp

.. parsed-literal::

    template <class Tag>
    struct keyword
    {
        template <class T> |ArgumentPack|_ `operator=`_\(T& value) const;
        template <class T> |ArgumentPack|_ `operator=`_\(T const& value) const;

        template <class T> *tagged default* `operator|`_\(T& x) const;
        template <class T> *tagged default* `operator|`_\(T const& x) const;

        template <class F> *tagged lazy default* `operator||`_\(F const&) const;

        static keyword<Tag>& get_\();
    };


.. |operator=| replace:: ``operator=``
.. _operator=:

``operator=``
  .. parsed-literal::

      template <class T> |ArgumentPack|_ operator=(T& value) const;
      template <class T> |ArgumentPack|_ operator=(T const& value) const;

  :Requires: nothing

  :Returns:
      an |ArgumentPack|_  containing a single |tagged reference| to
      ``value`` with |kw|_ ``Tag`` 

.. _operator|:

``operator|``
  .. parsed-literal::

      template <class T> *tagged default* operator|(T& x) const;
      template <class T> *tagged default* operator|(T const& x) const;

  :Returns: a |tagged default| with *value* ``x`` and |kw|_ ``Tag``.

.. _operator||:

``operator||``
  .. parsed-literal::

      template <class F> *tagged lazy default* operator||(F const& g) const;

  :Requires: ``g()`` is valid, with type ``boost::``\ |result_of|_\
    ``<F()>::type``.  [#no_result_of]_


  :Returns: a |tagged lazy default| with *value* ``g`` and |kw|_ ``Tag``.

.. _get:

``get``
  .. parsed-literal::

        static keyword<Tag>& get\();