[Boost-commit] svn:boost r80828 - trunk/libs/foreach/doc

Subject: [Boost-commit] svn:boost r80828 - trunk/libs/foreach/doc
From: eric_at_[hidden]
Date: 2012-10-03 14:45:41

Author: eric_niebler
Date: 2012-10-03 14:45:40 EDT (Wed, 03 Oct 2012)
New Revision: 80828
URL: http://svn.boost.org/trac/boost/changeset/80828

Log:
foreach: describe perils of #define-ing foreach to BOOST_FOREACH
Text files modified: 
   trunk/libs/foreach/doc/foreach.qbk |    27 +++++++++++++++++++++++----             
   1 files changed, 23 insertions(+), 4 deletions(-)

Modified: trunk/libs/foreach/doc/foreach.qbk
==============================================================================
--- trunk/libs/foreach/doc/foreach.qbk	(original)
+++ trunk/libs/foreach/doc/foreach.qbk	2012-10-03 14:45:40 EDT (Wed, 03 Oct 2012)
@@ -180,19 +180,38 @@
 get tiresome to look at. That may be true, but _foreach_ is merely following
 the [@http://www.boost.org/more/lib_guide.htm Boost Naming Convention]. That
 doesn't mean you're stuck with it, though. If you would like to use a different
-identifier (`foreach`, perhaps), you can simply do:
+identifier (`foreach_`, perhaps), you can simply do:
 
-    #define foreach         BOOST_FOREACH
-    #define reverse_foreach BOOST_REVERSE_FOREACH
+    #define foreach_         BOOST_FOREACH
+    #define foreach_r_       BOOST_REVERSE_FOREACH
 
 Only do this if you are sure that the identifier you choose will not cause
 name conflicts in your code.
 
-[note Do not use `#define foreach(x,y) BOOST_FOREACH(x,y)`.
+[note Do not use `#define foreach_(x,y) BOOST_FOREACH(x,y)`.
  This can be problematic if the arguments are macros themselves. This would
  result in an additional expansion of these macros. Instead, use the 
  form shown above.]
 
+Lasstly, a word of warning. Lots of folks use a `foreach` macro as a short form
+for `BOOST_FOREACH`. I discourage this. It leads to name conflicts within the
+`BOOST_FOREACH` macro itself, where `foreach` is the name of a namespace. Besides,
+`foreach` is a common-eough identifier; even [@http://qt.digia.com/ Qt] defines
+it as a macro. If you insist on using `foreach`, you might try something like this:
+
+    #include <boost/foreach.hpp>
+    
+    namespace boost
+    {
+        // Suggested work-around for https://svn.boost.org/trac/boost/ticket/6131
+        namespace BOOST_FOREACH = foreach;
+    }
+    
+    #define foreach   BOOST_FOREACH
+
+This will work around /some/ of the problem you're likely to encounter, but not all.
+Prefer using a different identifier.
+
 [endsect]
 
 [section Extensibility]