[boost-doc-zh] r421 committed - 翻译 variant 库的 qbk/xml 文件
- From: boost-doc-zh@xxxxxxxxxxxxxx
- To: boost-doc-zh-notify@xxxxxxxxxxxxx
- Date: Tue, 20 Jul 2010 06:55:30 +0000
Revision: 421
Author: alai04
Date: Mon Jul 19 23:54:43 2010
Log: 翻译 variant 库的 qbk/xml 文件
http://code.google.com/p/boost-doc-zh/source/detail?r=421
Modified:
/trunk/libs/variant/doc/biblio.xml
/trunk/libs/variant/doc/design.xml
/trunk/libs/variant/doc/introduction.xml
/trunk/libs/variant/doc/misc.xml
/trunk/libs/variant/doc/reference/apply_visitor.xml
/trunk/libs/variant/doc/reference/bad_visit.xml
/trunk/libs/variant/doc/reference/get.xml
/trunk/libs/variant/doc/reference/recursive_variant.xml
/trunk/libs/variant/doc/reference/recursive_wrapper.xml
/trunk/libs/variant/doc/reference/reference.xml
/trunk/libs/variant/doc/reference/static_visitor.xml
/trunk/libs/variant/doc/reference/variant.xml
/trunk/libs/variant/doc/reference/variant_fwd.xml
/trunk/libs/variant/doc/reference/visitor_ptr.xml
/trunk/libs/variant/doc/tutorial/advanced.xml
/trunk/libs/variant/doc/tutorial/basic.xml
/trunk/libs/variant/doc/tutorial/tutorial.xml
=======================================
--- /trunk/libs/variant/doc/biblio.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/variant/doc/biblio.xml Mon Jul 19 23:54:43 2010
@@ -2,7 +2,7 @@
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
<section id="variant.refs">
- <title>References</title>
+ <title>References 参考书目</title>
<para id="variant.refs.abr00">
<ulink
url="http://boost.org/more/generic_exception_safety.html";>[Abr00]</ulink>
=======================================
--- /trunk/libs/variant/doc/design.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/variant/doc/design.xml Mon Jul 19 23:54:43 2010
@@ -2,50 +2,62 @@
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
<section id="variant.design">
- <title>Design Overview</title>
+ <title>Design Overview 设计概览</title>
<using-namespace name="boost"/>
<section id="variant.design.never-empty">
- <title>"Never-Empty" Guarantee</title>
+ <title>"Never-Empty" Guarantee "非空"保证</title>
<section id="variant.design.never-empty.guarantee">
- <title>The Guarantee</title>
+ <title>The Guarantee 保证</title>
<para>All instances <code>v</code> of type
<code><classname>variant</classname><T1,T2,...,TN></code>
guarantee that <code>v</code> has constructed content of one of the
types <code>T<emphasis>i</emphasis></code>, even if an operation on
- <code>v</code> has previously failed.</para>
+ <code>v</code> has previously failed.<sbr/>
+ 类型
<code><classname>variant</classname><T1,T2,...,TN></code> 的所有实例
+ <code>v</code> 均保证，<code>v</code> 具有某个类型
<code>T<emphasis>i</emphasis></code>
+ 的已构造内容，即使之前对 <code>v</code><code>v</code> 的某项操作失
败了。</para>
<para>This implies that <code>variant</code> may be viewed precisely
as
a union of <emphasis>exactly</emphasis> its bounded types. This
"never-empty" property insulates the user from the
possibility of undefined <code>variant</code> content and the
significant additional complexity-of-use attendant with such a
- possibility.</para>
+ possibility.<sbr/>
+ 这意味着 <code>variant</code> 可以被视为其有界类型的一个联合。
+ 这个 "非空" 的特性使得用户不会遇到未定义的
<code>variant</code> 内容，因此也不需要额外的复杂用法。</para>
</section>
<section id="variant.design.never-empty.problem">
- <title>The Implementation Problem</title>
+ <title>The Implementation Problem 实现的问题</title>
<para>While the
<link linkend="variant.design.never-empty.guarantee">never-empty
guarantee</link>
might at first seem "obvious," it is in fact not even
straightforward how to implement it in general (i.e., without
unreasonably restrictive additional requirements on
- <link linkend="variant.concepts.bounded-type">bounded
types</link>).</para>
+ <link linkend="variant.concepts.bounded-type">bounded
types</link>).<sbr/>
+ 虽然 <link linkend="variant.design.never-empty.guarantee">非空保证
</link> 看上去很 ""明显"，
+ 实际上如何在通常的情况下(即，不给 <link
linkend="variant.concepts.bounded-type">有界类型</link> 增加不合理的限制)
+ 实现它却一点都不简单。</para>
<para>The central difficulty emerges in the details of
<code>variant</code> assignment. Given two instances
<code>v1</code>
and <code>v2</code> of some concrete <code>variant</code> type,
there
are two distinct, fundamental cases we must consider for the
assignment
- <code>v1 = v2</code>.</para>
+ <code>v1 = v2</code>.<sbr/>
+ 主要的困难在于 <code>variant</code> 赋值的细节上。给定某个
<code>variant</code> 类型的两个实例
+ <code>v1</code> 和 <code>v2</code>, 在赋值 <code>v1 = v2</code>
时，我们必须考虑两种截然不同的情形。</para>
<para>First consider the case that <code>v1</code> and
<code>v2</code>
each contains a value of the same type. Call this type
<code>T</code>.
In this situation, assignment is perfectly straightforward: use
- <code>T::operator=</code>.</para>
+ <code>T::operator=</code>.<sbr/>
+ 首先考虑 <code>v1</code> 和 <code>v2</code> 含有相同类型的值的情
形。
+ 我们称这个类型为 <code>T</code>. 在这种情况下，赋值很简单：使用
<code>T::operator=</code> 就行了。</para>
<para>However, we must also consider the case that <code>v1</code>
and
<code>v2</code> contain values <emphasis>of distinct
types</emphasis>.
@@ -56,95 +68,129 @@
of the right-hand side (i.e., <code>v2</code>). In the end, whereas
<code>v1</code> began with content of type <code>T</code>, it ends
with content of type <code>U</code>, namely a copy of the content
of
- <code>v2</code>.</para>
+ <code>v2</code>.<sbr/>
+ 不过，我们还必须考虑 <code>v1</code> 和 <code>v2</code> 含有
<emphasis>不同类型</emphasis>的值的情形。
+ 我们分别称这两类型为 <code>T</code> 和 <code>U</code>. 这时，由于
<code>variant</code> 是在栈上管理其内容的，
+ 赋值的左操作数(即 <code>v1</code>)必须销毁其内容并允许就地复制构造
右操作数(即 <code>v2</code>)的内容。
+ 最后，<code>v1</code> 以类型 <code>T</code> 内容开始而以类型
<code>U</code> 的内容结束，具有
+ <code>v2</code> 的内容的拷贝。</para>
<para>The crux of the problem, then, is this: in the event that
copy-construction of the content of <code>v2</code> fails, how can
<code>v1</code> maintain its "never-empty" guarantee?
By the time copy-construction from <code>v2</code> is attempted,
- <code>v1</code> has already destroyed its content!</para>
+ <code>v1</code> has already destroyed its content!<sbr/>
+ 该问题的症结在于：如果对 <code>v2</code> 内容的复制构造失败，那么
<code>v1</code> 如何维持其 "非空" 保证？
+ 在尝试对 <code>v2</code> 进行复制构造时，<code>v1</code> 已经销毁了
它的内容了！</para>
</section>
<section id="variant.design.never-empty.memcpy-solution">
- <title>The "Ideal" Solution: False Hopes</title>
+ <title>The "Ideal" Solution: False Hopes "完美的
"方案：错误的期望</title>
<para>Upon learning of this dilemma, clever individuals may propose
the
- following scheme hoping to solve the problem:
+ following scheme hoping to solve the problem:<sbr/>
+ 在了解了这一困难局面后，聪明的程序员可能会提出以下方法，希望可以解
决这个问题：
<orderedlist>
<listitem>Provide some "backup" storage, appropriately
aligned, capable of holding values of the contained type of the
- left-hand side.</listitem>
+ left-hand side.<sbr/>
+ 提供一些"后备"存储，进行适当的对齐，用以保存左操作数
所含的值。</listitem>
<listitem>Copy the memory (e.g., using <code>memcpy</code>) of
the
- storage of the left-hand side to the backup storage.</listitem>
+ storage of the left-hand side to the backup storage.<sbr/>
+ 将左操作数的存储内存复制(如，使用 <code>memcpy</code>)到后备的
存储中。</listitem>
<listitem>Attempt a copy of the right-hand side content to the
- (now-replicated) left-hand side storage.</listitem>
+ (now-replicated) left-hand side storage.<sbr/>
+ 尝试将右操作数复制到(现在已备份)左操作数的存储中。</listitem>
<listitem>In the event of an exception from the copy, restore the
backup (i.e., copy the memory from the backup storage back into
- the left-hand side storage).</listitem>
+ the left-hand side storage).<sbr/>
+ 如果复制操作出现异常，则从备份中进行恢复(即，从后备存储中复制内
存到左操作数的存储中)。 </listitem>
<listitem>Otherwise, in the event of success, now copy the memory
of the left-hand side storage to another "temporary"
- aligned storage.</listitem>
+ aligned storage.<sbr/>
+ 否则，复制成功，将左操作数的存储内存复制到另一个"临时
"的对齐存储中。</listitem>
<listitem>Now restore the backup (i.e., again copying the memory)
to the left-hand side storage; with the "old" content
now restored, invoke the destructor of the contained type on
the
- storage of the left-hand side.</listitem>
+ storage of the left-hand side.<sbr/>
+ 现在恢复备份(即再次复制内存)到左操作数的存储中；在"旧的
"内容恢复后，
+ 调用左操作数所含类型的析构函数。</listitem>
<listitem>Finally, copy the memory of the temporary storage to
the
- (now-empty) storage of the left-hand side.</listitem>
+ (now-empty) storage of the left-hand side.<sbr/>
+ 最后，从临时存储中复制内存到(现在为空)左操作数的存储中。
</listitem>
</orderedlist>
</para>
<para>While complicated, it appears such a scheme could provide the
desired safety in a relatively efficient manner. In fact, several
- early iterations of the library implemented this very
approach.</para>
+ early iterations of the library implemented this very
approach.<sbr/>
+ 虽然有点复杂，但看起来这个方法以相对高效的方式提供了想要的安全性。
+ 实际上，本库的几个早期版本正是以这一方法实现的。</para>
<para>Unfortunately, as Dave Abraham's first noted, the scheme
results
- in undefined behavior:
+ in undefined behavior:<sbr/>
+ 不幸的是，正如 Dave Abraham 首先指出的，这个方法会导致未定义行为：
<blockquote>
<para>"That's a lot of code to read through, but if it's
- doing what I think it's doing, it's undefined behavior.</para>
+ doing what I think it's doing, it's undefined behavior.<sbr/>
+ "从头读下来，这有很多代码，不过，如果这段代码确实是按照我
所想的去做的话，它将是一个未定义的行为。</para>
<para>"Is the trick to move the bits for an existing object
into a buffer so we can tentatively construct a new object in
that memory, and later move the old bits back temporarily to
- destroy the old object?</para>
+ destroy the old object?<sbr/>
+ "将一个已有对象的 bits 移动到另一个缓冲区，好让我们可以试
验性地在这片内存中构造一个新的对象，
+ 然后再从临时存储中将 bits 移回并销毁旧的对象，这是否是一个骗
局？</para>
<para>"The standard does not give license to do that: only
one
object may have a given address at a time. See 3.8, and
- particularly paragraph 4."</para>
+ particularly paragraph 4."<sbr/>
+ ""标准中并没有允许这样做：在一个时候只能有一个对象可
以拥有一个给定的地址。
+ 请见标准的 3.8 节，特别是第4段。""</para>
</blockquote>
</para>
<para>Additionally, as close examination quickly reveals, the scheme
has
the potential to create irreconcilable race-conditions in
concurrent
- environments.</para>
+ environments.<sbr/>
+ 此外，后来的测试很快就表明，这个方法在并行环境下有可能会创建矛盾的
竞争条件。</para>
<para>Ultimately, even if the above scheme could be made to work on
certain platforms with particular compilers, it is still necessary
to
- find a portable solution.</para>
+ find a portable solution.<sbr/>
+ 最后，即使以上方法可以在特定平台的特定编译器上工作，也还需要找到可
移植的解决方案。</para>
</section>
<section id="variant.design.never-empty.double-storage-solution">
- <title>An Initial Solution: Double Storage</title>
+ <title>An Initial Solution: Double Storage 初步的方案：双存储</title>
<para>Upon learning of the infeasibility of the above scheme, Anthony
Williams proposed in
<link linkend="variant.refs.wil02">[Wil02]</link> a scheme that
served
as the basis for a portable solution in some pre-release
- implementations of <code>variant</code>.</para>
+ implementations of <code>variant</code>.<sbr/>
+ 了解到以上方法的不可行之后，Anthony Williams 在 <link
linkend="variant.refs.wil02">[Wil02]</link>
+ 中提议了另一个方法，作为可移植的 <code>variant</code> 的预发布版本
实现。</para>
<para>The essential idea to this scheme, which shall be referred to
as
the "double storage" scheme, is to provide enough space
within a <code>variant</code> to hold two separate values of any of
- the bounded types.</para>
+ the bounded types.<sbr/>
+ 这个方法的基本思想被称为 "双存储"，为一个
<code>variant</code>
+ 提供足够的空间来保存任意两个有界类型的值。</para>
<para>With the secondary storage, a copy the right-hand side can be
attempted without first destroying the content of the left-hand
side;
accordingly, the content of the left-hand side remains available in
- the event of an exception.</para>
+ the event of an exception.<sbr/>
+ 有了第二份存储，就可以在不销毁左操作数的内容的前提下尝试对右操作数
的复制；
+ 因此，在发生异常时左操作数的内容仍保持有效。</para>
<para>Thus, with this scheme, the <code>variant</code> implementation
needs only to keep track of which storage contains the content --
and
- dispatch any visitation requests, queries, etc. accordingly.</para>
+ dispatch any visitation requests, queries, etc. accordingly.<sbr/>
+ 所以，基于此方法，<code>variant</code> 的实现只需跟踪哪一份存储保存
了当前内容 --
+ 从而对所有访问请示、查询等进行分派。</para>
<para>The most obvious flaw to this approach is the space overhead
incurred. Though some optimizations could be applied in special
cases
@@ -155,15 +201,20 @@
the use of double storage. In particular, it was noted that the
overhead of double storage would be at play at all times -- even if
assignment to <code>variant</code> never occurred. For this reason
- and others, a new approach was developed.</para>
+ and others, a new approach was developed.<sbr/>
+ 这一方法最明显的缺点就是空间的开销。虽然在特殊情况下可以进行一些优
化以消除对两份存储的需要 --
+ 对于特定的有界类型或在某些情形下(相关细节请看 <xref
linkend="variant.design.never-empty.optimizations"/>) --
+ 但是在 Boost 邮件列表中的大多数用户还是强烈反对使用双存储。具体地
说，双份存储的的开销几乎在所有时间都需要 --
+ 即使从未对 <code>variant</code> 进行过赋值。由于这些那些的原因，我
们开发了新的方法。</para>
</section>
<section id="variant.design.never-empty.heap-backup-solution">
- <title>Current Approach: Temporary Heap Backup</title>
+ <title>Current Approach: Temporary Heap Backup 当前的方法：临时的堆备
份</title>
<para>Despite the many objections to the double storage solution, it
was
realized that no replacement would be without drawbacks. Thus, a
- compromise was desired.</para>
+ compromise was desired.<sbr/>
+ 尽管对于双存储方案有很多的反对意见，但是我们还是认识到不存在没有缺
点的替代方案。因此，我们需要一些折衷。</para>
<para>To this end, Dave Abrahams suggested to include the following
in
the behavior specification for <code>variant</code> assignment:
@@ -172,20 +223,29 @@
continue to store its content <emphasis>in situ</emphasis> after
construction and after assignment involving identical contained
types,
<code>variant</code> would store its content on the heap after
- assignment involving distinct contained types.</para>
-
- <para>The algorithm for assignment would proceed as follows:
+ assignment involving distinct contained types.<sbr/>
+ 最后，Dave Abrahams 建议对 <code>variant</code> 的赋值行为增加以下
规定："从一个类型到另一个类型的
+ <code>variant</code> 赋值可能引起动态分配"。即，虽然
<code>variant</code>
+ 依然保持在构造后以及在赋予相同类型的值后，原位保存其内容，但是如果
被赋予不同类型的值，则
+ <code>variant</code> 可能将其内容保存在堆上。</para>
+
+ <para>The algorithm for assignment would proceed as follows:<sbr/>
+ 赋值的算法将如下处理：
<orderedlist>
<listitem>Copy-construct the content of the right-hand side to
the
- heap; call the pointer to this data <code>p</code>.</listitem>
- <listitem>Destroy the content of the left-hand side.</listitem>
+ heap; call the pointer to this data <code>p</code>.<sbr/>
+ 将右操作数的内容复制构造到堆上；该数据的指针称为
<code>p</code>.</listitem>
+ <listitem>Destroy the content of the left-hand side.<sbr/>
+ 销毁左操作数的内容。</listitem>
<listitem>Copy <code>p</code> to the left-hand side
- storage.</listitem>
+ storage.<sbr/>
+ 将 <code>p</code> 复制到左操作数的存储中。</listitem>
</orderedlist>
Since all operations on pointers are nothrow, this scheme would
allow
- <code>variant</code> to meet its never-empty guarantee.
+ <code>variant</code> to meet its never-empty guarantee.<sbr/>
+ 因为所有对指针的操作都是不会抛出的，该方法将使得
<code>variant</code> 满足其非空保证。
</para>
<para>The most obvious concern with this approach is that while it
@@ -194,19 +254,28 @@
assignment -- not just in terms of the initial allocation but also
as a result of the continued storage of the content on the heap.
While
the former problem is unavoidable, the latter problem may be
avoided
- with the following "temporary heap backup" technique:
+ with the following "temporary heap backup"
technique:<sbr/>
+ 对于这个方法，最值得留意的是，虽然它的确消除了双份存储的空间开销，
+ 但是它将动态分配的开销引入到了 <code>variant</code> 的赋值之中 --
+ 不仅是初始的分配，而且内容将被长期保存在堆上。
+ 虽然前一个问题是不可避免的，但后一个问题可以通过以下 "临时的堆备
份" 技术得以避免：
<orderedlist>
<listitem>Copy-construct the content of the
<emphasis>left</emphasis>-hand side to the heap; call the
pointer to
- this data <code>backup</code>.</listitem>
- <listitem>Destroy the content of the left-hand side.</listitem>
+ this data <code>backup</code>.<sbr/>
+ 将<emphasis>左</emphasis>操作数的内容复制构造到堆上；该数据的指
针称为 <code>backup</code>. </listitem>
+ <listitem>Destroy the content of the left-hand side.<sbr/>
+ 销毁左操作数的内容。</listitem>
<listitem>Copy-construct the content of the right-hand side in
the
- (now-empty) storage of the left-hand side.</listitem>
+ (now-empty) storage of the left-hand side.<sbr/>
+ 将右操作数的内容复制构造到(现在为空的)左操作数的存储中。
</listitem>
<listitem>In the event of failure, copy <code>backup</code> to
the
- left-hand side storage.</listitem>
+ left-hand side storage.<sbr/>
+ 如果失败，则将 <code>backup</code> 复制到左操作数的存储中。
</listitem>
<listitem>In the event of success, deallocate the data pointed to
- by <code>backup</code>.</listitem>
+ by <code>backup</code>.<sbr/>
+ 如果成功，则释放 <code>backup</code> 所指的数据。</listitem>
</orderedlist>
</para>
@@ -215,7 +284,10 @@
fails; and 3) after any <emphasis>successful</emphasis> assignment,
storage within the <code>variant</code> is guaranteed. For the
purposes of the initial release of the library, these
characteristics
- were deemed a satisfactory compromise solution.</para>
+ were deemed a satisfactory compromise solution.<sbr/>
+ 通过这种技术：1) 只使用了单份存储；2) 只有当赋值失败时，堆上的分配
才是长期的；
+ 3) <emphasis>成功</emphasis>赋值后，<code>variant</code> 的存储得以
保证。
+ 对于本库的初次发布的目的，这些特性已经可以被认为是一个满意的折衷方
案。</para>
<para>There remain notable shortcomings, however. In particular,
there
may be some users for which heap allocation must be avoided at all
@@ -227,11 +299,17 @@
<emphasis>are</emphasis> certain things the user can do to ensure
the
greatest efficiency for <code>variant</code> instances (see
<xref linkend="variant.design.never-empty.optimizations"/> for
- details).</para>
+ details).<sbr/>
+ 不过，还有一些值得注意的缺点。具体地说，可能有些用户要求不惜代价必
须避免堆分配；
+ 而其它用户则要求通过一个用户提供的分配器来进行堆分配。这些问题将在
以后解决
+ (请见 <xref linkend="variant.design.never-empty.roadmap"/>)。
+ 目前，本库将内容的存储方式作为一个实现细节。虽然如此，就象下一节所
要讲述的，
+ 有一些事情是用户可以做的，以确保 <code>variant</code> 实例具有最高
的效率(详情请见
+ <xref linkend="variant.design.never-empty.optimizations"/>)。
</para>
</section>
<section id="variant.design.never-empty.optimizations">
- <title>Enabling Optimizations</title>
+ <title>Enabling Optimizations 进行优化</title>
<para>As described in
<xref linkend="variant.design.never-empty.problem"/>, the central
@@ -241,11 +319,17 @@
face this possibility. Similarly, if one of the bounded types of
the
<code>variant</code> is nothrow default-constructible, then such a
type could be used as a safe "fallback" type in the
event of
- failed copy construction.</para>
+ failed copy construction.<sbr/>
+ 正如在 <xref linkend="variant.design.never-empty.problem"/> 中所
讲，
+ 实现"非空保证"的主要困难在于，在 <code>variant</code> 赋值的过程中
有可能发生复制构造的失败。
+ 不过，具有不抛出异常的复制构造函数的类型显然不会面临这种可能性。
+ 同样，如果 <code>variant</code> 的某个有界类型可以无抛出地缺省构
造，
+ 那么这一类型就可被用作复制构造失败后的安全 "回退" 类型。</para>
<para>Accordingly, <code>variant</code> is designed to enable the
following optimizations once the following criteria on its bounded
- types are met:
+ types are met:<sbr/>
+ 因此，<code>variant</code> 被设计为如果其有界类型符合以下标准，就可
以使用以下优化：
<itemizedlist>
@@ -253,7 +337,10 @@
copy-constructible (as indicated by
<code><classname>boost::has_nothrow_copy</classname></code>),
the
library guarantees <code>variant</code> will use only single
- storage and in-place construction for
<code>T</code>.</listitem>
+ storage and in-place construction for <code>T</code>.<sbr/>
+ 对于每个可以无抛出复制构造(就象
<code><classname>boost::has_nothrow_copy</classname></code>
+ 那样)的有界类型 <code>T</code>, 本库保证 <code>variant</code>
只使用单份存储且就地进行
+ <code>T</code> 的构造。</listitem>
<listitem>If <emphasis>any</emphasis> bounded type is nothrow
default-constructible (as indicated by
@@ -264,7 +351,10 @@
the event of assignment failure, an unspecified nothrow
default-constructible bounded type will be default-constructed
in
the left-hand side operand so as to preserve the never-empty
- guarantee.</listitem>
+ guarantee.<sbr/>
+ 如果任一有界类型可以无抛出缺省构造(就象
<code><classname>boost::has_nothrow_constructor</classname></code> 那样)，
+ 本库保证 <code>variant</code> 只使用单份存储且可以对
<code>variant</code> 中的每一个有界类型进行就地构造。
+ 不过请注意，如果赋值失败，某个不确定的可无抛出缺省构造的有界类
型将被缺省构造到左操作数中，以提供非空保证。</listitem>
</itemizedlist>
@@ -276,7 +366,11 @@
by default return <code>false</code> for all <code>class</code> and
<code>struct</code> types. It is necessary therefore to provide
specializations of these templates as appropriate for user-defined
- types, as demonstrated in the following:
+ types, as demonstrated in the following:<sbr/>
+ <emphasis role="bold">警告</emphasis>：在多数平台
上，<libraryname>Type Traits</libraryname>
+ 模板 <code>has_nothrow_copy</code> 和
<code>has_nothrow_constructor</code> 缺省对于所有
+ <code>class</code> 和 <code>struct</code> 类型返回
<code>false</code><code>false</code>.
+ 因此需要为用户自定义类型提供这些模板的适当的特化版本，示范如下：
<programlisting>// ...in your code (at file scope)...
@@ -300,17 +394,24 @@
bounded type instead of other nothrow default-constructible bounded
types. (If this is deemed to be a useful feature, it will become
part
of the specification for <code>variant</code>; otherwise, it may be
- obsoleted. Please provide feedback to the Boost mailing
list.)</para>
+ obsoleted. Please provide feedback to the Boost mailing
list.)<sbr/>
+ <emphasis role="bold">实现说明</emphasis>：为了使得在遇到异常后
<code>variant</code>
+ 的行为更可预测，当前的实现在 boost::blank 被指定为有界类型时会优先
缺省构造
+ <code><classname>boost::blank</classname></code> 而不是其它可以无抛
出缺省构造的有界类型。
+ (如果这一点被认为是有用的，则它将成为 <code>variant</code> 规格的一
部分；否则它将被废弃。
+ 请向 Boost 邮件列表提供反馈。)</para>
</section>
<section id="variant.design.never-empty.roadmap">
- <title>Future Direction: Policy-based Implementation</title>
+ <title>Future Direction: Policy-based Implementation 未来的方向：基于
策略的实现</title>
<para>As the previous sections have demonstrated, much effort has
been
expended in an attempt to provide a balance between performance,
data
size, and heap usage. Further, significant optimizations may be
enabled in <code>variant</code> on the basis of certain traits of
its
- bounded types.</para>
+ bounded types.<sbr/>
+ 正如前一节中的示例，我们进行了更多的努力，以在性能、数据大小和堆的
使用之间提供一个平衡。
+ 而且，基于 <code>variant</code> 的有界类型的特定 traits，还可以进行
特殊的优化。</para>
<para>However, there will be some users for whom the chosen
compromise
is unsatisfactory (e.g.: heap allocation must be avoided at all
costs;
@@ -319,7 +420,11 @@
policy-based implementation of <code>variant</code>. While this
will
not eliminate the problems described in the previous sections, it
will
allow the decisions regarding tradeoffs to be decided by the user
- rather than the library designers.</para>
+ rather than the library designers.<sbr/>
+ 不过，还是有些用户对于选定的折衷不满意(例如：堆的分配必须不惜代价地
避免；
+ 如果要用堆分配，就必须使用定制的分配器；等等)。因此，本库的未来版本
将支持
+ <code>variant</code> 的一个基于策略的实现。虽然它不能完全解决前面章
节中所说的问题，
+ 但是它允许折衷的决定由用户而不是库的设计者来作出。</para>
</section>
</section>
=======================================
--- /trunk/libs/variant/doc/introduction.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/variant/doc/introduction.xml Mon Jul 19 23:54:43 2010
@@ -2,12 +2,12 @@
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
<section id="variant.intro">
- <title>Introduction</title>
+ <title>Introduction 简介</title>
<using-namespace name="boost"/>
<section id="variant.abstract">
- <title>Abstract</title>
+ <title>Abstract 概要</title>
<para>The <code>variant</code> class template is a safe, generic,
stack-based
discriminated union container, offering a simple solution for manipulating
an
@@ -15,38 +15,51 @@
standard containers such as <code>std::vector</code> may be thought of as
"<emphasis role="bold">multi-value, single type</emphasis>,"
<code>variant</code> is "<emphasis role="bold">multi-type,
-single value</emphasis>."</para>
+single value</emphasis>."<sbr/>
+<code>variant</code> 类模板是一个安全的、泛型的、基于栈的、可识别的联合容
器，
+为以统一风格操作异类类型集合的对象提供了一个简单的方法。
+象 <code>std::vector</code> 这样的标准容器可以被视为 "<emphasis
role="bold">多值，单一类型</emphasis>"的，
+而 <code>variant</code> 则是 "<emphasis role="bold">多类型，单值
</emphasis>"的。</para>
<para>Notable features of
<code><classname>boost::variant</classname></code>
-include:</para>
+include:<sbr/>
+<code><classname>boost::variant</classname></code> 的主要特性包括：</para>
<itemizedlist>
<listitem>Full value semantics, including adherence to standard
- overload resolution rules for conversion operations.</listitem>
+ overload resolution rules for conversion operations.<sbr/>
+ 完全的值语义，包括遵守转换操作符的标准重载决议规则。</listitem>
<listitem>Compile-time type-safe value visitation via
-
<code><functionname>boost::apply_visitor</functionname></code>.</listitem>
+ <code><functionname>boost::apply_visitor</functionname></code>.<sbr/>
+ 经由 <code><functionname>boost::apply_visitor</functionname></code> 的
编译期类型安全的值访问。</listitem>
<listitem>Run-time checked explicit value retrieval via
- <code><functionname>boost::get</functionname></code>.</listitem>
+ <code><functionname>boost::get</functionname></code>.<sbr/>
+ 经由 <code><functionname>boost::get</functionname></code> 的运行期带检
查的显式的值取出。</listitem>
<listitem>Support for recursive variant types via both
<code><classname>boost::make_recursive_variant</classname></code> and
-
<code><classname>boost::recursive_wrapper</classname></code>.</listitem>
+ <code><classname>boost::recursive_wrapper</classname></code>.<sbr/>
+ 通过 <code><classname>boost::make_recursive_variant</classname></code>
和
+ <code><classname>boost::recursive_wrapper</classname></code> 支持递归
的 variant 类型。</listitem>
<listitem>Efficient implementation -- stack-based when possible (see
- <xref linkend="variant.design.never-empty"/> for more
details).</listitem>
+ <xref linkend="variant.design.never-empty"/> for more details).<sbr/>
+ 高效的实现 -- 尽可能基于栈(详情请见 <xref
linkend="variant.design.never-empty"/>)。</listitem>
</itemizedlist>
</section>
<section id="variant.motivation">
- <title>Motivation</title>
+ <title>Motivation 动机</title>
<section id="variant.motivation.problem">
- <title>Problem</title>
+ <title>Problem 问题</title>
<para>Many times, during the development of a C++ program, the
programmer finds himself in need of manipulating several distinct
types in a uniform manner. Indeed, C++ features direct language
support for such types through its <code>union</code>
-keyword:</para>
+keyword:<sbr/>
+很多时候，在开发一个C++程序时，程序员会发现需要以统一的风格来操作多个不同的
类型。
+确实，C++以 <code>union</code> 关键字直接提供了这种支持：</para>
<programlisting>union { int i; double d; } u;
u.d = 3.14;
@@ -57,7 +70,9 @@
the language primarily as a means for preserving compatibility with
C, which supports only POD (Plain Old Data) types, and so does not
accept types exhibiting non-trivial construction or
-destruction:</para>
+destruction:<sbr/>
+但是，C++的 <code>union</code> 结构在面向对象的环境下几乎是不可用的。
+该结构得以保存下来，主要是为了与C兼容，它只能支持 POD 类型，不可以使用带有
非平凡构造或析构的类型：</para>
<programlisting>union {
int i;
@@ -71,35 +86,48 @@
or, more dangerously, a <code>void*</code>). Objects of
concrete type may be then retrieved by way of a polymorphic downcast
construct (e.g., <code>dynamic_cast</code>,
-<code><functionname>boost::any_cast</functionname></code>, etc.).</para>
+<code><functionname>boost::any_cast</functionname></code>, etc.).<sbr/>
+显然，我们需要另一种方法。典型的方法是对对象进行动态分配，随之而来就是要通
过一个公共基类
+(通常是一个虚基类[<link linkend="variant.refs.hen01">Hen01</link>] 或者是更
危险的 <code>void*</code>)来进行操作。
+然后通过一个多态的向下转型结构(如 <code>dynamic_cast</code>,
+<code><functionname>boost::any_cast</functionname></code>, 等等)来取回具体
类型的对象。</para>
<para>However, solutions of this sort are highly error-prone, due
-to the following:</para>
+to the following:<sbr/>
+但是，这类方法是非常容易出错的，因为以下原因：</para>
<itemizedlist>
<listitem><emphasis>Downcast errors cannot be detected at
compile-time.</emphasis> Thus, incorrect usage of downcast
- constructs will lead to bugs detectable only at run-time.</listitem>
+ constructs will lead to bugs detectable only at run-time.<sbr/>
+ <emphasis>向下转型的错误不能在编译期被检测到。</emphasis>
+ 因此，对向下转型结构的错误使用将导致只能在运行期被检查出来的 bug。
</listitem>
<listitem><emphasis>Addition of new concrete types may be
ignored.</emphasis> If a new concrete type is added to the
hierarchy, existing downcast code will continue to work as-is,
wholly ignoring the new type. Consequently, the programmer must
manually locate and modify code at numerous locations, which often
- results in run-time errors that are difficult to find.</listitem>
+ results in run-time errors that are difficult to find.<sbr/>
+ <emphasis>新加入的具体类可能被忽略。</emphasis>
+ 如果一个新的具体类被加入到类层次中，已有的向下转型代码可以继续工作，完
全忽略掉了新的类型。
+ 因此，程序员必须手工定位和修改多处代码，这通常会导致运行期错误且难以觉
察。</listitem>
</itemizedlist>
<para>Furthermore, even when properly implemented, these solutions tend
to incur a relatively significant abstraction penalty due to the use of
-the heap, virtual function calls, and polymorphic downcasts.</para>
+the heap, virtual function calls, and polymorphic downcasts.<sbr/>
+此外，即使被正确地实现，这类方法还是会由于使用了堆、虚拟函数调用和多态向下
转型而导致相对严重的开销。</para>
</section>
<section id="variant.motivation.solution">
- <title>Solution: A Motivating Example</title>
+ <title>Solution: A Motivating Example 解决方法：一个例子</title>
<para>The <code><classname>boost::variant</classname></code> class template
addresses these issues in a safe, straightforward, and efficient manner.
The
-following example demonstrates how the class can be used:</para>
+following example demonstrates how the class can be used:<sbr/>
+<code><classname>boost::variant</classname></code> 类模板以安全、简单和高效
的方法解决了这个问题。
+以下例子示范了如何使用这个类：</para>
<programlisting>#include "boost/variant.hpp"
#include <iostream>
=======================================
--- /trunk/libs/variant/doc/misc.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/variant/doc/misc.xml Mon Jul 19 23:54:43 2010
@@ -2,7 +2,7 @@
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
<section id="variant.misc">
- <title>Miscellaneous Notes</title>
+ <title>Miscellaneous Notes 杂项说明</title>
<using-namespace name="boost"/>
@@ -13,38 +13,51 @@
of the same features of the <libraryname>Any</libraryname> library.
However, since neither library wholly encapsulates the features of the
other, one library cannot be generally recommended for use over the
- other.</para>
+ other.<sbr/>
+ 作为一个可识别的联合空器，Variant 库共享了
<libraryname>Any</libraryname> 库的许多相同特性。
+ 不过，由于没有一个库可以完全包含另一个库的所有特性，所以没有哪一个库被
推荐优于另一个库。</para>
<para>That said, Boost.Variant has several advantages over Boost.Any,
- such as:
+ such as:<sbr/>
+ 可以说，Boost.Variant 有几个优于 Boost.Any 之处，如：
<itemizedlist>
<listitem>Boost.Variant guarantees the type of its content is one of
a
- finite, user-specified set of types.</listitem>
+ finite, user-specified set of types.<sbr/>
+ Boost.Variant 保证其内容的类型是一个有限的、用户指定的类型。
</listitem>
<listitem>Boost.Variant provides <emphasis>compile-time</emphasis>
checked visitation of its content. (By contrast, the current
version
of Boost.Any provides no visitation mechanism at all; but even if
it
- did, it would need to be checked at run-time.)</listitem>
+ did, it would need to be checked at run-time.)<sbr/>
+ Boost.Variant 提供了对其内容的<emphasis>编译期</emphasis>检查的访问
方式。
+ (作为对比，当前版本的 Boost.Any 根本没有提供访问机制；即使它提供
了，也只能在运行期进行检查)
+</listitem>
<listitem>Boost.Variant enables generic visitation of its content.
(Even if Boost.Any did provide a visitation mechanism, it would
enable
- visitation only of explicitly-specified types.)</listitem>
+ visitation only of explicitly-specified types.)<sbr/>
+ Boost.Variant 可以实现对其内容的泛型访问。(即使 Boost.Any 也提供访
问机制，也只能根据显式指定的类型进行访问)</listitem>
<listitem>Boost.Variant offers an efficient, stack-based storage
scheme
- (avoiding the overhead of dynamic allocation).</listitem>
+ (avoiding the overhead of dynamic allocation).<sbr/>
+ Boost.Variant 提供了高效的、基于栈的存储方式(避免了动态分配的开销
)。 </listitem>
</itemizedlist>
</para>
<para>Of course, Boost.Any has several advantages over Boost.Variant,
- such as:
+ such as:<sbr/>
+ 当然，Boost.Any 也有优于 Boost.Variant 之处，如：
<itemizedlist>
<listitem>Boost.Any, as its name implies, allows virtually any type
for
- its content, providing great flexibility.</listitem>
+ its content, providing great flexibility.<sbr/>
+ Boost.Any, 顾名思义，允许其内容为任意类型，提供了强大的灵活性。
</listitem>
<listitem>Boost.Any provides the no-throw guarantee of exception
safety
- for its swap operation.</listitem>
+ for its swap operation.<sbr/>
+ Boost.Any 为其交换操作提供了无抛出的异常安全保证。</listitem>
<listitem>Boost.Any makes little use of template metaprogramming
techniques (avoiding potentially hard-to-read error messages and
- significant compile-time processor and memory demands).</listitem>
+ significant compile-time processor and memory demands).<sbr/>
+ Boost.Any 只使用了少量模板元编程的技术(避免了难以阅读的错误信息和编
译时对处理器和内存的大量需求)。</listitem>
</itemizedlist>
</para>
@@ -52,27 +65,32 @@
</section>
<section>
- <title>Portability</title>
+ <title>Portability 可移植性</title>
<para>The library aims for 100% ANSI/ISO C++ conformance. However, this
is
strictly impossible due to the inherently non-portable nature of the
<libraryname>Type Traits</libraryname> library's
<code><classname>type_with_alignment</classname></code> facility. In
practice though, no compilers or platforms have been discovered where
this
- reliance on undefined behavior has been an issue.</para>
+ reliance on undefined behavior has been an issue.<sbr/>
+ 本库的目标是 100% ANSI/ISO C++ 的兼容性。但是，这是不可能的，因为
<libraryname>Type Traits</libraryname>
+ 库的 <code><classname>type_with_alignment</classname></code> 工具固有的
不可移植性。
+ 尽管在实际中，还没有发现某个编译器或平台有这方面的问题。</para>
<para>Additionally, significant effort has been expended to ensure proper
functioning despite various compiler bugs and other conformance
problems.
To date the library testsuite has
been compiled and tested successfully on at least the following
compilers
- for basic and advanced functionality:
+ for basic and advanced functionality:<sbr/>
+ 此外，我们还做出了重大努力，在各种编译器缺陷和标准符合度问题下保证正确
的功能。
+ 到目前为止，本库的测试组件至少在以下编译器上编译和测试通过，测试是针对
各种基本和高级功能的：
<informaltable>
<tgroup cols="5">
<thead>
<row>
<entry></entry>
- <entry>Basic</entry>
+ <entry>Basic 基本</entry>
<entry>
<code>variant<T&></code>
</entry>
@@ -155,51 +173,60 @@
<ulink url="http://boost.sourceforge.net/regression-logs";>Test
Summary</ulink>
page. Please note, however, that this page reports on day-to-day
changes
to inter-release code found in the Boost CVS and thus likely does not
- match the state of code found in Boost releases.</para>
+ match the state of code found in Boost releases.<sbr/>
+ 最后，在 CVS 中的测试组件当前状态可以在 <ulink
url="http://boost.sourceforge.net/regression-logs";>Test Summary</ulink> 页找
到。
+ 不过请注意，该网页按天报告在 Boost CVS 中的内部版本代码的变化，所以与
Boost 发布版的代码状态会不匹配。</para>
</section>
<section id="variant.troubleshooting">
- <title>Troubleshooting</title>
+ <title>Troubleshooting 疑难解答</title>
<para>Due to the heavy use of templates in the implementation of
<code>variant</code>, it is not uncommon when compiling to encounter
problems related to template instantiaton depth, compiler memory, etc.
This
section attempts to provide advice to common problems experienced on
several
- popular compilers.</para>
+ popular compilers.<sbr/>
+ 由于 <code>variant</code> 的实现大量使用了模板，所以常常会出现与模板实例
化深度、编译器内存等有关的问题。
+ 本节试图对在常用编译器上会遇到的常见问题提出一些建议。</para>
<para>(This section is still in progress, with additional advice/feedback
welcome. Please post to the Boost-Users list with any useful experiences
you
- may have.)</para>
+ may have.)<sbr/>
+ (本节还在完成中，欢迎提出建议和反馈。请将任何有用的经验发送到
Boost-Users 列表)。</para>
<section id="variant.troubleshooting.template-depth">
- <title>"Template instantiation depth exceeds maximum"</title>
+ <title>"Template instantiation depth exceeds maximum"
"模板实例化深度超出最大值"</title>
<section id="variant.troubleshooting.template-depth.gcc">
<title>GNU GCC</title>
<para>The compiler option
<code>-ftemplate-depth-<emphasis>NN</emphasis></code> can increase
the
maximum allowed instantiation depth. (Try
- <code>-ftemplate-depth-50</code>.)</para>
+ <code>-ftemplate-depth-50</code>.)<sbr/>
+ 编译器选项 <code>-ftemplate-depth-<emphasis>NN</emphasis></code> 可
以增加允许的实例化深度最大值。
+ (试一下 <code>-ftemplate-depth-50</code>.)</para>
</section>
</section>
<section id="variant.troubleshooting.compiler-memory">
- <title>"Internal heap limit reached"</title>
+ <title>"Internal heap limit reached" "达到内部堆的上限
"</title>
<section id="variant.troubleshooting.compiler-memory.msvc">
<title>Microsoft Visual C++</title>
<para>The compiler option <code>/Zm<emphasis>NNN</emphasis></code>
can
increase the memory allocation limit. The <code>NNN</code> is a
scaling percentage (i.e., <code>100</code> denotes the default
limit).
- (Try <code>/Zm200</code>.)</para>
+ (Try <code>/Zm200</code>.)<sbr/>
+ 编译器选项 <code>/Zm<emphasis>NNN</emphasis></code> 可以增加内存分
配的上限。
+ <code>NNN</code> 为缩放的百分比(即 <code>100</code> 表示缺省上限)。
(试一下 <code>/Zm200</code>.)</para>
</section>
</section>
</section>
<section id="variant.ack">
- <title>Acknowledgments</title>
+ <title>Acknowledgments 鸣谢</title>
<para>Eric Friedman and Itay Maman designed the initial submission; Eric
was
the primary implementer.</para>
=======================================
--- /trunk/libs/variant/doc/reference/apply_visitor.xml Mon Dec 28 23:05:14
2009
+++ /trunk/libs/variant/doc/reference/apply_visitor.xml Mon Jul 19 23:54:43
2010
@@ -4,16 +4,21 @@
<header name="boost/variant/apply_visitor.hpp">
<namespace name="boost">
<class name="apply_visitor_delayed_t">
- <purpose>Adapts a visitor for use as a function object.</purpose>
+ <purpose>Adapts a visitor for use as a function object.<sbr/>
+ 将一个访问者适配为一个函数对象。</purpose>
<description>
<simpara>Adapts the function given at construction for use as a
function object. This is useful, for example, when one needs to
operate on each element of a sequence of variant objects using a
standard library algorithm such as
- <code>std::for_each</code>.</simpara>
+ <code>std::for_each</code>.<sbr/>
+ 将在构造时给定的函数适配为函数对象。这很有用，例如，当你需要对一
个 variant
+ 对象序列中的各个元素使用象 <code>std::for_each</code> 这样的标准
算法进行操作时。</simpara>
<simpara>See the "visitor-only" form of
<code><functionname>apply_visitor</functionname></code> for a
simple
- way to create <code>apply_visitor_delayed_t</code>
objects.</simpara>
+ way to create <code>apply_visitor_delayed_t</code> objects.<sbr/>
+ 关于创建 <code>apply_visitor_delayed_t</code> 对象的简单方法，请
见
+ <code><functionname>apply_visitor</functionname></code> 的
"visitor-only" 形式。</simpara>
</description>
<template>
@@ -31,7 +36,8 @@
<effects>
<simpara>Constructs the function object with the given
- visitor.</simpara>
+ visitor.<sbr/>
+ 以给定的访问者构造函数对象。</simpara>
</effects>
</constructor>
@@ -67,7 +73,8 @@
<description>
<simpara>Invokes
<code><functionname>apply_visitor</functionname></code> on the
- stored visitor using the given operands.</simpara>
+ stored visitor using the given operands.<sbr/>
+ 以给定的操作数对所保存的访问者调用
<code><functionname>apply_visitor</functionname></code>.</simpara>
</description>
</overloaded-method>
</method-group>
@@ -161,23 +168,29 @@
<purpose>
<simpara>Allows compile-time checked type-safe application of the
given visitor to the content of the given variant, ensuring that
all
- types are handled by the visitor.</simpara>
+ types are handled by the visitor.<sbr/>
+ 将给定的访问者应用到给定的 variant 的内容上，该过程在编译期进行类型
安全检查，以确认所有类型均被访问者所处理。</simpara>
</purpose>
<description>
<simpara>The behavior of <code>apply_visitor</code> is dependent on
the number of arguments on which it operates (i.e., other than the
- visitor). The function behaves as follows:
+ visitor). The function behaves as follows:<sbr/>
+ <code>apply_visitor</code> 的行为取决于它所操作的参数的数量(即除访
问者以外的其它参数)。该函数的行为如下：
<itemizedlist>
<listitem>Overloads accepting one operand invoke the unary
function
call operator of the given visitor on the content of the
given
- <code><classname>variant</classname></code>
operand.</listitem>
+ <code><classname>variant</classname></code> operand.<sbr/>
+ 接受一个操作数的重载将以给定的
<code><classname>variant</classname></code>
+ 操作数的内容调用给定的访问者的单参函数调用操作符。</listitem>
<listitem>Overloads accepting two operands invoke the binary
function call operator of the given visitor on the content of
the given <code><classname>variant</classname></code>
- operands.</listitem>
+ operands.<sbr/>
+ 接受两个操作数的重载将以给定的
<code><classname>variant</classname></code>
+ 操作数的内容调用给定的访问者的二元函数调用操作符。</listitem>
<listitem>The overload accepting only a visitor returns a
<classname alt="boost::apply_visitor_delayed_t">generic
function object</classname>
@@ -187,7 +200,11 @@
specified above. (This behavior is particularly useful, for
example, when one needs to operate on each element of a
sequence
of variant objects using a standard library
- algorithm.)</listitem>
+ algorithm.)<sbr/>
+ 只接受一个访问者的重载将返回一个 <classname
alt="boost::apply_visitor_delayed_t">泛型函数对象</classname>，
+ 该对象接受一个或两个参数并以这些参数和 <code>visitor</code>
调用
+ <code><functionname>apply_visitor</functionname></code>, 其行
为和前面两项相似。
+ (这种行为特别有用，例如当你需要对一个 variant 对象序列中的各
个元素使用一个标准库算法时)。 </listitem>
</itemizedlist>
</simpara>
@@ -197,14 +214,18 @@
<simpara>The overloads acccepting operands return the result of
applying the given visitor to the content of the given operands.
The overload accepting only a visitor return a function object,
thus
- delaying application of the visitor to any operands.</simpara>
+ delaying application of the visitor to any operands.<sbr/>
+ 接受操作数的重载将返回将给定访问者应用于给定操作数所得的结果。
+ 只接受一个访问者的重载则返回一个函数对象，以延后将访问者应用于任意
操作数。</simpara>
</returns>
<requires>
<simpara>The given visitor must fulfill the
<link
linkend="variant.concepts.static-visitor"><emphasis>StaticVisitor</emphasis></link>
concept requirements with respect to each of the bounded types of
the
- given <code>variant</code>.</simpara>
+ given <code>variant</code>.<sbr/>
+ 给定的访问者必须符合 <link
linkend="variant.concepts.static-visitor"><emphasis>StaticVisitor</emphasis></link>
+ 概念的要求，并处理给定 <code>variant</code> 的各个有界类型。
</simpara>
</requires>
<throws>
@@ -212,7 +233,9 @@
visitor throws when applied. The overload accepting only a visitor
will not throw. (Note, however, that the returned
<classname alt="boost::apply_visitor_delayed_t">function
object</classname>
- may throw when invoked.)</simpara>
+ may throw when invoked.)<sbr/>
+ 接受操作数的重载只会在给定的访问者抛出异常时抛出。只接受一个访问者
的重载则不会抛出。
+ (但是请注意，返回的 <classname
alt="boost::apply_visitor_delayed_t">函数对象</classname> 有可能在运行时抛出
)</simpara>
</throws>
</overloaded-function>
</namespace>
=======================================
--- /trunk/libs/variant/doc/reference/bad_visit.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/variant/doc/reference/bad_visit.xml Mon Jul 19 23:54:43 2010
@@ -11,7 +11,8 @@
<purpose>
<simpara>The exception thrown in the event of a visitor
- unable to handle the visited value.</simpara>
+ unable to handle the visited value.<sbr/>
+ 当一个访问者不能处理被访问值时抛出的异常。</simpara>
</purpose>
<method name="what" specifiers="virtual" cv="const">
=======================================
--- /trunk/libs/variant/doc/reference/get.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/variant/doc/reference/get.xml Mon Jul 19 23:54:43 2010
@@ -12,7 +12,8 @@
<purpose>
<simpara>The exception thrown in the event of a failed application
of
<code><functionname>boost::get</functionname></code> on the
given
- operand value.</simpara>
+ operand value.<sbr/>
+ 将 <code><functionname>boost::get</functionname></code> 应用于给定
的操作数值发生失败时所抛出的异常。</simpara>
</purpose>
<method name="what" specifiers="virtual" cv="const">
@@ -87,7 +88,8 @@
<purpose>
<simpara>Retrieves a value of a specified type from a given
- <code><classname>variant</classname></code>.</simpara>
+ <code><classname>variant</classname></code>.<sbr/>
+ 从给定的 <code><classname>variant</classname></code> 中取出指定类
型的值。</simpara>
</purpose>
<description>
@@ -95,13 +97,17 @@
type-safe retrieval of the content of the given
<code><classname>variant</classname></code>. The function
succeeds
only if the content is of the specified type <code>U</code>, with
- failure indicated as described below.</simpara>
- <simpara><emphasis role="bold">Warning</emphasis>: After either
+ failure indicated as described below.<sbr/>
+ <code>get</code> 函数取出给定
<code><classname>variant</classname></code> 中的内容，该过程是运行期检查的、
类型安全的。
+ 该函数仅在内容的类型为 <code>U</code> 时成功返回，关于失败的情况
描述如下。</simpara>
+ <simpara><emphasis role="bold">Warning 警告</emphasis>: After
either
<code>operand</code> or its content is destroyed (e.g., when the
given <code><classname>variant</classname></code> is assigned a
value of different type), the returned reference is invalidated.
Thus, significant care and caution must be extended when handling
- the returned reference.</simpara>
+ the returned reference.<sbr/>
+ 在 <code>operand</code> 或其内容销毁后(例如，给定的
<code><classname>variant</classname></code>
+ 被赋予另一个不同类型的值)，返回的引用将变为无效。因此，在使用返回
的引用时必须特别小心谨慎。</simpara>
</description>
<notes>
@@ -112,7 +118,12 @@
<code>const</code>-qualified. The converse, however, is not
required:
that is, the specified type <code>U</code> may be
<code>const</code>-qualified even when <code>operand</code> and its
- content are not.</simpara>
+ content are not.<sbr/>
+ 作为类型安全保证的一部分，<code>get</code> 保持
<code>const</code>-正确性。
+ 因此，只要 <code>operand</code> 或其内容是 <code>const</code>-限定
的，则类型
+ <code>U</code> 必须也是 <code>const</code>-限定的。不过反之则不
然：即使
+ <code>operand</code> 及其内容不是 <code>const</code>-限定的，类型
<code>U</code>
+ 也可以是 <code>const</code>-限定的。</simpara>
</notes>
<returns>
@@ -121,7 +132,10 @@
otherwise, a null pointer is returned. If passed a reference,
<code>get</code> returns a reference to the value content if it is
of
the specified type <code>U</code>; otherwise, an exception is
thrown
- (see below).</simpara>
+ (see below).<sbr/>
+ 如果传入的是一个指针，则 <code>get</code> 在其内容的类型为
<code>U</code> 时返回该内容值的指针；
+ 否则返回一个空指针。如果传入的是一个引用，则 <code>get</code> 在其
内容的类型为 <code>U</code>
+ 时返回该内容值的引用；否则抛出一个异常(见后)。</simpara>
</returns>
<throws>
@@ -130,7 +144,10 @@
throw; the overloads taking a
<code><classname>variant</classname></code> reference throw
<code><classname>bad_get</classname></code> if the content is not
of
- the specified type <code>U</code>.</simpara>
+ the specified type <code>U</code>.<sbr/>
+ 接受一个 <code><classname>variant</classname></code> 指针的重载不会
抛出；接受一个
+ <code><classname>variant</classname></code> 引用的重载在所含内容不
是类型 <code>U</code>
+ 时抛出 <code><classname>bad_get</classname></code>.</simpara>
</throws>
<rationale>
@@ -138,7 +155,9 @@
<code><functionname>apply_visitor</functionname></code>
is generally preferred due to its greater safety, <code>get</code>
may
may be more convenient in some cases due to its straightforward
- usage.</simpara>
+ usage.<sbr/>
+ 虽然使用 <code><functionname>apply_visitor</functionname></code> 的
访问机制由于更好的安全性而更为常用，
+ 但在某些情况下使用 <code>get</code> 则更为方便。</simpara>
</rationale>
</overloaded-function>
=======================================
--- /trunk/libs/variant/doc/reference/recursive_variant.xml Mon Dec 28
23:05:14 2009
+++ /trunk/libs/variant/doc/reference/recursive_variant.xml Mon Jul 19
23:54:43 2010
@@ -9,7 +9,8 @@
</typedef>
<class name="make_recursive_variant">
- <purpose>Simplifies declaration of recursive <code>variant</code>
types.</purpose>
+ <purpose>Simplifies declaration of recursive <code>variant</code>
types.<sbr/>
+ 简化递归 <code>variant</code> 类型的声明。</purpose>
<template>
<template-type-parameter name="T1"/>
@@ -28,42 +29,60 @@
<code>U<emphasis>i</emphasis></code> is the result of the
corresponding type <code>T<emphasis>i</emphasis></code>
undergone a
transformation function. The following pseudo-code specifies the
- behavior of this transformation (call it
<code>substitute</code>):
+ behavior of this transformation (call it
<code>substitute</code>):<sbr/>
+ <code>type</code> 的行为在各方面均等同于 <code>variant< U1,
U2, ..., UN ></code>, 其中每个类型
+ <code>U<emphasis>i</emphasis></code> 为相应的类型
<code>T<emphasis>i</emphasis></code> 经过转化函数后所得的结果。
+ 以下伪代码给出了这一转化(我们称之为 <code>substitute</code>)的行
为：
<itemizedlist>
<listitem>If <code>T<emphasis>i</emphasis></code> is
<code>boost::recursive_variant_</code> then:
- <code>variant< U1, U2, ..., UN ></code>;</listitem>
+ <code>variant< U1, U2, ..., UN ></code>;<sbr/>
+ 如果 <code>T<emphasis>i</emphasis></code> 是
<code>boost::recursive_variant_</code> 则返回：
+ <code>variant< U1, U2, ..., UN ></code>; </listitem>
<listitem>Else if <code>T<emphasis>i</emphasis></code> is of
the
form <code>X *</code> then:
- <code>substitute(X) *</code>;</listitem>
+ <code>substitute(X) *</code>;<sbr/>
+ 否则，如果 <code>T<emphasis>i</emphasis></code> 形如 <code>X
*</code> 则返回：<code>substitute(X) *</code>; </listitem>
<listitem>Else if <code>T<emphasis>i</emphasis></code> is of
the
form <code>X &</code> then:
- <code>substitute(X) &</code>;</listitem>
+ <code>substitute(X) &</code>;<sbr/>
+ 否则，如果 <code>T<emphasis>i</emphasis></code> 形如 <code>X
&</code> 则返回：
+ <code>substitute(X) &</code>; </listitem>
<listitem>Else if <code>T<emphasis>i</emphasis></code> is of
the
form <code>R (*)( X1, X2, ..., XN )</code> then:
- <code>substitute(R) (*)( substitute(X1),
substitute(X2), ..., substitute(XN) )</code>;</listitem>
+ <code>substitute(R) (*)( substitute(X1),
substitute(X2), ..., substitute(XN) )</code>;<sbr/>
+ 否则，如果 <code>T<emphasis>i</emphasis></code> 形如 <code>R
(*)( X1, X2, ..., XN )</code> 则返回：
+ <code>substitute(R) (*)( substitute(X1),
substitute(X2), ..., substitute(XN) )</code>; </listitem>
<listitem>Else if <code>T<emphasis>i</emphasis></code> is of
the
form <code>F < X1, X2, ..., XN ></code> then:
- <code>F< substitute(X1), substitute(X2), ...,
substitute(XN) ></code>;</listitem>
- <listitem>Else:
<code>T<emphasis>i</emphasis></code>.</listitem>
+ <code>F< substitute(X1), substitute(X2), ...,
substitute(XN) ></code>;<sbr/>
+ 否则，如果 <code>T<emphasis>i</emphasis></code> 形如 <code>F
< X1, X2, ..., XN ></code> 则返回：
+ <code>F< substitute(X1), substitute(X2), ...,
substitute(XN) ></code>; </listitem>
+ <listitem>Else: <code>T<emphasis>i</emphasis></code>.<sbr/>
+ 否则返回：<code>T<emphasis>i</emphasis></code>.</listitem>
</itemizedlist>
</para>
<para>Note that cv-qualifiers are preserved and that the actual
process is generally a bit more complicated. However, the above
does
convey the essential idea as well as describe the extent of the
- substititions.</para>
+ substititions.<sbr/>
+ 注意，cv-限定符被保留，而且实际过程还要更复杂一点。不过，上述代码
已经表达了这一替换操作的基本意思。</para>
<para>Use of <code>make_recursive_variant</code> is demonstrated in
- <xref
linkend="variant.tutorial.recursive.recursive-variant"/>.</para>
+ <xref
linkend="variant.tutorial.recursive.recursive-variant"/>.<sbr/>
+ 有关 <code>make_recursive_variant</code> 的用例，请见 <xref
linkend="variant.tutorial.recursive.recursive-variant"/>。</para>
<para><emphasis role="bold">Portability</emphasis>: Due to standard
conformance issues in several compilers,
<code>make_recursive_variant</code> is not universally
supported. On
these compilers the library indicates its lack of support via the
definition of the preprocessor symbol
-
<code><macroname>BOOST_VARIANT_NO_FULL_RECURSIVE_VARIANT_SUPPORT</macroname></code>.</para>
+
<code><macroname>BOOST_VARIANT_NO_FULL_RECURSIVE_VARIANT_SUPPORT</macroname></code>.<sbr/>
+ <emphasis role="bold">可移植性</emphasis>：由于某些编译器的标准符
合问题，
+ <code>make_recursive_variant</code> 并不被完全支持。在这些编译器
上，本库通过定义一个预处理器符号
+
<code><macroname>BOOST_VARIANT_NO_FULL_RECURSIVE_VARIANT_SUPPORT</macroname></code>
来表示支持上的不足。</para>
</description>
<typedef name="type">
@@ -75,7 +94,8 @@
<class name="make_recursive_variant_over">
<purpose>
<simpara>Exposes a recursive <code>variant</code> whose bounded
types
- are the elements of the given type sequence.</simpara>
+ are the elements of the given type sequence.<sbr/>
+ 提供一个递归 <code>variant</code>，其有界类型为给定的类型序列中的
元素。</simpara>
</purpose>
<template>
@@ -91,18 +111,25 @@
<code><classname>make_recursive_variant</classname><
Sequence[0], Sequence[1], ... >::type</code>
(where <code>Sequence[<emphasis>i</emphasis>]</code> denotes the
<emphasis>i</emphasis>-th element of <code>Sequence</code>),
except
- that no upper limit is imposed on the number of types.</simpara>
+ that no upper limit is imposed on the number of types.<sbr/>
+ <code>type</code> 的行为在各方面均等同于
+ <code><classname>make_recursive_variant</classname><
Sequence[0], Sequence[1], ... >::type</code>
+ (其中 <code>Sequence[<emphasis>i</emphasis>]</code> 表示
<code>Sequence</code> 的第<emphasis>i</emphasis>个元素)，
+ 除了一点，即类型的数量没有上限。</simpara>
<simpara><emphasis role="bold">Notes</emphasis>:</simpara>
<itemizedlist>
<listitem><code>Sequence</code> must meet the requirements of
<libraryname>MPL</libraryname>'s <emphasis>Sequence</emphasis>
- concept.</listitem>
+ concept.<sbr/>
+ <code>Sequence</code> 必须符合 <libraryname>MPL</libraryname>
的 <emphasis>Sequence</emphasis> 概念的要求。</listitem>
<listitem>Due to standard conformance problems in several
compilers,
<code>make_recursive_variant_over</code> may not be supported
on
your compiler. See
<code><macroname>BOOST_VARIANT_NO_TYPE_SEQUENCE_SUPPORT</macroname></code>
- for more information.</listitem>
+ for more information.<sbr/>
+ 由于某些编译器的标准符合问
题，<code>make_recursive_variant_over</code> 可能在你的编译器上不被支持。
+ 更多信息请见
<code><macroname>BOOST_VARIANT_NO_TYPE_SEQUENCE_SUPPORT</macroname></code>.
</listitem>
</itemizedlist>
</description>
</class>
=======================================
--- /trunk/libs/variant/doc/reference/recursive_wrapper.xml Mon Dec 28
23:05:14 2009
+++ /trunk/libs/variant/doc/reference/recursive_wrapper.xml Mon Jul 19
23:54:43 2010
@@ -1,11 +1,12 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
<header name="boost/variant/recursive_wrapper.hpp">
<namespace name="boost">
<class name="recursive_wrapper">
- <purpose>Solves circular dependencies, enabling recursive
types.</purpose>
+ <purpose>Solves circular dependencies, enabling recursive
types.<sbr/>
+ 解决循环依赖问题，以支持递归类型。</purpose>
<template>
<template-type-parameter name="T"/>
@@ -17,19 +18,26 @@
allocated dynamically. This allows
<code>recursive_wrapper</code> to
hold types <code>T</code> whose member data leads to a circular
dependency (e.g., a data member of <code>T</code> has a data
member
- of type <code>T</code>).</simpara>
+ of type <code>T</code>).<sbr/>
+ <code>recursive_wrapper</code> 类模板具有类似于简单的值容器的接
口，但它的内容是动态分配的。
+ 这使得 <code>recursive_wrapper</code> 可以保存成员数据会引起循环
依赖的类型 <code>recursive_wrapper</code>
+ (即 <code>recursive_wrapper</code> 的某个数据成员具有类型为
<code>recursive_wrapper</code> 的数据成员)。</simpara>
<simpara>The application of <code>recursive_wrapper</code> is
easiest
understood in context. See
<xref linkend="variant.tutorial.recursive.recursive-wrapper"/>
for a
- demonstration of a common use of the class template.</simpara>
-
- <simpara><emphasis role="bold">Notes</emphasis>:</simpara>
+ demonstration of a common use of the class template.<sbr/>
+ <code>recursive_wrapper</code> 的应用在上下文中最容易理解。
+ 有关这个类模板的通常用法的示例，请见 <xref
linkend="variant.tutorial.recursive.recursive-wrapper"/>。</simpara>
+
+ <simpara><emphasis role="bold">Notes 备注</emphasis>:</simpara>
<itemizedlist>
<listitem>Any type specified as the template argument to
<code>recursive_wrapper</code> must be capable of construction
via
<code>operator new</code>. Thus, for instance, references are
not
- supported.</listitem>
+ supported.<sbr/>
+ 任何被指定为 <code>recursive_wrapper</code> 的模板参数的类型必
须可以通过 <code>operator new</code> 来构造。
+ 因此，象引用这样的类型不被支持。</listitem>
</itemizedlist>
</description>
@@ -40,29 +48,34 @@
<destructor>
<purpose>Destructor.</purpose>
<description>
- <simpara>Deletes the content of <code>*this</code>.</simpara>
+ <simpara>Deletes the content of <code>*this</code>.<sbr/>
+ 删除 <code>*this</code> 的内容。</simpara>
</description>
- <throws>Will not throw.</throws>
+ <throws>Will not throw.<sbr/>
+ 不会抛出。</throws>
</destructor>
<constructor>
<purpose>Default constructor.</purpose>
<description>
<simpara>Initializes <code>*this</code> by default construction
of
- <code>T</code>.</simpara>
+ <code>T</code>.<sbr/>
+ 以 <code>*this</code> 的缺省构造来初始化
<code>*this</code><code>*this</code>.</simpara>
</description>
<requires>
<simpara><code>T</code> must fulfill the requirements of the
<emphasis>DefaultConstructible</emphasis> [20.1.4]
- concept.</simpara>
+ concept.<sbr/>
+ <code>T</code> 必须符合
<emphasis>DefaultConstructible</emphasis> [20.1.4] 概念的要求。</simpara>
</requires>
<throws>
<simpara>May fail with any exceptions arising from the default
constructor of <code>T</code> or, in the event of
- insufficient memory, with
<code>std::bad_alloc</code>.</simpara>
+ insufficient memory, with <code>std::bad_alloc</code>.<sbr/>
+ 可能因 <code>T</code> 的缺省构造函数引起的异常而失败，或因内存
不足抛出 <code>std::bad_alloc</code>.</simpara>
</throws>
</constructor>
@@ -74,13 +87,15 @@
<purpose>Copy constructor.</purpose>
<description>
<simpara>Copies the content of <code>other</code> into
- <code>*this</code>.</simpara>
+ <code>*this</code>.<sbr/>
+ 将 <code>other</code> 的内容复制到
<code>*this</code>.</simpara>
</description>
<throws>
<simpara>May fail with any exceptions arising from the
copy constructor of <code>T</code> or, in the event of
- insufficient memory, with
<code>std::bad_alloc</code>.</simpara>
+ insufficient memory, with <code>std::bad_alloc</code>.<sbr/>
+ 可能因 <code>T</code> 的缺省构造函数引起的异常而失败，或因内存
不足抛出 <code>std::bad_alloc</code>.</simpara>
</throws>
</constructor>
@@ -92,13 +107,15 @@
<purpose>Value constructor.</purpose>
<description>
<simpara>Copies <code>operand</code> into
- <code>*this</code>.</simpara>
+ <code>*this</code>.<sbr/>
+ 将 <code>operand</code> 复制到 <code>*this</code>.</simpara>
</description>
<throws>
<simpara>May fail with any exceptions arising from the
copy constructor of <code>T</code> or, in the event of
- insufficient memory, with
<code>std::bad_alloc</code>.</simpara>
+ insufficient memory, with <code>std::bad_alloc</code>.<sbr/>
+ 可能因 <code>T</code> 的缺省构造函数引起的异常而失败，或因内存
不足抛出 <code>std::bad_alloc</code>.</simpara>
</throws>
</constructor>
@@ -113,10 +130,12 @@
<description>
<simpara>Exchanges contents of <code>*this</code> and
- <code>other</code>.</simpara>
+ <code>other</code>.<sbr/>
+ 交换 <code>*this</code> 和 <code>other</code> 的内容。
</simpara>
</description>
- <throws>Will not throw.</throws>
+ <throws>Will not throw.<sbr/>
+ 不会抛出。</throws>
</method>
<method name="operator=">
@@ -129,18 +148,21 @@
<purpose>Copy assignment operator.</purpose>
<description>
<simpara>Assigns the content of <code>rhs</code> to the
content of
- <code>*this</code>.</simpara>
+ <code>*this</code>.<sbr/>
+ 将 <code>rhs</code> 内容赋值给 <code>*this</code> 的内容。
</simpara>
</description>
<requires>
<simpara><code>T</code> must fulfill the requirements of
the <conceptname>Assignable</conceptname>
- concept.</simpara>
+ concept.<sbr/>
+ <code>T</code> 必须符合 <conceptname>Assignable</conceptname>
概念的要求。</simpara>
</requires>
<throws>
<simpara>May fail with any exceptions arising from the
assignment
- operator of <code>T</code>.</simpara>
+ operator of <code>T</code>.<sbr/>
+ 可能因 <code>T</code> 的赋值操作符所引起的异常而失败。
</simpara>
</throws>
</method>
@@ -154,18 +176,21 @@
<purpose>Value assignment operator.</purpose>
<description>
<simpara>Assigns <code>rhs</code> into the content of
- <code>*this</code>.</simpara>
+ <code>*this</code>.<sbr/>
+ 将 <code>rhs</code> 赋值给 <code>*this</code> 的内容。
</simpara>
</description>
<requires>
<simpara><code>T</code> must fulfill the requirements of the
<conceptname>Assignable</conceptname>
- concept.</simpara>
+ concept.<sbr/>
+ <code>T</code> 必须符合 <conceptname>Assignable</conceptname>
概念的要求。</simpara>
</requires>
<throws>
<simpara>May fail with any exceptions arising from the
assignment
- operator of <code>T</code>.</simpara>
+ operator of <code>T</code>.<sbr/>
+ 可能因 <code>T</code> 的赋值操作符所引起的异常而失败。
</simpara>
</throws>
</method>
@@ -183,10 +208,12 @@
<description>
<simpara>Returns a reference to the content of
- <code>*this</code>.</simpara>
+ <code>*this</code>.<sbr/>
+ 返回 <code>*this</code> 的内容的一个引用。</simpara>
</description>
- <throws>Will not throw.</throws>
+ <throws>Will not throw.<sbr/>
+ 不会抛出。</throws>
</overloaded-method>
<overloaded-method name="get_pointer">
@@ -199,10 +226,12 @@
<description>
<simpara>Returns a pointer to the content of
- <code>*this</code>.</simpara>
+ <code>*this</code>.<sbr/>
+ 返回 <code>*this</code> 的内容的一个指针。</simpara>
</description>
- <throws>Will not throw.</throws>
+ <throws>Will not throw.<sbr/>
+ 不会抛出。</throws>
</overloaded-method>
</method-group>
@@ -212,7 +241,8 @@
<class name="is_recursive_wrapper">
<purpose>
<simpara>Determines whether the specified type is a specialization
of
- <code>recursive_wrapper</code>.</simpara>
+ <code>recursive_wrapper</code>.<sbr/>
+ 判断指定类型是否 <code>recursive_wrapper</code> 的特化。
</simpara>
</purpose>
<template>
@@ -221,11 +251,14 @@
<description>
<simpara>Value is true iff <code>T</code> is a specialization of
- <code><classname>recursive_wrapper</classname></code>.</simpara>
- <simpara><emphasis role="bold">Note</emphasis>:
+ <code><classname>recursive_wrapper</classname></code>.<sbr/>
+ Value 为 true 当且仅当 <code>T</code> 是
<code><classname>recursive_wrapper</classname></code> 的一个特化。</simpara>
+ <simpara><emphasis role="bold">Note 备注</emphasis>:
<code>is_recursive_wrapper</code> is a model of
<libraryname>MPL</libraryname>'s
- <emphasis>IntegralConstant</emphasis> concept.</simpara>
+ <emphasis>IntegralConstant</emphasis> concept.<sbr/>
+ <code>is_recursive_wrapper</code> 符合
<libraryname>MPL</libraryname> 的
+ <emphasis>IntegralConstant</emphasis> 概念。</simpara>
</description>
<typedef name="type">
@@ -241,7 +274,8 @@
<class name="unwrap_recursive_wrapper">
<purpose>
<simpara>Unwraps the specified argument if given a specialization
of
- <code><classname>recursive_wrapper</classname></code>.</simpara>
+ <code><classname>recursive_wrapper</classname></code>.<sbr/>
+ 解开给定参数的包装，如果它是
<code><classname>recursive_wrapper</classname></code> 的特化。</simpara>
</purpose>
<template>
@@ -252,7 +286,10 @@
<simpara><code>type</code> is equivalent to <code>T::type</code> if
<code>T</code> is a specialization of
<code><classname>recursive_wrapper</classname></code>. Otherwise,
- <code>type</code> is equivalent to <code>T</code>.</simpara>
+ <code>type</code> is equivalent to <code>T</code>.<sbr/>
+ <code>type</code> 等同于 <code>T::type</code> 如果
<code>T</code> 是
+ <code><classname>recursive_wrapper</classname></code> 的一个特
化。
+ 否则，<code>type</code> 等同于 <code>T</code>.</simpara>
</description>
<typedef name="type">
=======================================
--- /trunk/libs/variant/doc/reference/reference.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/variant/doc/reference/reference.xml Mon Jul 19 23:54:43 2010
@@ -8,7 +8,8 @@
<header name="boost/variant.hpp">
<section id="variant.header.include-all">
<para>This header exists simply as a convenience to the user,
including
- all of the headers in the <code>boost/variant</code>
directory.</para>
+ all of the headers in the <code>boost/variant</code> directory.<sbr/>
+ 本头文件是为了方便用户而存在，它包含了 <code>boost/variant</code> 目
录中的所有头文件。</para>
</section>
</header>
=======================================
--- /trunk/libs/variant/doc/reference/static_visitor.xml Mon Dec 28
23:05:14 2009
+++ /trunk/libs/variant/doc/reference/static_visitor.xml Mon Jul 19
23:54:43 2010
@@ -9,21 +9,27 @@
<template-type-parameter name="ResultType"/>
</template>
- <purpose>Convenient base type for static visitors.</purpose>
+ <purpose>Convenient base type for static visitors.<sbr/>
+ 用作静态访问者的基类。</purpose>
<description>
<simpara>Denotes the intent of the deriving class as meeting the
requirements of a static visitor of some type. Also exposes the
inner type <code>result_type</code> as required by the
<link
linkend="variant.concepts.static-visitor"><emphasis>StaticVisitor</emphasis></link>
- concept.</simpara>
- <simpara><emphasis role="bold">Notes</emphasis>:
+ concept.<sbr/>
+ 表明其派生类的意图是符合作为某个类型的静态访问者的要求。
+ 并按照 <link
linkend="variant.concepts.static-visitor"><emphasis>StaticVisitor</emphasis></link>
+ 概念的要求提供内嵌类型 <code>result_type</code>.</simpara>
+ <simpara><emphasis role="bold">Notes 备注</emphasis>:
<code>static_visitor</code> is intended for use as a base type
only
- and is therefore noninstantiable.</simpara>
+ and is therefore noninstantiable.<sbr/>
+ <code>static_visitor</code> 的唯一目的就是用作基类，所以是不可实
例化的。</simpara>
</description>
<typedef name="result_type">
<type>ResultType</type>
- <purpose>Exposes result_type member as required by StaticVisitor
concept.</purpose>
+ <purpose>Exposes result_type member as required by StaticVisitor
concept.<sbr/>
+ 按 StaticVisitor 概念的要求给出 result_type 成员。</purpose>
</typedef>
</class>
=======================================
--- /trunk/libs/variant/doc/reference/variant.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/variant/doc/reference/variant.xml Mon Jul 19 23:54:43 2010
@@ -4,7 +4,8 @@
<header name="boost/variant/variant.hpp">
<namespace name="boost">
<class name="variant">
- <purpose>Safe, generic, stack-based discriminated union
container.</purpose>
+ <purpose>Safe, generic, stack-based discriminated union
container.<sbr/>
+ 安全、泛型、基于栈的可识别联合容器。</purpose>
<description>
<simpara>The <code>variant</code> class template (inspired by
Andrei
Alexandrescu's class of the same name
@@ -19,29 +20,46 @@
<code>variant</code> supports compile-time checked, type-safe
visitation; and through
<code><functionname>get</functionname></code>,
<code>variant</code> supports run-time checked, type-safe value
- retrieval.</simpara>
-
- <simpara><emphasis role="bold">Notes</emphasis>:</simpara>
+ retrieval.<sbr/>
+ <code>variant</code> 类模板(灵感来自于 Andrei Alexandrescu 的同名类
+ [<link linkend="variant.refs.ale01a">Ale01A</link>])是一个高效的、
+ <link linkend="variant.tutorial.recursive">可递归的</link>、可保存
任意值类型(POD 或 非-POD)的有界可识别值类型。
+ 它可以构造自任意可转换为其任一有界类型的类型，或者构造自一个源
<code>variant</code>，只要源
+ <code>variant</code> 的每个有界类型可以转换为目标
<code>variant</code> 的某个有界类型。
+ 通过使用 <code><functionname>apply_visitor</functionname></code>,
<code>variant</code>
+ 可以支持编译期检查的、类型安全的访问；而通过
<code><functionname>get</functionname></code>,
+ <code>variant</code> 可以支持运行期检查的、类型安全的值取出。
</simpara>
+
+ <simpara><emphasis role="bold">Notes 说明</emphasis>:</simpara>
<itemizedlist>
<listitem>The bounded types of the <code>variant</code> are
exposed
via the nested typedef <code>types</code>, which is an
<libraryname>MPL</libraryname>-compatible Sequence containing
the
set of types that must be handled by any
<link linkend="variant.concepts.static-visitor">visitor</link>
to
- the <code>variant</code>.</listitem>
+ the <code>variant</code>.<sbr/>
+ <code>variant</code> 的有界类型通过内嵌的 typedef
<code>types</code> 获得，它是一个
+ <libraryname>MPL</libraryname>-兼容的序列，其中包含一组类型，这
些类型必须被访问该
+ <code>variant</code> 的 <link
linkend="variant.concepts.static-visitor">visitor</link> 所处理。</listitem>
<listitem>All members of <code>variant</code> satisfy at least
the
basic guarantee of exception-safety. That is, all operations on
a <code>variant</code> remain defined even after previous
- operations have failed.</listitem>
+ operations have failed.<sbr/>
+ <code>variant</code> 的所有成员至少要满足基本的异常安全保证。
+ 即，<code>variant</code> 的所有操作即使失败了也必须保持数据的一
致性。</listitem>
<listitem>Each type specified as a template argument to
<code>variant</code> must meet the requirements of the
<emphasis><link
linkend="variant.concepts.bounded-type">BoundedType</link></emphasis>
- concept.</listitem>
+ concept.<sbr/>
+ 每个被指定为 <code>variant</code> 的模板参数的类型必须满足
+ <emphasis><link
linkend="variant.concepts.bounded-type">BoundedType</link></emphasis> 概念的
要求。</listitem>
<listitem>Each type specified as a template argument to
<code>variant</code> must be distinct after removal of
qualifiers.
Thus, for instance, both <code>variant<int, int></code>
and
<code>variant<int, const int></code> have undefined
- behavior.</listitem>
+ behavior.<sbr/>
+ 每个被指定为 <code>variant</code> 的模板参数的类型必须在去除限
定符后是唯一的。因此，象
+ <code>variant<int, int></code> 和 <code>variant<int,
const int></code> 这样的类型的行为是未定义的。</listitem>
<listitem>Conforming implementations of <code>variant</code> must
allow at least ten types as template arguments. The exact
number
of allowed arguments is exposed by the preprocessor macro
@@ -49,7 +67,12 @@
(See <code><classname>make_variant_over</classname></code> for
a
means to specify the bounded types of a <code>variant</code> by
the elements of an <libraryname>MPL</libraryname> or compatible
- Sequence, thus overcoming this limitation.)</listitem>
+ Sequence, thus overcoming this limitation.)<sbr/>
+ 符合规范的 <code>variant</code> 实现必须至少允许10个类型作为模
板参数。
+ 实际所允许的参数数量由预处理器宏
<code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code> 获得。
+ (以 <libraryname>MPL</libraryname> 或兼容序列的元素来指定
<code>variant</code> 的有界类型，
+ 则可以超过这个限制，相关说明请见
<code><classname>make_variant_over</classname></code>)
+</listitem>
</itemizedlist>
</description>
@@ -70,10 +93,12 @@
<destructor>
<effects>
- <simpara>Destroys the content of <code>*this</code>.</simpara>
+ <simpara>Destroys the content of <code>*this</code>.<sbr/>
+ 销毁 <code>*this</code> 的内容。</simpara>
</effects>
- <throws>Will not throw.</throws>
+ <throws>Will not throw.<sbr/>
+ 不会抛出。</throws>
</destructor>
<constructor>
@@ -81,17 +106,21 @@
<simpara>The first bounded type of the <code>variant</code>
(i.e.,
<code>T1</code>) must fulfill the requirements of the
<emphasis>DefaultConstructible</emphasis> [20.1.4]
- concept.</simpara>
+ concept.<sbr/>
+ <code>variant</code> 的第一个有界类型(即 <code>T1</code>)必须符
合
+ <emphasis>DefaultConstructible</emphasis> [20.1.4] 概念的要求。
</simpara>
</requires>
<postconditions>
<simpara>Content of <code>*this</code> is the default value of
the
- first bounded type (i.e, <code>T1</code>).</simpara>
+ first bounded type (i.e, <code>T1</code>).<sbr/>
+ <code>*this</code> 的内容为第一个有界类型(即 <code>T1</code>)的
缺省值。</simpara>
</postconditions>
<throws>
<simpara>May fail with any exceptions arising from the default
- constructor of <code>T1</code>.</simpara>
+ constructor of <code>T1</code>.<sbr/>
+ 可能因 <code>T1</code> 的缺省构造函数所引起的任何异常而失败。
</simpara>
</throws>
</constructor>
@@ -102,12 +131,14 @@
<postconditions>
<simpara>Content of <code>*this</code> is a copy of the content
of
- <code>other</code>.</simpara>
+ <code>other</code>.<sbr/>
+ <code>*this</code> 的内容为 <code>other</code> 内容的一份拷贝。
</simpara>
</postconditions>
<throws>
<simpara>May fail with any exceptions arising from the
- copy constructor of <code>other</code>'s contained
type.</simpara>
+ copy constructor of <code>other</code>'s contained type.<sbr/>
+ 可能因 <code>other</code> 所含类型的复制构造函数所引起的任何异
常而失败。</simpara>
</throws>
</constructor>
@@ -123,18 +154,21 @@
<requires>
<simpara><code>T</code> must be unambiguously convertible to one
of
the bounded types (i.e., <code>T1</code>, <code>T2</code>,
- etc.).</simpara>
+ etc.).<sbr/>
+ <code>T</code> 必须明确地可转换为某个有界类型(如
<code>T1</code>, <code>T2</code>, 等)。</simpara>
</requires>
<postconditions>
<simpara>Content of <code>*this</code> is the best conversion of
<code>operand</code> to one of the bounded types, as determined
- by standard overload resolution rules.</simpara>
+ by standard overload resolution rules.<sbr/>
+ <code>*this</code> 的内容为 <code>operand</code> 到某个有界类型
的最佳转换，取决于标准的重载决议规则。</simpara>
</postconditions>
<throws>
<simpara>May fail with any exceptions arising from the
conversion of
- <code>operand</code> to one of the bounded types.</simpara>
+ <code>operand</code> to one of the bounded types.<sbr/>
+ 可能因 <code>operand</code> 至某个有界类型的转换所引起的任何异
常而失败。</simpara>
</throws>
</constructor>
@@ -149,7 +183,8 @@
<notes>
<simpara>Same semantics as previous constructor, but allows
- construction from temporaries.</simpara>
+ construction from temporaries.<sbr/>
+ 与前一构造函数语义相同，但允许构造自临时对象。</simpara>
</notes>
</constructor>
@@ -169,7 +204,10 @@
<simpara><emphasis>Every</emphasis> one of <code>U1</code>,
<code>U2</code>, ..., <code>UN</code> must have an unambiguous
conversion to one of the bounded types (i.e., <code>T1</code>,
- <code>T2</code>, ..., <code>TN</code>).</simpara>
+ <code>T2</code>, ..., <code>TN</code>).<sbr/>
+ <emphasis>每一个</emphasis> <code>U1</code>,
+ <code>U2</code>, ..., <code>UN</code> 都必须明确可转换为某个有
界类型(如 <code>T1</code>,
+ <code>T2</code>, ..., <code>TN</code>)。</simpara>
</requires>
<postconditions>
@@ -178,7 +216,10 @@
copy of <code>operand</code>. Otherwise, content of
<code>*this</code> is the best conversion of the content of
<code>operand</code> to one of the bounded types, as determined
- by standard overload resolution rules.</simpara>
+ by standard overload resolution rules.<sbr/>
+ 如果 <code>variant<U1, U2, ..., UN></code> 本身是其中一个
有界类型，则 <code>*this</code>
+ 的内容为 <code>operand</code> 的拷贝。否则，<code>*this</code>
的内容为 <code>operand</code>
+ 到某个有界类型的最佳转换，取决于标准的重载决议规则。</simpara>
</postconditions>
<throws>
@@ -187,7 +228,10 @@
from the copy constructor of
<code>variant<U1, U2, ..., UN></code>. Otherwise, may fail
with any exceptions arising from the conversion of the content of
- <code>operand</code> to one of the bounded types.</simpara>
+ <code>operand</code> to one of the bounded types.<sbr/>
+ 如果 <code>variant<U1, U2, ..., UN></code> 本身是其中一个有
界类型，则可能因
+ <code>variant<U1, U2, ..., UN></code> 的复制构造函数所引起
的任何异常而失败。
+ 否则，可能因 <code>operand</code> 至某个有界类型的转换所引起的任
何异常而失败。</simpara>
</throws>
</constructor>
@@ -205,7 +249,8 @@
<notes>
<simpara>Same semantics as previous constructor, but allows
- construction from temporaries.</simpara>
+ construction from temporaries.<sbr/>
+ 与前一构造函数语义相同，但允许构造自临时对象。</simpara>
</notes>
</constructor>
@@ -221,12 +266,14 @@
<requires>
<simpara>Every bounded type must fulfill the requirements of
the
<conceptname>Assignable</conceptname>
- concept.</simpara>
+ concept.<sbr/>
+ 每个有界类型都必须满足 <conceptname>Assignable</conceptname>
概念的要求。</simpara>
</requires>
<effects>
<simpara>Interchanges the content of <code>*this</code> and
- <code>other</code>.</simpara>
+ <code>other</code>.<sbr/>
+ 交换 <code>*this</code> 和 <code>other</code> 的内容。
</simpara>
</effects>
<throws>
@@ -237,7 +284,11 @@
with any exceptions arising from either of the copy
constructors
of the contained types. Also, in the event of insufficient
memory, may fail with <code>std::bad_alloc</code>
- (<link
linkend="variant.design.never-empty.problem">why?</link>).</simpara>
+ (<link
linkend="variant.design.never-empty.problem">why?</link>).<sbr/>
+ 如果 <code>other</code> 所含类型与 <code>*this</code> 所含类
型相同，则可能因 <code>*this</code>
+ 和 <code>other</code> 的内容的 swap 操作所引起的异常而失败。
+ 否则，可能因某个所含类型的复制构造函数所引起的异常而失败。
+ 也可能由于内存不足而抛出
<code>std::bad_alloc</code>.</simpara>
</throws>
</method>
@@ -251,7 +302,8 @@
<requires>
<simpara>Every bounded type must fulfill the requirements of
the
<conceptname>Assignable</conceptname>
- concept.</simpara>
+ concept.<sbr/>
+ 每个有界类型都必须满足 <conceptname>Assignable</conceptname>
概念的要求。</simpara>
</requires>
<effects>
@@ -260,7 +312,10 @@
content of <code>rhs</code> into the content of
<code>*this</code>. Otherwise, makes the content of
<code>*this</code> a copy of the content of <code>rhs</code>,
- destroying the previous content of
<code>*this</code>.</simpara>
+ destroying the previous content of <code>*this</code>.<sbr/>
+ 如果 <code>rhs</code> 所含类型与 <code>*this</code> 所含类型
相同，则将 <code>rhs</code>
+ 的内容赋值到 <code>*this</code> 的内容中。否则，将
<code>*this</code> 的内容变为
+ <code>rhs</code> 内容的一份拷贝，并销毁 <code>*this</code> 原
来的内容。</simpara>
</effects>
<throws>
@@ -271,7 +326,10 @@
may fail with any exceptions arising from the copy
constructor
of the contained type of <code>rhs</code>. Also, in the
event of
insufficient memory, may fail with
<code>std::bad_alloc</code>
- (<link
linkend="variant.design.never-empty.problem">why?</link>).</simpara>
+ (<link
linkend="variant.design.never-empty.problem">why?</link>).<sbr/>
+ 如果 <code>rhs</code> 所含类型与 <code>*this</code> 所含类型
相同，则可能因将 <code>rhs</code>
+ 的内容赋值到 <code>*this</code> 中而引起的异常而失败。否
则，可能因 <code>rhs</code>
+ 所含类型的复制构造函数所引起的异常而失败。也可能由于内存不足
而抛出 <code>std::bad_alloc</code>.</simpara>
</throws>
</method>
@@ -290,10 +348,12 @@
<itemizedlist>
<listitem><code>T</code> must be unambiguously convertible to
one of the bounded types (i.e., <code>T1</code>,
- <code>T2</code>, etc.).</listitem>
+ <code>T2</code>, etc.).<sbr/>
+ <code>T</code> 必须明确可转换为某个有界类型(即
<code>T1</code>, <code>T2</code>, 等)。 </listitem>
<listitem>Every bounded type must fulfill the requirements
of the
<conceptname>Assignable</conceptname>
- concept.</listitem>
+ concept.<sbr/>
+ 每个有界类型都必须满足
<conceptname>Assignable</conceptname> 概念的要求。</listitem>
</itemizedlist>
</requires>
@@ -304,7 +364,10 @@
<code>*this</code> the best conversion of <code>rhs</code> to
one of the bounded types, as determined by standard overload
resolution rules, destroying the previous content of
- <code>*this</code>.</simpara>
+ <code>*this</code>.<sbr/>
+ 如果 <code>*this</code> 所含类型为 T, 则将 <code>rhs</code>
赋为 <code>*this</code> 的内容。
+ 否则，将 <code>*this</code> 的内容变为从 <code>rhs</code> 到
某个有界类型的最佳转换，
+ 取决于标准的重载决议规则，并销毁 <code>*this</code> 原来的内
容。</simpara>
</effects>
<throws>
@@ -315,7 +378,10 @@
arising from the conversion of <code>rhs</code> to one of the
bounded types. Also, in the event of insufficient memory, may
fail with <code>std::bad_alloc</code>
- (<link
linkend="variant.design.never-empty.problem">why?</link>).</simpara>
+ (<link
linkend="variant.design.never-empty.problem">why?</link>).<sbr/>
+ 如果 <code>*this</code> 所含类型为 T, 则可能因将
<code>rhs</code> 赋为 <code>*this</code> 的内容所引起的异常而失败。
+ 否则，可能因从 <code>rhs</code> 到某个有界类型的转换所引起的
异常而失败。
+ 还可能由于内存不足而抛出
<code>std::bad_alloc</code>.</simpara>
</throws>
</method>
@@ -331,10 +397,14 @@
of the contained type of <code>*this</code>. (For instance,
if
called on a <code>variant<int, std::string></code>
object
containing a <code>std::string</code>, <code>which()</code>
- would return <code>1</code>.)</simpara>
+ would return <code>1</code>.)<sbr/>
+ <code>*this</code> 所含类型在有界类型集合中的索引值，从零起
计。
+ (例如，如果从一个包含 <code>std::string</code> 的
<code>variant<int, std::string></code>
+ 调用，<code>which()</code> 将返回 <code>1</code>.)</simpara>
</returns>
- <throws>Will not throw.</throws>
+ <throws>Will not throw.<sbr/>
+ 不会抛出异常。</throws>
</method>
<method name="empty" cv="const">
@@ -344,15 +414,19 @@
<simpara><code>false</code>: <code>variant</code> always
contains
exactly one of its bounded types. (See
<xref linkend="variant.design.never-empty"/>
- for more information.)</simpara>
+ for more information.)<sbr/>
+ <code>false</code>: <code>variant</code> 总是刚好包含某一个有
界类型。(更多信息请见
+ <xref linkend="variant.design.never-empty"/>)</simpara>
</returns>
<rationale>
<simpara>Facilitates generic compatibility with
- <classname>boost::any</classname>.</simpara>
+ <classname>boost::any</classname>.<sbr/>
+ 便于与 <classname>boost::any</classname> 的泛型兼容。
</simpara>
</rationale>
- <throws>Will not throw.</throws>
+ <throws>Will not throw.<sbr/>
+ 不会抛出异常。</throws>
</method>
<method name="type" cv="const">
@@ -360,14 +434,17 @@
<returns>
<simpara><code>typeid(x)</code>, where <code>x</code> is the
the
- content of <code>*this</code>.</simpara>
+ content of <code>*this</code>.<sbr/>
+ <code>typeid(x)</code>, 其中 <code>x</code> 为
<code>*this</code> 的内容。</simpara>
</returns>
- <throws>Will not throw.</throws>
+ <throws>Will not throw.<sbr/>
+ 不会抛出异常。</throws>
<notes>
<simpara>Not available when <code>BOOST_NO_TYPEID</code> is
- defined.</simpara>
+ defined.<sbr/>
+ 当定义了 <code>BOOST_NO_TYPEID</code> 时无效。</simpara>
</notes>
</method>
@@ -399,14 +476,17 @@
<simpara>The overload returning <code>void</code> exists only
to
prohibit implicit conversion of the operator's right-hand
side
to <code>variant</code>; thus, its use will (purposefully)
- result in a compile-time error.</simpara>
+ result in a compile-time error.<sbr/>
+ 存在一个返回 <code>void</code> 的重载只是为了防止右操作数隐式
转换为 <code>variant</code>;
+ 这样的用法将(被有意地)引发一个编译错误。</simpara>
</notes>
<requires>
<simpara>Every bounded type of the <code>variant</code> must
fulfill the requirements of the
<conceptname>EqualityComparable</conceptname>
- concept.</simpara>
+ concept.<sbr/>
+ <code>variant</code> 的每一个有界类型都必须满足
<conceptname>EqualityComparable</conceptname> 概念的要求。</simpara>
</requires>
<returns>
@@ -415,14 +495,18 @@
<code>content_this == content_rhs</code>, where
<code>content_this</code> is the content of
<code>*this</code>
and <code>content_rhs</code> is the content of
- <code>rhs</code>.</simpara>
+ <code>rhs</code>.<sbr/>
+ <code>true</code> 当且仅当 <code>which() ==
rhs.which()</code> 且 <code>content_this == content_rhs</code>,
+ 其中 <code>content_this</code> 为 <code>*this</code> 的内容
而 <code>content_rhs</code> 为 <code>rhs</code> 的内容。</simpara>
</returns>
<throws>
<simpara>If <code>which() == rhs.which()</code> then may fail
with
any exceptions arising from <code>operator==(T,T)</code>,
where
<code>T</code> is the contained type of
- <code>*this</code>.</simpara>
+ <code>*this</code>.<sbr/>
+ 如果 <code>which() == rhs.which()</code> 则可能因
<code>operator==(T,T)</code>
+ 所引起的异常而失败，其中 <code>T</code> 为
<code>*this</code> 所含类型。</simpara>
</throws>
</overloaded-method>
@@ -450,14 +534,17 @@
<simpara>The overload returning <code>void</code> exists only
to
prohibit implicit conversion of the operator's right-hand
side
to <code>variant</code>; thus, its use will (purposefully)
- result in a compile-time error.</simpara>
+ result in a compile-time error.<sbr/>
+ 存在一个返回 <code>void</code> 的重载只是为了防止右操作数隐式
转换为 <code>variant</code>;
+ 这样的用法将(被有意地)引发一个编译错误。</simpara>
</notes>
<requires>
<simpara>Every bounded type of the <code>variant</code> must
fulfill the requirements of the
<conceptname>LessThanComparable</conceptname>
- concept.</simpara>
+ concept.<sbr/>
+ <code>variant</code> 的每一个有界类型都必须满足
<conceptname>LessThanComparable</conceptname> 概念的要求。</simpara>
</requires>
<returns>
@@ -465,14 +552,19 @@
<code>content_this < content_rhs</code>, where
<code>content_this</code> is the content of
<code>*this</code>
and <code>content_rhs</code> is the content of
<code>rhs</code>.
- Otherwise: <code>which() < rhs.which()</code>.</simpara>
+ Otherwise: <code>which() < rhs.which()</code>.<sbr/>
+ 如果 <code>which() == rhs.which()</code> 则返
回：<code>content_this < content_rhs</code>,
+ 其中 <code>content_this</code> 为 <code>*this</code> 的内容
而 <code>content_rhs</code> 为
+ <code>rhs</code> 的内容。否则返回：<code>which() <
rhs.which()</code>.</simpara>
</returns>
<throws>
<simpara>If <code>which() == rhs.which()</code> then may fail
with
any exceptions arising from <code>operator<(T,T)</code>,
where <code>T</code> is the contained type of
- <code>*this</code>.</simpara>
+ <code>*this</code>.<sbr/>
+ 如果 <code>which() == rhs.which()</code> 则可能因
<code>operator==(T,T)</code>
+ 所引起的异常而失败，其中 <code>T</code> 为
<code>*this</code> 所含类型。</simpara>
</throws>
</overloaded-method>
@@ -499,12 +591,14 @@
<effects>
<simpara>Swaps <code>lhs</code> with <code>rhs</code> by
application
- of <code><methodname>variant::swap</methodname></code>.</simpara>
+ of <code><methodname>variant::swap</methodname></code>.<sbr/>
+ 通过调用 <code><methodname>variant::swap</methodname></code> 来交
换<code>lhs</code> 和 <code>rhs</code>。</simpara>
</effects>
<throws>
<simpara>May fail with any exception arising from
- <code><methodname>variant::swap</methodname></code>.</simpara>
+ <code><methodname>variant::swap</methodname></code>.<sbr/>
+ 可能由于 <code><methodname>variant::swap</methodname></code> 抛出
的任何异常而失败。</simpara>
</throws>
</function>
@@ -534,17 +628,21 @@
<simpara>Every bounded type of the <code>variant</code> must
fulfill the requirements of the
<link
linkend="variant.concepts.output-streamable"><emphasis>OutputStreamable</emphasis></link>
- concept.</simpara>
+ concept.<sbr/>
+ <code>variant</code> 的每个有界类型必须满足
+ <link
linkend="variant.concepts.output-streamable"><emphasis>OutputStreamable</emphasis></link>
概念的要求。</simpara>
</requires>
<effects>
<simpara>Calls <code>out << x</code>, where <code>x</code> is
- the content of <code>rhs</code>.</simpara>
+ the content of <code>rhs</code>.<sbr/>
+ 调用 <code>out << x</code>, 其中 <code>x</code> 为
<code>rhs</code> 的内容。</simpara>
</effects>
<notes>
<simpara>Not available when <code>BOOST_NO_IOSTREAM</code> is
- defined.</simpara>
+ defined.<sbr/>
+ 当定义了 <code>BOOST_NO_IOSTREAM</code> 时无效。</simpara>
</notes>
</function>
@@ -552,7 +650,8 @@
<class name="make_variant_over">
<purpose>
<simpara>Exposes a <code>variant</code> whose bounded types are the
- elements of the given type sequence.</simpara>
+ elements of the given type sequence.<sbr/>
+ 提供一个 <code>variant</code>，其有界类型为给定类型序列的元素。
</simpara>
</purpose>
<template>
@@ -568,18 +667,25 @@
<code><classname>variant</classname>< Sequence[0],
Sequence[1], ... ></code>
(where <code>Sequence[<emphasis>i</emphasis>]</code> denotes the
<emphasis>i</emphasis>-th element of <code>Sequence</code>),
except
- that no upper limit is imposed on the number of types.</simpara>
-
- <simpara><emphasis role="bold">Notes</emphasis>:</simpara>
+ that no upper limit is imposed on the number of types.<sbr/>
+ <code>type</code> 的行为在各方面均等同于
<code><classname>variant</classname>< Sequence[0], Sequence[1], ...
></code>
+ (其中 <code>Sequence[<emphasis>i</emphasis>]</code> 表示
<code>Sequence</code> 的第<emphasis>i</emphasis>个元素)，
+ 除了一点，即类型的数量没有上限。</simpara>
+
+ <simpara><emphasis role="bold">Notes 注</emphasis>:</simpara>
<itemizedlist>
<listitem><code>Sequence</code> must meet the requirements of
<libraryname>MPL</libraryname>'s <emphasis>Sequence</emphasis>
- concept.</listitem>
+ concept.<sbr/>
+ <code>Sequence</code> 必须符合 <libraryname>MPL</libraryname>
的 <emphasis>Sequence</emphasis> 概念的要求。</listitem>
<listitem>Due to standard conformance problems in several
compilers,
<code>make_variant_over</code> may not be supported on your
compiler. See
<code><macroname>BOOST_VARIANT_NO_TYPE_SEQUENCE_SUPPORT</macroname></code>
- for more information.</listitem>
+ for more information.<sbr/>
+ 由于在某些编译器上的标准符合问
题，<code>make_variant_over</code> 可能在你的编译器上不被支持。
+ 更多信息请见
<code><macroname>BOOST_VARIANT_NO_TYPE_SEQUENCE_SUPPORT</macroname></code>.
+</listitem>
</itemizedlist>
</description>
</class>
=======================================
--- /trunk/libs/variant/doc/reference/variant_fwd.xml Mon Dec 28 23:05:14
2009
+++ /trunk/libs/variant/doc/reference/variant_fwd.xml Mon Jul 19 23:54:43
2010
@@ -8,20 +8,28 @@
<code><classname>boost::make_recursive_variant</classname></code>, and
<code><classname>boost::make_recursive_variant_over</classname></code>
class templates and the <code>boost::recursive_variant_</code> tag
type.
- Also defines several preprocessor symbols, as described below.</para>
+ Also defines several preprocessor symbols, as described below.<sbr/>
+ 提供 <code><classname>boost::variant</classname></code>,
+ <code><classname>boost::make_variant_over</classname></code>,
+ <code><classname>boost::make_recursive_variant</classname></code>, 和
+ <code><classname>boost::make_recursive_variant_over</classname></code>
类模板的前向声明以及
+ <code>boost::recursive_variant_</code> 类型。还定义了以下几个预处理器符
号：</para>
<macro name="BOOST_VARIANT_LIMIT_TYPES">
<purpose>
<simpara>Expands to the length of the
template parameter list for
- <code><classname>variant</classname></code>.</simpara>
+ <code><classname>variant</classname></code>.<sbr/>
+ 展开为 <code><classname>variant</classname></code> 的模板参数列表的
长度。</simpara>
</purpose>
<description>
<para><emphasis role="bold">Note</emphasis>: Conforming
implementations of <code>variant</code> must allow at least ten
template arguments. That is, BOOST_VARIANT_LIMIT_TYPES must be
greater
- or equal to <code>10</code>.</para>
+ or equal to <code>10</code>.<sbr/>
+ <emphasis role="bold">注</emphasis>：符合规范的
<code>variant</code> 实现必须至少支持十个模板参数。
+ 即 BOOST_VARIANT_LIMIT_TYPES 必须大于等于 <code>10</code>.</para>
</description>
</macro>
@@ -30,7 +38,8 @@
<purpose>
<simpara>Enumerate parameters for use with
- <code><classname>variant</classname></code>.</simpara>
+ <code><classname>variant</classname></code>.<sbr/>
+ 用于列举 <code><classname>variant</classname></code> 的参数。
</simpara>
</purpose>
<description>
@@ -39,14 +48,20 @@
each element in the sequence consists of the concatenation of
<emphasis>param</emphasis> with its zero-based index into the
sequence. That is,
- <code>param ## 0, param ## 1, ..., param ##
BOOST_VARIANT_LIMIT_TYPES - 1</code>.</para>
+ <code>param ## 0, param ## 1, ..., param ##
BOOST_VARIANT_LIMIT_TYPES - 1</code>.<sbr/>
+ 展开为长度等于
<code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code> 的以逗号分隔的
序列，
+ 序列中的每一个元素为 <emphasis>param</emphasis> 后跟一个索引，索引
值从零起计。
+ 即 <code>param ## 0, param ## 1, ..., param ##
BOOST_VARIANT_LIMIT_TYPES - 1</code>.</para>
<para><emphasis role="bold">Rationale</emphasis>: This macro greatly
simplifies for the user the process of declaring
<code><classname>variant</classname></code> types
in function templates or explicit partial specializations of class
templates, as shown in the
- <link
linkend="variant.tutorial.preprocessor">tutorial</link>.</para>
+ <link
linkend="variant.tutorial.preprocessor">tutorial</link>.<sbr/>
+ <emphasis role="bold">原理</emphasis>：该宏大大简化了用户在函数模板
或类模板的显式偏特化中声明
+ <code><classname>variant</classname></code> 类型的过程，就象在
+ <link linkend="variant.tutorial.preprocessor">指南</link> 中所示范
的那样。</para>
</description>
</macro>
@@ -55,7 +70,8 @@
<purpose>
<simpara>Enumerate all but the first parameter for use with
- <code><classname>variant</classname></code>.</simpara>
+ <code><classname>variant</classname></code>.<sbr/>
+ 用于列举 <code><classname>variant</classname></code> 除第一个参数以
外的其它参数。</simpara>
</purpose>
<description>
@@ -64,24 +80,33 @@
where each element in the sequence consists of the concatenation of
<emphasis>param</emphasis> with its one-based index into the
sequence.
That is,
- <code>param ## 1, ..., param ## BOOST_VARIANT_LIMIT_TYPES -
1</code>.</para>
+ <code>param ## 1, ..., param ## BOOST_VARIANT_LIMIT_TYPES -
1</code>.<sbr/>
+ 展开为长度等于
<code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname> - 1</code> 的以逗号分
隔的序列，
+ 序列中的每个元素为 <emphasis>param</emphasis> 后跟一个索引，索引值
从一起计。
+ 即 <code>param ## 1, ..., param ## BOOST_VARIANT_LIMIT_TYPES -
1</code>.
+
+</para>
<para><emphasis role="bold">Note</emphasis>: This macro results in
the
same expansion as
<code><macroname>BOOST_VARIANT_ENUM_PARAMS</macroname></code> --
but
- without the first term.</para>
+ without the first term.<sbr/>
+ <emphasis role="bold">注</emphasis>：该宏的展开结果与
<code><macroname>BOOST_VARIANT_ENUM_PARAMS</macroname></code>
+ 相同 -- 除了第一项。</para>
</description>
</macro>
<macro name="BOOST_VARIANT_NO_REFERENCE_SUPPORT">
<purpose>
<simpara>Indicates <code><classname>variant</classname></code> does
not
- support references as bounded types.</simpara>
+ support references as bounded types.<sbr/>
+ 表示 <code><classname>variant</classname></code> 不支持以引用作为有
界类型。</simpara>
</purpose>
<description>
<para>Defined only if <code><classname>variant</classname></code>
does
- not support references as bounded types.</para>
+ not support references as bounded types.<sbr/>
+ 仅在 <code><classname>variant</classname></code> 不支持以引用作为有
界类型时定义。</para>
</description>
</macro>
@@ -89,14 +114,17 @@
<purpose>
<simpara>Indicates absence of support for specifying the bounded
types
of a <code><classname>variant</classname></code> by the elements
of a
- type sequence.</simpara>
+ type sequence.<sbr/>
+ 表示不能支持以类型序列的元素来指定
<code><classname>variant</classname></code> 的有界类型。</simpara>
</purpose>
<description>
<para>Defined only if
<code><classname>make_variant_over</classname></code> and
<code><classname>make_recursive_variant_over</classname></code>
- are not supported for some reason on the target compiler.</para>
+ are not supported for some reason on the target compiler.<sbr/>
+ 仅当 <code><classname>make_variant_over</classname></code> 和
+ <code><classname>make_recursive_variant_over</classname></code> 因
为某种原因在目标编译器上不被支持时被定义。</para>
</description>
</macro>
@@ -104,21 +132,27 @@
<purpose>
<simpara>Indicates
<code><classname>make_recursive_variant</classname></code>
operates in
- an implementation-defined manner.</simpara>
+ an implementation-defined manner.<sbr/>
+ 表示 <code><classname>make_recursive_variant</classname></code> 以
实现定义的方式来操作。</simpara>
</purpose>
<description>
<para>Defined only if
<code><classname>make_recursive_variant</classname></code> does not
operate as documented on the target compiler, but rather in an
- implementation-defined manner.</para>
+ implementation-defined manner.<sbr/>
+ 仅当 <code><classname>make_recursive_variant</classname></code> 不
能在目标编译器上使用时定义，
+ 但可以以实现定义的方式来操作。</para>
<para><emphasis role="bold">Implementation Note</emphasis>: If
<code>BOOST_VARIANT_NO_FULL_RECURSIVE_VARIANT_SUPPORT</code> is
defined for the target compiler, the current implementation uses
the
<libraryname>MPL</libraryname> lambda mechanism to approximate the
desired behavior. (In most cases, however, such compilers do not
have
- full lambda support either.)</para>
+ full lambda support either.)<sbr/>
+ <emphasis role="bold">实现说明</emphasis>：如果
<code>BOOST_VARIANT_NO_FULL_RECURSIVE_VARIANT_SUPPORT</code>
+ 在目标编译器上被定义，则当前实现使用
<libraryname>MPL</libraryname> lambda 机制来得到所需的行为。
+ (但是在多数情况下，这些编译器也不能完全支持 lambda)</para>
</description>
</macro>
</header>
=======================================
--- /trunk/libs/variant/doc/reference/visitor_ptr.xml Mon Dec 28 23:05:14
2009
+++ /trunk/libs/variant/doc/reference/visitor_ptr.xml Mon Jul 19 23:54:43
2010
@@ -10,11 +10,14 @@
<template-type-parameter name="R"/>
</template>
- <purpose>Adapts a function pointer for use as a static
visitor.</purpose>
+ <purpose>Adapts a function pointer for use as a static visitor.<sbr/>
+ 将一个函数指针适配为一个静态访问者。</purpose>
<description>
<simpara>Adapts the function given at construction for use as a
<link linkend="variant.concepts.static-visitor">static
visitor</link>
- of type <code>T</code> with result type <code>R</code>.</simpara>
+ of type <code>T</code> with result type <code>R</code>.<sbr/>
+ 将在构造时给定的函数适配为类型 <code>T</code> 的一个 <link
linkend="variant.concepts.static-visitor">静态访问者</link>，
+ 返回类型为 <code>R</code>.</simpara>
</description>
<inherit
access="public"><classname>static_visitor</classname><R></inherit>
@@ -25,7 +28,8 @@
</parameter>
<effects>
- <simpara>Constructs the visitor with the given
function.</simpara>
+ <simpara>Constructs the visitor with the given function.<sbr/>
+ 以给定的函数构造访问者。</simpara>
</effects>
</constructor>
@@ -55,15 +59,19 @@
<simpara>If passed a value or reference of type
<code>T</code>, it invokes the function given at
construction, appropriately forwarding
- <code>operand</code>.</simpara>
+ <code>operand</code>.<sbr/>
+ 如果传入的是类型 <code>T</code> 的一个值或引用，则调用在构造
时给定的函数，并适当地转发 <code>operand</code>.</simpara>
</effects>
- <returns>Returns the result of the function invocation.</returns>
+ <returns>Returns the result of the function invocation.<sbr/>
+ 返回函数调用的结果。</returns>
<throws id="visitor_ptr_t.visit.throws">
<simpara>The overload taking a value or reference of type
<code>T</code> throws if the invoked function throws.
The overload taking all other values
<emphasis>always</emphasis>
- throws
<code><classname>bad_visit</classname></code>.</simpara>
+ throws <code><classname>bad_visit</classname></code>.<sbr/>
+ 接受类型 <code>T</code> 的一个值或引用的重载会在所调用的函数
抛出异常时抛出。
+ 接受所有其它值的重载则<emphasis>总是</emphasis>抛出
<code><classname>bad_visit</classname></code>.</simpara>
</throws>
</overloaded-method>
</method-group>
@@ -72,12 +80,14 @@
<function name="visitor_ptr">
<purpose>
<simpara>Returns a visitor object that adapts function pointers for
- use as a static visitor.</simpara>
+ use as a static visitor.<sbr/>
+ 返回一个访问者对象，将函数指针适配为静态访问者。</simpara>
</purpose>
<description>
<simpara>Constructs and returns a
<code><classname>visitor_ptr_t</classname></code> adaptor over the
- given function.</simpara>
+ given function.<sbr/>
+ 构造并返回给定函数的一个
<code><classname>visitor_ptr_t</classname></code> 适配器。</simpara>
</description>
<template>
@@ -94,13 +104,15 @@
<returns>
<simpara>Returns a
<code><classname>visitor_ptr_t</classname></code>
visitor object that, when applied, invokes the given
- function.</simpara>
+ function.<sbr/>
+ 返回一个 <code><classname>visitor_ptr_t</classname></code> 访问者
对象，应用该访问者时，将调用给定的函数。</simpara>
</returns>
<throws>
<simpara>Will not throw. (Note, however, that the returned
<classname alt="boost::visitor_ptr_t">visitor object</classname>
may
- throw when applied.)</simpara>
+ throw when applied.)<sbr/>
+ 不会抛出。(不过请注意，返回的 <classname
alt="boost::visitor_ptr_t">访问者对象</classname> 可能在使用时抛出
)</simpara>
</throws>
</function>
=======================================
--- /trunk/libs/variant/doc/tutorial/advanced.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/variant/doc/tutorial/advanced.xml Mon Jul 19 23:54:43 2010
@@ -2,7 +2,7 @@
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
<section id="variant.tutorial.advanced">
- <title>Advanced Topics</title>
+ <title>Advanced Topics 高级议题</title>
<using-namespace name="boost"/>
<using-class name="boost::variant"/>
@@ -11,10 +11,14 @@
for advanced uses of <code>variant</code>. Unlike in the above section,
each
feature presented below is largely independent of the others.
Accordingly,
this section is not necessarily intended to be read linearly or in its
- entirety.</para>
+ entirety.<sbr/>
+ 本节将讨论本库的几个特性，这些特性通常在 <code>variant</code> 的高级用法
中使用。
+ 与前面一节不同，以下介绍的各个特性与其它特性间互不依赖。因此，这一节不需
要按顺序阅读或者全部读完。
+
+</para>
<section id="variant.tutorial.preprocessor">
- <title>Preprocessor macros</title>
+ <title>Preprocessor macros 预处理器宏</title>
<para>While the <code>variant</code> class template's variadic parameter
list greatly simplifies use for specific instantiations of the
template,
@@ -22,7 +26,10 @@
while it is immediately clear how one might write a function accepting
a
specific <code>variant</code> instantiation, say
<code>variant<int, std::string></code>, it is less clear how one
- might write a function accepting any given <code>variant</code>.</para>
+ might write a function accepting any given <code>variant</code>.<sbr/>
+ 虽然 <code>variant</code> 类模板的可变长度参数列表大大简化了该模板在使
用时的实例化，但是也使得该模板的泛型实例化变得复杂了。
+ 例如，如何编写一个接受某个特定 <code>variant</code> 实例的函数是很显然
的，如 <code>variant<int, std::string></code>,
+ 但是如何编写一个接受任意 <code>variant</code> 的函数就不太明显了。
</para>
<para>Due to the lack of support for true variadic template parameter
lists
in the C++98 standard, the preprocessor is needed. While the
@@ -31,11 +38,19 @@
<code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code>
unnecessarily clutters otherwise simple code. Therefore, for common
use-cases, this library provides its own macro
- <code><emphasis
role="bold"><macroname>BOOST_VARIANT_ENUM_PARAMS</macroname></emphasis></code>.</para>
+ <code><emphasis
role="bold"><macroname>BOOST_VARIANT_ENUM_PARAMS</macroname></emphasis></code>.<sbr/>
+ 由于C++98标准在支持真正的可变长度模板参数方面的不足，所以这里需要预处理
器。
+ 虽然 <libraryname>Preprocessor</libraryname> 库提供了通用和强大的解决方
法，但是重复
+ <code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code> 次对于简
单代码而言还是过于混乱。
+ 因此，本库为最常见的用例提供了自己的宏
+ <code><emphasis
role="bold"><macroname>BOOST_VARIANT_ENUM_PARAMS</macroname></emphasis></code>.
+
+</para>
<para>This macro simplifies for the user the process of declaring
<code>variant</code> types in function templates or explicit partial
- specializations of class templates, as shown in the following:
+ specializations of class templates, as shown in the following:<sbr/>
+ 该宏简化了用户在函数模板或类模板的显式偏特化中声明
<code>variant</code> 类型的方式，举例如下：
<programlisting>// general cases
template <typename T> void some_func(const T &);
@@ -54,7 +69,7 @@
</section>
<section id="variant.tutorial.over-sequence">
- <title>Using a type sequence to specify bounded types</title>
+ <title>Using a type sequence to specify bounded types 用一个类型序列来指
定有界类型</title>
<para>While convenient for typical uses, the <code>variant</code> class
template's variadic template parameter list is limiting in two
significant
@@ -63,21 +78,29 @@
implementation-defined maximum (namely,
<code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code>).
Second, the nature of parameter lists in general makes compile-time
- manipulation of the lists excessively difficult.</para>
+ manipulation of the lists excessively difficult.<sbr/>
+ 虽然很方便使用，但是 <code>variant</code> 类模板的变长模板参数列表还是
在两方面在明显的限制。
+ 首先，由于C++在支持真正的变长模板参数方面的不足，参数的数量肯定要受限于
某个实现定义的最大值
+ (即 <code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code>)。
+ 其次，参数列表本身的性质通常会使得列表的编译期操作非常困难。</para>
<para>To solve these problems,
<code>make_variant_over< <emphasis>Sequence</emphasis> ></code>
exposes a <code>variant</code> whose bounded types are the elements of
<code>Sequence</code> (where <code>Sequence</code> is any type
fulfilling
the requirements of <libraryname>MPL</libraryname>'s
- <emphasis>Sequence</emphasis> concept). For instance,
+ <emphasis>Sequence</emphasis> concept). For instance,<sbr/>
+ 为了解决这些问题，<code>make_variant_over<
<emphasis>Sequence</emphasis> ></code> 可以以 <code>Sequence</code> 的元
素
+ (这里的 <code>Sequence</code> 是满足 <libraryname>MPL</libraryname> 的
<emphasis>Sequence</emphasis> 概念的任意类型)
+ 作为一个 <code>variant</code> 的有界类型。例如，
<programlisting>typedef <classname>mpl::vector</classname>< std::string
> types_initial;
typedef <classname>mpl::push_front</classname>< types_initial, int
>::type types;
<classname>boost::make_variant_over</classname>< types >::type
v1;</programlisting>
- behaves equivalently to
+ behaves equivalently to<sbr/>
+ 等同于
<programlisting><classname>boost::variant</classname>< int, std::string
> v2;</programlisting>
@@ -88,17 +111,22 @@
<code>make_variant_over</code> is not universally available. On these
compilers the library indicates its lack of support for the syntax via
the
definition of the preprocessor symbol
-
<code><macroname>BOOST_VARIANT_NO_TYPE_SEQUENCE_SUPPORT</macroname></code>.</para>
+
<code><macroname>BOOST_VARIANT_NO_TYPE_SEQUENCE_SUPPORT</macroname></code>.<sbr/>
+ <emphasis role="bold">可移植性</emphasis>：不幸的是，由于某些编译器不完
全符合标准，
+ <code>make_variant_over</code> 并不是在哪都可以用。在这些编译器上，本库
以预处理器符号
+
<code><macroname>BOOST_VARIANT_NO_TYPE_SEQUENCE_SUPPORT</macroname></code>
的定义来表明编译器语法支持的不足。</para>
</section>
<section id="variant.tutorial.recursive">
- <title>Recursive <code>variant</code> types</title>
+ <title>Recursive <code>variant</code> types 递归的 <code>variant</code>
类型</title>
<para>Recursive types facilitate the construction of complex semantics
from
simple syntax. For instance, nearly every programmer is familiar with
the
canonical definition of a linked list implementation, whose simple
- definition allows sequences of unlimited length:
+ definition allows sequences of unlimited length:<sbr/>
+ 递归类型可以用简单的语法来实现复杂的语义结构。
+ 例如，几乎所有程序员都熟悉规范的链表定义，其简单的定义可以实现无限长度
的序列：
<programlisting>template <typename T>
struct list_node
@@ -112,7 +140,9 @@
<para>The nature of <code>variant</code> as a generic class template
unfortunately precludes the straightforward construction of recursive
<code>variant</code> types. Consider the following attempt to construct
- a structure for simple mathematical expressions:
+ a structure for simple mathematical expressions:<sbr/>
+ 由于 <code>variant</code> 本身是一个泛型的类模板，这样就排除了简单地构
造递归 <code>variant</code> 类型的可能。
+ 想象一下，以下要构造一个简单的数学表达式的结构：
<programlisting>struct add;
struct sub;
@@ -145,7 +175,10 @@
from a more significant logical flaw: even if C++ syntax were different
such that the above example could be made to "work,"
<code>expression</code> would need to be of infinite size, which is
- clearly impossible.</para>
+ clearly impossible.<sbr/>
+ 虽然是出于好意的，但以上方法并不能通过编译，因为
<code>binary_op</code> 在 <code>variant</code> 类型
+ <code>expression</code> 实例化时尚未是完整的。更进一步，该方法还有一个
更为重大的逻辑缺陷：
+ 即使C++语法可以让以上例子"通过"，<code>expression</code> 仍将
会具有无穷大的大小，这显然是不可能的。</para>
<para>To overcome these difficulties, <code>variant</code> includes
special
support for the
@@ -156,14 +189,20 @@
a more convenient syntax for declaring recursive <code>variant</code>
types. Tutorials for use of these facilities is described in
<xref linkend="variant.tutorial.recursive.recursive-wrapper"/> and
- <xref linkend="variant.tutorial.recursive.recursive-variant"/>.</para>
+ <xref linkend="variant.tutorial.recursive.recursive-variant"/>.<sbr/>
+ 为了克服这些困难，<code>variant</code> 含有对
<code><classname>boost::recursive_wrapper</classname></code>
+ 类模板的特殊支持，它可以打破作为问题核心的循环依赖。更进一步，
+ <code><classname>boost::make_recursive_variant</classname></code> 还提
供了一个更为方便的语法来声明递归
+ <code>variant</code> 类型。有关这两个工具的用法分别在 <xref
linkend="variant.tutorial.recursive.recursive-wrapper"/> 和
+ <xref linkend="variant.tutorial.recursive.recursive-variant"/> 中讲述。
</para>
<section id="variant.tutorial.recursive.recursive-wrapper">
- <title>Recursive types with <code>recursive_wrapper</code></title>
+ <title>Recursive types with <code>recursive_wrapper</code>
<code>recursive_wrapper</code>的递归类型</title>
<para>The following example demonstrates how
<code>recursive_wrapper</code>
could be used to solve the problem presented in
- <xref linkend="variant.tutorial.recursive"/>:
+ <xref linkend="variant.tutorial.recursive"/>:<sbr/>
+ 以下例子示范了如何用 <code>recursive_wrapper</code> 来解决在 <xref
linkend="variant.tutorial.recursive"/> 中所说的问题：
<programlisting>typedef <classname>boost::variant</classname><
int
@@ -178,7 +217,10 @@
<code>variant</code> as though the wrapper were not present. This is
seen
in the implementation of the following visitor, which calculates the
value
of an <code>expression</code> without any reference to
- <code>recursive_wrapper</code>:
+ <code>recursive_wrapper</code>:<sbr/>
+ 因为 <code>variant</code> 提供了对 <code>recursive_wrapper</code> 的特
殊支持，用户可以将得到的 <code>variant</code>
+ 视为没有 wrapper 的一样。这可以在以下访问者的实现中看到，该访问者计算一
个 <code>expression</code> 的值而无需引用
+ <code>recursive_wrapper</code>：
<programlisting>class calculator : public
<classname>boost::static_visitor<int></classname>
{
@@ -205,7 +247,8 @@
</para>
- <para>Finally, we can demonstrate <code>expression</code> in action:
+ <para>Finally, we can demonstrate <code>expression</code> in
action:<sbr/>
+ 最后，我们可以示范 <code>expression</code> 如何运作：
<programlisting>void f()
{
@@ -225,12 +268,14 @@
</section>
<section id="variant.tutorial.recursive.recursive-variant">
- <title>Recursive types with <code>make_recursive_variant</code></title>
+ <title>Recursive types with <code>make_recursive_variant</code>
<code>make_recursive_variant</code>的递归类型</title>
<para>For some applications of recursive <code>variant</code> types, a
user
may be able to sacrifice the full flexibility of using
<code>recursive_wrapper</code> with <code>variant</code> for the
following
- convenient syntax:
+ convenient syntax:<sbr/>
+ 在某些递归 <code>variant</code> 类型的应用中，用户也许可以为了以下简便
的语法而牺牲使用
+ <code>recursive_wrapper</code> 的灵活性：
<programlisting>typedef
<classname>boost::make_recursive_variant</classname><
int
@@ -239,7 +284,8 @@
</para>
- <para>Use of the resultant <code>variant</code> type is as expected:
+ <para>Use of the resultant <code>variant</code> type is as
expected:<sbr/>
+ 可以象你所想的那样使用得到的 <code>variant</code> 类型：
<programlisting>std::vector< int_tree_t > subresult;
subresult.push_back(3);
@@ -255,13 +301,17 @@
</para>
<para>To be clear, one might represent the resultant content of
- <code>var</code> as <code>( 1 ( 3 5 ) 7 )</code>.</para>
+ <code>var</code> as <code>( 1 ( 3 5 ) 7 )</code>.<sbr/>
+ 为清楚起见，你可以将得到的 <code>var</code> 表示为 <code>( 1 ( 3 5 ) 7
)</code>.</para>
<para>Finally, note that a type sequence can be used to specify the
bounded
types of a recursive <code>variant</code> via the use of
<code><classname>boost::make_recursive_variant_over</classname></code>,
whose semantics are the same as <code>make_variant_over</code> (which
is
- described in <xref linkend="variant.tutorial.over-sequence"/>).</para>
+ described in <xref linkend="variant.tutorial.over-sequence"/>).<sbr/>
+ 最后要注意的是，可以通过
<code><classname>boost::make_recursive_variant_over</classname></code>
+ 用一个类型序列来指定递归 <code>variant</code> 的有界类型，其语法类似于
make_variant_over
+ (在 <xref linkend="variant.tutorial.over-sequence"/> 中有说明)。</para>
<para><emphasis role="bold">Portability</emphasis>: Unfortunately, due to
standard conformance issues in several compilers,
@@ -272,25 +322,34 @@
Thus, unless working with highly-conformant compilers, maximum
portability
will be achieved by instead using <code>recursive_wrapper</code>, as
described in
- <xref linkend="variant.tutorial.recursive.recursive-wrapper"/>.</para>
+ <xref linkend="variant.tutorial.recursive.recursive-wrapper"/>.<sbr/>
+ <emphasis role="bold">可移植性</emphasis>：不幸的是，由于某些编译器不完
全符合标准，<code>make_recursive_variant</code>
+ 并不是在哪都可以用。在这些编译器上，本库以预处理器符号
+
<code><macroname>BOOST_VARIANT_NO_FULL_RECURSIVE_VARIANT_SUPPORT</macroname></code>
的定义来表明编译器语法支持的不足。
+ 因此，除非是使用高标准的编译器，否则使用
<code>recursive_wrapper</code> 可以得到最好的可移植性，就象在
+ <xref linkend="variant.tutorial.recursive.recursive-wrapper"/> 中所说的
那样。</para>
</section>
</section> <!--/tutorial.recursive-->
<section id="variant.tutorial.binary-visitation">
- <title>Binary visitation</title>
+ <title>Binary visitation 二元访问方式</title>
<para>As the tutorial above demonstrates, visitation is a powerful
mechanism
for manipulating <code>variant</code> content. Binary visitation
further
extends the power and flexibility of visitation by allowing
simultaneous
visitation of the content of two different <code>variant</code>
- objects.</para>
+ objects.<sbr/>
+ 就象前面的例子所展现的，访问方式是一种对 <code>variant</code> 的内容进
行操作的强大机制。
+ 二元访问方式进一步扩展了访问方式的能力和灵活性，它允许同时访问两个不同
<code>variant</code> 对象中的内容。</para>
<para>Notably this feature requires that binary visitors are incompatible
with the visitor objects discussed in the tutorial above, as they must
operate on two arguments. The following demonstrates the
implementation of
- a binary visitor:
+ a binary visitor:<sbr/>
+ 注意，这一特性要求二元访问者与前面所讨论的访问者对象是不兼容的，二元访
问者必须操作两个参数。
+ 以下例子示范了一个二元访问者的实现：
<programlisting>class are_strict_equals
: public <classname>boost::static_visitor</classname><bool>
@@ -314,7 +373,8 @@
</para>
<para>As expected, the visitor is applied to two <code>variant</code>
- arguments by means of <code>apply_visitor</code>:
+ arguments by means of <code>apply_visitor</code>:<sbr/>
+ 如你所想，这个访问者要通过 <code>apply_visitor</code> 应用于两个
<code>variant</code> 参数上：
<programlisting><classname>boost::variant</classname>< int, std::string
> v1( "hello" );
@@ -329,7 +389,9 @@
<para>Finally, we must note that the function object returned from the
"delayed" form of
<code><functionname>apply_visitor</functionname></code> also supports
- binary visitation, as the following demonstrates:
+ binary visitation, as the following demonstrates:<sbr/>
+ 最后，我们必须说明，由
<code><functionname>apply_visitor</functionname></code>
+ 的"延迟"形式所返回的函数对象也可以支持二元访问方式，如下所
示：
<programlisting>typedef <classname>boost::variant</classname><double,
std::string> my_variant;
=======================================
--- /trunk/libs/variant/doc/tutorial/basic.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/variant/doc/tutorial/basic.xml Mon Jul 19 23:54:43 2010
@@ -2,7 +2,7 @@
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
<section id="variant.tutorial.basic">
- <title>Basic Usage</title>
+ <title>Basic Usage 基本用法</title>
<using-namespace name="boost"/>
<using-class name="boost::variant"/>
@@ -15,10 +15,15 @@
<link
linkend="variant.concepts.bounded-type"><emphasis>BoundedType</emphasis></link>
concept. Any number of bounded types may be specified, up to some
implementation-defined limit (see
- <code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code>).</para>
+ <code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code>).<sbr/>
+ 定义一个由多个类型组成的可识别联合容器时，要以所需要的类型来实例化
<code><classname>boost::variant</classname></code> 类模板。
+ 这些类型被称为 <emphasis role="bold">有界类型</emphasis>，它们要遵循
<link linkend="variant.concepts.bounded-type"><emphasis>
+ BoundedType</emphasis></link> 概念的要求。可以指定任意数量的有界类型，数
量的限制是实现定义的(请见
+ <code><macroname>BOOST_VARIANT_LIMIT_TYPES</macroname></code>)。</para>
<para>For example, the following declares a discriminated union container
on
- <code>int</code> and <code>std::string</code>:
+ <code>int</code> and <code>std::string</code>:<sbr/>
+ 例如，以下声明了一个由 <code>int</code> 和 <code>std::string</code> 组成
的可识别联合容器：
<programlisting><classname>boost::variant</classname>< int, std::string
> v;</programlisting>
@@ -30,7 +35,11 @@
default-constructible, a <code>variant</code> can be constructed
directly from any value convertible to one of its bounded types.
Similarly,
a <code>variant</code> can be assigned any value convertible to one of
its
- bounded types, as demonstrated in the following:
+ bounded types, as demonstrated in the following:<sbr/>
+ 缺省地，一个 <code>variant</code> 会缺省构造其第一个有界类型，所以
<code>v</code> 开始会包含 <code>int(0)</code>.
+ 如果这不是你想要的，或者如果第一个有界类型不是可缺省构造
的，<code>variant</code>
+ 也可以直接从某个可以转换为其任意一个有界类型的值来构造。
+ 同样，一个 <code>variant</code> 可以被赋值为任意一个可转换为某个有界类型
的值，举例如下：
<programlisting>v = "hello";</programlisting>
@@ -39,7 +48,8 @@
<para>Now <code>v</code> contains a <code>std::string</code> equal to
<code>"hello"</code>. We can demonstrate this by
<emphasis role="bold">streaming</emphasis> <code>v</code> to
standard
- output:
+ output:<sbr/>
+ 现在 <code>v</code> 包含一个等于 <code>"hello"</code> 的
<code>std::string</code>. 我们可以示范将 <code>v</code> 输出到标准输出：
<programlisting>std::cout << v << std::endl;</programlisting>
@@ -51,12 +61,18 @@
<code><functionname>apply_visitor</functionname></code>, which is safest
and very powerful, and
<code><functionname>get</functionname><T></code>, which is
- sometimes more convenient to use.</para>
+ sometimes more convenient to use.<sbr/>
+ 通常，我们对 <code>variant</code> 的内容要做的不只是流的输入输出。
+ 因此，我们需要一些访问所含值的方法。有两种方法来实现这一点：
+ <code><functionname>apply_visitor</functionname></code>, 这是最安全和最强
大的；
+ 还有 <code><functionname>get</functionname><T></code>, 有时这更方便
使用。</para>
<para>For instance, suppose we wanted to concatenate to the string
contained
in <code>v</code>. With <emphasis role="bold">value retrieval</emphasis>
by <code><functionname>get</functionname></code>, this may be
accomplished
- quite simply, as seen in the following:
+ quite simply, as seen in the following:<sbr/>
+ 例如，假设我们想在 <code>v</code> 中的字符串后进行连接。通过
<code><functionname>get</functionname></code>
+ 的 <emphasis role="bold">值取出</emphasis>，可以很简单地完成如下：
<programlisting>std::string& str =
<functionname>boost::get</functionname><std::string>(v);
str += " world! ";</programlisting>
@@ -65,7 +81,9 @@
<para>As desired, the <code>std::string</code> contained by <code>v</code>
now
is equal to <code>"hello world! "</code>. Again, we can demonstrate this
by
- streaming <code>v</code> to standard output:
+ streaming <code>v</code> to standard output:<sbr/>
+ 如你所想，<code>v</code> 中所包含的 <code>std::string</code> 现在为
<code>"hello world! "</code>.
+ 我们可以再次将 <code>v</code> 输出到标准输出：
<programlisting>std::cout << v << std::endl;</programlisting>
@@ -79,7 +97,12 @@
<code>std::string</code>. If we insisted upon continued use of
<code>get</code>, we would need to query the <code>variant</code> for its
contained type. The following function, which "doubles" the
- content of the given <code>variant</code>, demonstrates this approach:
+ content of the given <code>variant</code>, demonstrates this
approach:<sbr/>
+ 虽然在这种简单的例子中，使用 <code>get</code> 完全可以接受，但是通常来说
<code>get</code> 有几个明显的缺点。
+ 例如，如果我们要写一个以 <code>variant<int, std::string></code> 为
参数的函数，我们就不知道传入的 <code>variant</code>
+ 究竟是包含了一个 <code>int</code> 抑或是一个 <code>std::string</code>.
+ 如果我们还是继续使用 <code>get</code> 的话，我们就需要向
<code>variant</code> 询问它所含的类型。
+ 以下函数用于将给定的 <code>variant</code> 的内容进行"翻倍"，就示范了这种
方法：
<programlisting>void times_two( boost::variant< int, std::string >
& operand )
{
@@ -97,7 +120,10 @@
<code>times_two</code> to operate on a <code>variant</code> with
additional
bounded types. Specifically, let's add
<code>std::complex<double></code> to the set. Clearly, we would
need
- to at least change the function declaration:
+ to at least change the function declaration:<sbr/>
+ 但是，这样的代码是非常脆弱的，如果不小心注意，很容易就会导致微妙的逻辑错
误，且只能在运行期检测到。
+ 例如，如果我们想将 <code>times_two</code> 扩展为用于一个增加了其它有界类
型的 <code>variant</code>.
+ 具体地，我们将 <code>std::complex<double></code> 增加到这个类型集
中。显然，我们至少需要修改函数的声明：
<programlisting>void times_two( boost::variant< int, std::string,
std::complex<double> > & operand )
{
@@ -111,7 +137,10 @@
<code>times_two</code> would silently return -- without any of the
desired
side-effects and without any error. In this case, the fix is obvious.
But in
more complicated programs, it could take considerable time to identify
and
- locate the error in the first place.</para>
+ locate the error in the first place.<sbr/>
+ 当然，还需要更多的修改，现在如果传入的 <code>variant</code> 实际上含有一
个 <code>std::complex</code> 值，
+ <code>times_two</code> 就将静静地返回 -- 没做任何动作也没有任何错误。这种
情况下，要做的修正是显而易见的。
+ 不过，在更复杂的程序中，就可能需要很长时间来识别和定位这个错误。</para>
<para>Thus, real-world use of <code>variant</code> typically demands an
access
mechanism more robust than <code>get</code>. For this reason,
@@ -119,11 +148,16 @@
<emphasis role="bold">visitation</emphasis> via
<code><functionname>apply_visitor</functionname></code>. Visitation
requires
that the programmer explicitly handle (or ignore) each bounded type.
Failure
- to do so results in a compile-time error.</para>
+ to do so results in a compile-time error.<sbr/>
+ 因此，在真实世界中 <code>variant</code> 的使用需要一个比
<code>get</code> 更健壮的访问机制。
+ 由于这个原因，<code>variant</code> 通过
<code><functionname>apply_visitor</functionname></code>
+ 提供带编译期检验的 <emphasis role="bold">访问方式</emphasis>。
+ 这种访问方式要求程序员显式处理(或忽略)每一个有界类型。不这样做将导致编译
期错误。</para>
<para>Visitation of a <code>variant</code> requires a visitor object. The
following demonstrates one such implementation of a visitor
implementating
- behavior identical to <code>times_two</code>:
+ behavior identical to <code>times_two</code>:<sbr/>
+ 访问一个 <code>variant</code> 需要一个访问者对象。下面示范了如何以访问者
的方式来实现与 <code>times_two</code> 一样的功能：
<programlisting>class times_two_visitor
: public <classname>boost::static_visitor</classname><>
@@ -145,7 +179,8 @@
</para>
<para>With the implementation of the above visitor, we can then apply it to
- <code>v</code>, as seen in the following:
+ <code>v</code>, as seen in the following:<sbr/>
+ 有了以上这样的访问者，我们就可以将它应用于 <code>v</code>, 如下所示：
<programlisting><functionname>boost::apply_visitor</functionname>(
times_two_visitor(), v );</programlisting>
@@ -153,13 +188,18 @@
<para>As expected, the content of <code>v</code> is now a
<code>std::string</code> equal to <code>"hello world! hello
world! "</code>.
- (We'll skip the verification this time.)</para>
+ (We'll skip the verification this time.)<sbr/>
+ 正象我们所期待的那样，现在 <code>v</code> 的内容将是一个等于
<code>"hello world! hello world! "</code> 的
+ <code>std::string</code>. (这次我们跳过了结果验证)。</para>
<para>In addition to enhanced robustness, visitation provides another
important advantage over <code>get</code>: the ability to write generic
visitors. For instance, the following visitor will "double" the
content of <emphasis>any</emphasis> <code>variant</code> (provided
its
- bounded types each support operator+=):
+ bounded types each support operator+=):<sbr/>
+ 除了健壮性的加强，访问方式还提供了另一个比 <code>get</code> 好的重要优
势：可以编写泛型的访问者。
+ 例如，以下访问者将对<emphasis>任意</emphasis> <code>variant</code>
+ (只要它的每一个有界类型都支持 operator+=)的内容进行"加倍"：
<programlisting>class times_two_generic
: public <classname>boost::static_visitor</classname><>
@@ -176,7 +216,8 @@
</para>
-<para>Again, <code>apply_visitor</code> sets the wheels in motion:
+<para>Again, <code>apply_visitor</code> sets the wheels in motion:<sbr/>
+同样，<code>apply_visitor</code> 让轮子转动起来：
<programlisting><functionname>boost::apply_visitor</functionname>(
times_two_generic(), v );</programlisting>
@@ -191,7 +232,12 @@
the given visitor to any <code>variant</code> but rather returns a
function
object that operates on any <code>variant</code> given to it. This
behavior
is particularly useful when operating on sequences of
<code>variant</code>
- type, as the following demonstrates:
+ type, as the following demonstrates:<sbr/>
+ 虽然访问方式的初始化设置花费了比 <code>get</code> 更多的开销，但是它的好
处也非常明显。
+ 在结束本节之前，我们再看一下 <code>apply_visitor</code> 的最后一个优
点：<emphasis role="bold">延迟访问</emphasis>。
+ 即有一个特殊形式的 <code>apply_visitor</code>，它不是立即将给定的访问者应
用于 <code>variant</code>，
+ 而是返回一个函数对象，该函数对象可以操作于任意给定的
<code>variant</code>.
+ 这种行为在需要对一个 <code>variant</code> 类型的序列进行操作时非常有
用，举例如下：
<programlisting>std::vector<
<classname>boost::variant</classname><int, std::string> > vec;
vec.push_back( 21 );
=======================================
--- /trunk/libs/variant/doc/tutorial/tutorial.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/variant/doc/tutorial/tutorial.xml Mon Jul 19 23:54:43 2010
@@ -3,7 +3,7 @@
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
<section xmlns:xi="http://www.w3.org/2001/XInclude"; id="variant.tutorial">
-<title>Tutorial</title>
+<title>Tutorial 指南</title>
<xi:include href="basic.xml"/>
<xi:include href="advanced.xml"/>
Other related posts:
- » [boost-doc-zh] r421 committed - 翻译 variant 库的 qbk/xml 文件 - boost-doc-zh
