Subject: [Boost-commit] svn:boost r60788 - trunk/libs/proto/doc
From: eric_at_[hidden]
Date: 2010-03-23 01:07:40
Author: eric_niebler
Date: 2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
New Revision: 60788
URL: http://svn.boost.org/trac/boost/changeset/60788
Log:
add an appendix for release notes
Added:
trunk/libs/proto/doc/release_notes.qbk (contents, props changed)
Text files modified:
trunk/libs/proto/doc/acknowledgements.qbk | 2 +-
trunk/libs/proto/doc/history.qbk | 2 +-
trunk/libs/proto/doc/implementation.qbk | 2 +-
trunk/libs/proto/doc/proto.qbk | 2 ++
trunk/libs/proto/doc/rationale.qbk | 2 +-
5 files changed, 6 insertions(+), 4 deletions(-)
Modified: trunk/libs/proto/doc/acknowledgements.qbk
==============================================================================
--- trunk/libs/proto/doc/acknowledgements.qbk (original)
+++ trunk/libs/proto/doc/acknowledgements.qbk 2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
@@ -5,7 +5,7 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:acknowledgements Appendix D: Acknowledgements]
+[section:acknowledgements Appendix E: Acknowledgements]
I'd like to thank Joel de Guzman and Hartmut Kaiser for being willing to take a
chance on using Proto for their work on Spirit-2 and Karma when Proto was
Modified: trunk/libs/proto/doc/history.qbk
==============================================================================
--- trunk/libs/proto/doc/history.qbk (original)
+++ trunk/libs/proto/doc/history.qbk 2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
@@ -5,7 +5,7 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:history Appendix A: History]
+[section:history Appendix B: History]
[variablelist
[
Modified: trunk/libs/proto/doc/implementation.qbk
==============================================================================
--- trunk/libs/proto/doc/implementation.qbk (original)
+++ trunk/libs/proto/doc/implementation.qbk 2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
@@ -5,7 +5,7 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:implementation Appendix C: Implementation Notes]
+[section:implementation Appendix D: Implementation Notes]
[section:sfinae Quick-n-Dirty Type Categorization]
Modified: trunk/libs/proto/doc/proto.qbk
==============================================================================
--- trunk/libs/proto/doc/proto.qbk (original)
+++ trunk/libs/proto/doc/proto.qbk 2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
@@ -279,6 +279,8 @@
[section Appendices]
[/=================]
+[include release_notes.qbk]
+
[include history.qbk]
[include rationale.qbk]
Modified: trunk/libs/proto/doc/rationale.qbk
==============================================================================
--- trunk/libs/proto/doc/rationale.qbk (original)
+++ trunk/libs/proto/doc/rationale.qbk 2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
@@ -5,7 +5,7 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:rationale Appendix B: Rationale]
+[section:rationale Appendix C: Rationale]
[/==================================================]
[section:static_initialization Static Initialization]
Added: trunk/libs/proto/doc/release_notes.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/proto/doc/release_notes.qbk 2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
@@ -0,0 +1,76 @@
+[/
+ / Copyright (c) 2008 Eric Niebler
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:release_notes Appendix A: Release Notes]
+
+[/=================]
+[heading Boost 1.43]
+[/=================]
+
+In Boost 1.43, the recommended usage of _extends_ changed slightly. The new
+usage looks like this:
+
+ // my_expr is an expression extension of the Expr parameter
+ template<typename Expr>
+ struct my_expr
+ : proto::extends<Expr, my_expr<Expr>, my_domain>
+ {
+ my_expr(Expr const &expr = Expr())
+ : proto::extends<Expr, my_expr, my_domain>(expr)
+ {}
+
+ // NEW: use the following macro to bring
+ // proto::extends::operator= into scope.
+ BOOST_PROTO_EXTENDS_USING_ASSIGN(my_expr)
+ };
+
+The new thing is the use of the [^[macroref BOOST_PROTO_EXTENDS_USING_ASSIGN]()] macro.
+To allow assignment operators to build expression trees, _extends_ overloads the
+assignment operator. However, for the `my_expr` template, the compiler generates
+a default copy assignment operator that hides the ones in _extends_. This is often
+not desired (although it depends on the syntax you want to allow).
+
+Previously, the recommended usage was to do this:
+
+ // my_expr is an expression extension of the Expr parameter
+ template<typename Expr>
+ struct my_expr
+ : proto::extends<Expr, my_expr<Expr>, my_domain>
+ {
+ my_expr(Expr const &expr = Expr())
+ : proto::extends<Expr, my_expr, my_domain>(expr)
+ {}
+
+ // OLD: don't do it like this anymore.
+ using proto::extends<Expr, my_expr, my_domain>::operator=;
+ };
+
+While this works in the majority of cases, it still doesn't suppress the
+implicit generation of the default assignment operator. As a result, expressions
+of the form `a = b` could either build an expression template or do a copy
+assignment depending on whether the types of `a` and `b` happen to be the
+same. That can lead to subtle bugs, so the behavior was changed.
+
+The [^[macroref BOOST_PROTO_EXTENDS_USING_ASSIGN]()] brings into scope the
+assignment operators defined in _extends_ as well as suppresses the generation
+of the copy assignment operator.
+
+Also note that the _literal_ class template, which uses _extends_, has been chaged
+to use [^[macroref BOOST_PROTO_EXTENDS_USING_ASSIGN]()]. The implications are
+highlighted in the sample code below:
+
+ proto::literal<int> a(1), b(2); // two non-const proto literals
+ proto::literal<int> const c(3); // a const proto literal
+
+ a = b; // No-op. Builds an expression tree and discards it.
+ // Same behavior in 1.42 and 1.43.
+
+ a = c; // CHANGE! In 1.42, this performed copy assignment, causing
+ // a's value to change to 3. In 1.43, the behavior is now
+ // the same as above: build and discard an expression tree.
+
+[endsect]