[Boost-commit] svn:boost r80604 - sandbox/type_erasure/libs/type_erasure/example

Subject: [Boost-commit] svn:boost r80604 - sandbox/type_erasure/libs/type_erasure/example
From: steven_at_[hidden]
Date: 2012-09-19 18:52:25

Author: steven_watanabe
Date: 2012-09-19 18:52:25 EDT (Wed, 19 Sep 2012)
New Revision: 80604
URL: http://svn.boost.org/trac/boost/changeset/80604

Log:
More description of the print_sequence example.
Text files modified: 
   sandbox/type_erasure/libs/type_erasure/example/print_sequence.cpp |    42 +++++++++++++++++++++++++++++++++++++-- 
   1 files changed, 39 insertions(+), 3 deletions(-)

Modified: sandbox/type_erasure/libs/type_erasure/example/print_sequence.cpp
==============================================================================
--- sandbox/type_erasure/libs/type_erasure/example/print_sequence.cpp	(original)
+++ sandbox/type_erasure/libs/type_erasure/example/print_sequence.cpp	2012-09-19 18:52:25 EDT (Wed, 19 Sep 2012)
@@ -14,8 +14,24 @@
     (For the source of this example see
     [@boost:/libs/type_erasure/example/print_sequence.cpp print_sequence.cpp])
 
-    This example demonstrates using Boost.TypeErasure to implement a
-    virtual "template" function.
+    This example defines a class hierarchy that allows a sequence
+    to be formatted in several different ways.  We'd like to be
+    able to handle any sequence and any stream type, since the
+    range formatting is independent of the formatting of
+    individual elements.  Thus, our interface needs to look
+    something like this:
+
+    ``
+        class abstract_printer {
+        public:
+            template<class CharT, class Traits, class Range>
+            virtual void print(std::basic_ostream<CharT, Traits>& os, const Range& r) const = 0;
+        };
+    ``
+
+    Unfortunately, this is illegal because a virtual function
+    cannot be a template.  However, we can define a
+    class with much the same behavior using Boost.TypeErasure.
 */
 
 #include <boost/type_erasure/any.hpp>
@@ -61,9 +77,14 @@
 }
 }
 
+// abstract_printer - An abstract base class for formatting sequences.
 class abstract_printer {
 public:
-    // Range must be a Forward Range whose elements can be printed to os.
+    // print - write a sequence to a std::ostream in a manner
+    //   specific to the derived class.
+    //
+    // Requires: Range must be a Forward Range whose elements can be
+    //   printed to os.
     template<class CharT, class Traits, class Range>
     void print(std::basic_ostream<CharT, Traits>& os, const Range& r) const {
         // Capture the arguments
@@ -76,6 +97,8 @@
     }
     virtual ~abstract_printer() {}
 protected:
+    // define the concept requirements of the arguments of
+    // print and typedef the any types.
     typedef boost::mpl::vector<
         base_and_derived<std::ios_base, _os>,
         ostreamable<_os, _t>,
@@ -85,10 +108,15 @@
     > requirements;
     typedef boost::type_erasure::any<requirements, _os&> ostream_type;
     typedef boost::type_erasure::any<requirements, _iter> iterator_type;
+    // do_print - This method must be implemented by derived classes
     virtual void do_print(
         ostream_type os, iterator_type first, iterator_type last) const = 0;
 };
 
+// separator_printer - writes the elements of a sequence
+//   separated by a fixed string.  For example, if
+//   the separator is ", " separator_printer produces
+//   a comma separated list.
 class separator_printer : public abstract_printer {
 public:
     explicit separator_printer(const std::string& sep) : separator(sep) {}
@@ -107,6 +135,8 @@
     std::string separator;
 };
 
+// column_separator_printer - like separator_printer, but
+//   also inserts a line break after every n elements.
 class column_separator_printer : public abstract_printer {
 public:
     column_separator_printer(const std::string& sep, std::size_t num_columns)
@@ -134,6 +164,12 @@
     std::size_t cols;
 };
 
+// aligned_column_printer - formats a sequence in columns
+//   reading down.  For example, given the sequence
+//   { 1, 2, 3, 4, 5 }, aligned_column_printer might print
+//   1   4
+//   2   5
+//   3
 class aligned_column_printer : public abstract_printer {
 public:
     aligned_column_printer(std::size_t column_width, std::size_t num_columns)