Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r56260 - in sandbox/explore: boost boost/explore libs/explore/doc libs/explore/doc/html libs/explore/doc/html/boost_explore libs/explore/doc/html/boost_explore/tutorial libs/explore/test
From: jmcintyre_at_[hidden]
Date: 2009-09-17 01:31:28

Author: jared
Date: 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
New Revision: 56260
URL: http://svn.boost.org/trac/boost/changeset/56260

Log:
Explore - revise documentation and aff c_array.hpp

Added:
   sandbox/explore/boost/explore/c_array.hpp (contents, props changed)
   sandbox/explore/libs/explore/doc/html/boost_explore/tutorial/type_specific_formatting.html (contents, props changed)
   sandbox/explore/libs/explore/doc/type_specific_formatting.qbk (contents, props changed)
Text files modified:
   sandbox/explore/boost/explore.hpp | 2
   sandbox/explore/boost/explore/stream_container.hpp | 4
   sandbox/explore/libs/explore/doc/custom_containers.qbk | 60 ++++++++++-------------------
   sandbox/explore/libs/explore/doc/custom_delimeters.qbk | 6 +-
   sandbox/explore/libs/explore/doc/explore.qbk | 4
   sandbox/explore/libs/explore/doc/html/boost_explore/dependencies_platforms.html | 10 ++--
   sandbox/explore/libs/explore/doc/html/boost_explore/design.html | 2
   sandbox/explore/libs/explore/doc/html/boost_explore/tutorial.html | 32 ++++++++++----
   sandbox/explore/libs/explore/doc/html/boost_explore/tutorial/custom_containers.html | 81 ++++++++++++++-------------------------
   sandbox/explore/libs/explore/doc/html/boost_explore/tutorial/custom_delimeters.html | 20 ++++----
   sandbox/explore/libs/explore/doc/html/index.html | 12 +++--
   sandbox/explore/libs/explore/doc/tutorial.qbk | 30 ++++++++++----
   sandbox/explore/libs/explore/test/c_array.cpp | 3
   13 files changed, 125 insertions(+), 141 deletions(-)

Modified: sandbox/explore/boost/explore.hpp
==============================================================================
--- sandbox/explore/boost/explore.hpp (original)
+++ sandbox/explore/boost/explore.hpp 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -8,9 +8,7 @@
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
//

-#include <boost/explore/stream_container.hpp>
#include <boost/explore/iterator_range.hpp>
-
#include <boost/explore/vector.hpp>
#include <boost/explore/list.hpp>
#include <boost/explore/deque.hpp>

Added: sandbox/explore/boost/explore/c_array.hpp
==============================================================================
--- (empty file)
+++ sandbox/explore/boost/explore/c_array.hpp 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -0,0 +1,16 @@
+//
+// c_array.hpp - container streaming.
+//
+// Copyright (C) 2007, Jeffrey Faust
+// Copyright (C) 2009, Jared McIntyre
+//
+// 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)
+//
+
+#ifndef BOOST_EXPLORE_C_ARRAY_H
+#define BOOST_EXPLORE_C_ARRAY_H
+
+#include <boost/explore/stream_container.hpp>
+
+#endif
\ No newline at end of file

Modified: sandbox/explore/boost/explore/stream_container.hpp
==============================================================================
--- sandbox/explore/boost/explore/stream_container.hpp (original)
+++ sandbox/explore/boost/explore/stream_container.hpp 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -68,13 +68,13 @@
 template<typename Elem, typename Tr, typename T, std::size_t size>
 std::basic_ostream<Elem, Tr>& operator<<(std::basic_ostream<Elem, Tr>& ostr, T (&a)[size])
 {
- return stream_container(ostr, &a[0], &a[size]);
+ return boost::explore::stream_container(ostr, &a[0], &a[size]);
 }

 template<typename Elem, typename Tr, std::size_t size>
 std::basic_ostream<Elem, Tr>& operator<<(std::basic_ostream<Elem, Tr>& ostr, const Elem* s)
 {
- return stream_container(ostr, &s[0], &s[strlen(s)]);
+ return boost::explore::stream_container(ostr, &s[0], &s[strlen(s)]);
 }
# endif
}}

Modified: sandbox/explore/libs/explore/doc/custom_containers.qbk
==============================================================================
--- sandbox/explore/libs/explore/doc/custom_containers.qbk (original)
+++ sandbox/explore/libs/explore/doc/custom_containers.qbk 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -9,6 +9,8 @@

You can use explore with your custom containers, or third party containers. However, explore needs a little help in understanding these classes.

+[heading Standard Container]
+
The following is a very simple class that contains a 1, 2, and 3 along with the begin and end functions to access the iterators for the container.

 class user_vector
@@ -21,17 +23,26 @@
 m_vec.push_back(3);
 }

- friend std::ostream& operator<<(std::ostream& ostr, const user_vector& u);
-
+ std::vector<int>::iterator begin()
+ {
+ return m_vec.begin();
+ }
+
+ std::vector<int>::iterator end()
+ {
+ return m_vec.end();
+ }
+
 private:
 std::vector<int> m_vec;
 };

To allow the user_vector to stream properly, you must create an operator<< overload that for the user_vector class that wrapps a call to the explore::stream_container helper function. The stream_container helper iterates through a range outputting the proper delimeters along with the values in the range. So, the operator<< passes into stream_container the result of the begin and end functions, and allows stream_container to process the contents for it.

- std::ostream& operator<<(std::ostream& ostr, const user_vector& u)
+ template<typename Elem, typename Tr>
+ std::basic_ostream<Elem, Tr>& operator<<(std::basic_ostream<Elem, Tr>& ostr, const user_vector& u)
 {
- return explore::stream_container(ostr, u.m_vec.begin(), u.m_vec.end());
+ return explore::stream_container(ostr, u.begin(), u.end());
 }

With our new overloaded operator<<, the following code
@@ -43,44 +54,15 @@

 [1, 2, 3]

+[heading Associative Container]
+
If the container had been an associative container of pairs, then the operator<< code would have looked like this:

- std::ostream& operator<<(std::ostream& ostr, const user_vector& u)
+ template<typename Elem, typename Tr>
+ std::basic_ostream<Elem, Tr>& operator<<(std::basic_ostream<Elem, Tr>& ostr, const user_vector& u)
 {
 return explore::stream_container(ostr, u.begin(), u.end(), explore::stream_associative_value());
 }
-
-If the custom container has a stream operator that defines manipulators that should always be in effect for that container, then it becomes necessary to use the custom() manipulator. For example:
-
- ostream& operator<<(ostream& ostr, const user_vector& u)
- {
- return ostr << explore::custom() << explore::delimiters("/", "::", "/") << u.m_vec.m_data;
- }
-
-The desire here is to use the delimiters "/" for begin/end and "::" for the separator, independent of what depth the container is streamed at. The "custom" manipulator allows this to work. If this is not specified, you will receive a debug assertion. With this new overload, the code:
-
- user_vector v;
- std::cout << v;
-
-prints
-
- /1::2::3/
-
-But more interestingly:
-
- std::vector<user_vector> v;
- v.push_back(user_vector());
- v.push_back(user_vector());
-
- std::cout << explore::delimiters("{\n ", "\n ", "\n}") << v;
-
-prints
-
- {
- /1::2::3/
- /1::2::3/
- }
-
-So the same delimiters are always used for the custom container, even when that container is nested in another.
-
+
+The critical difference is the addition of the third parameter `explore::stream_associative_value()`.
[endsect]

Modified: sandbox/explore/libs/explore/doc/custom_delimeters.qbk
==============================================================================
--- sandbox/explore/libs/explore/doc/custom_delimeters.qbk (original)
+++ sandbox/explore/libs/explore/doc/custom_delimeters.qbk 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -60,11 +60,11 @@
 {
 using namespace explore;

- // level 0
+ ostr << level(0);
 ostr << start("") << explore::end("") << separator("\n");

- // level 1
- ostr << start("|", 1) << explore::end("|", 1) << separator(" ", 1);
+ ostr << level(1);
+ ostr << start("|") << explore::end("|") << separator(" ");

 return ostr;
 }

Modified: sandbox/explore/libs/explore/doc/explore.qbk
==============================================================================
--- sandbox/explore/libs/explore/doc/explore.qbk (original)
+++ sandbox/explore/libs/explore/doc/explore.qbk 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -48,7 +48,7 @@
 std::vector<std::vector<int> > vvi;
 vvi.push_back(vi);
 vvi.push_back(vi);
- std::cout << vvi; // prints [[1, 2, 3], [1, 2, 3]]
+ std::cout << vvi; // prints [[1, 2, 3], [1, 2, 3]]

 // associative containers
 std::map<std::string, int> si_map;
@@ -72,7 +72,7 @@

While explore is powerful and flexible, it is not infinitely flexible.
The reasons for this are discussed in the [link boost_explore.design design]
-section.For very complex output custom methods or a template output system should
+section. For very complex output custom methods or a template output system should
be considered.

[heading Supported Containers]

Modified: sandbox/explore/libs/explore/doc/html/boost_explore/dependencies_platforms.html
==============================================================================
--- sandbox/explore/libs/explore/doc/html/boost_explore/dependencies_platforms.html (original)
+++ sandbox/explore/libs/explore/doc/html/boost_explore/dependencies_platforms.html 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -6,7 +6,7 @@
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="../index.html" title="Boost.explore">
<link rel="up" href="../index.html" title="Boost.explore">
-<link rel="prev" href="tutorial/custom_containers.html" title="Custom Containers">
+<link rel="prev" href="tutorial/type_specific_formatting.html" title="Type Specific Formatting">
<link rel="next" href="design.html" title="Design Notes">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="tutorial/custom_containers.html"><img src="../../../../../doc/html/images/%20prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/%20up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/%20home.png" alt="Home"></a><a accesskey="n" href="design.html"><img src="../../../../../doc/html/images/%20next.png" alt="Next"></a>
+<a accesskey="p" href="tutorial/type_specific_formatting.html"><img src="../../../../../doc/html/images/%20prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/%20up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/%20home.png" alt="Home"></a><a accesskey="n" href="design.html"><img src="../../../../../doc/html/images/%20next.png" alt="Next"></a>
</div>
<div class="section" title="Dependencies and Platforms">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -28,7 +28,7 @@
 Platforms</a>
</h2></div></div></div>
<a name="boost_explore.dependencies_platforms.dependencies"></a><h3>
-<a name="id558213"></a>
+<a name="id558604"></a>
 <a class="link" href="dependencies_platforms.html#boost_explore.dependencies_platforms.dependencies">Dependencies</a>
 </h3>

@@ -52,7 +52,7 @@
 </li>
</ul></div>
<a name="boost_explore.dependencies_platforms.supported_platforms"></a><h3>
-<a name="id558260"></a>
+<a name="id558651"></a>
 <a class="link" href="dependencies_platforms.html#boost_explore.dependencies_platforms.supported_platforms">Supported
 Platforms</a>
 </h3>
@@ -74,7 +74,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="tutorial/custom_containers.html"><img src="../../../../../doc/html/images/%20prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/%20up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/%20home.png" alt="Home"></a><a accesskey="n" href="design.html"><img src="../../../../../doc/html/images/%20next.png" alt="Next"></a>
+<a accesskey="p" href="tutorial/type_specific_formatting.html"><img src="../../../../../doc/html/images/%20prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/%20up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/%20home.png" alt="Home"></a><a accesskey="n" href="design.html"><img src="../../../../../doc/html/images/%20next.png" alt="Next"></a>
</div>
</body>
</html>

Modified: sandbox/explore/libs/explore/doc/html/boost_explore/design.html
==============================================================================
--- sandbox/explore/libs/explore/doc/html/boost_explore/design.html (original)
+++ sandbox/explore/libs/explore/doc/html/boost_explore/design.html 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -26,7 +26,7 @@
<a name="boost_explore.design"></a><a class="link" href="design.html" title="Design Notes"> Design Notes</a>
</h2></div></div></div>
<a name="boost_explore.design.rationale"></a><h3>
-<a name="id558416"></a>
+<a name="id558807"></a>
<a class="link" href="design.html#boost_explore.design.rationale">Rationale</a>
</h3>

Modified: sandbox/explore/libs/explore/doc/html/boost_explore/tutorial.html
==============================================================================
--- sandbox/explore/libs/explore/doc/html/boost_explore/tutorial.html (original)
+++ sandbox/explore/libs/explore/doc/html/boost_explore/tutorial.html 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -31,6 +31,8 @@
<dl>
<dt> Custom Delimiters</dt>
<dt> Custom Containers</dt>
+<dt><a href="tutorial/type_specific_formatting.html"> Type
+ Specific Formatting</a></dt>
</dl>
</div>
<a name="boost_explore.tutorial.basic_container_printing"></a><h4>
@@ -44,14 +46,22 @@
<pre class="programlisting">#include <boost/explore.hpp>
using namespace boost::explore;
</pre>
+
+ However, this will pull in definitions of all the containers that Explore supports.
+ To include only the definitions required for a specific container include each
+ type's header file instead of <code class="computeroutput">"explore.hpp"</code>.
+ 
+<pre class="programlisting">#include <boost/explore/vector.hpp>
+#include <boost/explore/boost_array.hpp>
+</pre>
<a name="boost_explore.tutorial.printing_of_contained_items"></a><h4>
-<a name="id554053"></a>
+<a name="id554157"></a>
 <a class="link" href="tutorial.html#boost_explore.tutorial.printing_of_contained_items">Printing
 of Contained Items</a>
 </h4>

- Basic printing of containers requires the inclusing of explore.hpp. Once included,
- containers can be be streamed in a formated manner.
+ Once you have included the proper header files, containers can be be streamed
+ in a formated manner.
 
<pre class="programlisting">std::vector<int> vi;
vi.push_back(1);
@@ -85,13 +95,15 @@
<pre class="programlisting">[[1, 2, 3], [1, 2, 3]]
</pre>
<a name="boost_explore.tutorial.c_style_arrays"></a><h4>
-<a name="id554477"></a>
+<a name="id554580"></a>
 <a class="link" href="tutorial.html#boost_explore.tutorial.c_style_arrays">C Style Arrays</a>
 </h4>

 C style arrays have a standard streaming format, however, when you include
- explore.hpp, you override this default streaming format with the explore streaming
- format and all the abilities of it.
+ any explore header, including <code class="computeroutput">"explore.hpp"</code>
+ and <code class="computeroutput">"boost/explore/c_array.hpp"</code>,
+ you override this default streaming format with the explore streaming format
+ and all the abilities of it.
 
<pre class="programlisting">int arr[3] = {1,2,3};
std::cout << arr;
@@ -102,7 +114,7 @@
<pre class="programlisting">[1, 2, 3]
</pre>
<a name="boost_explore.tutorial.associative_containers"></a><h4>
-<a name="id554627"></a>
+<a name="id554746"></a>
 <a class="link" href="tutorial.html#boost_explore.tutorial.associative_containers">Associative Containers</a>
 </h4>

@@ -143,7 +155,7 @@
 can be handled as associative containers.
 
<a name="boost_explore.tutorial.lexical_cast"></a><h4>
-<a name="id555048"></a>
+<a name="id555167"></a>
 <a class="link" href="tutorial.html#boost_explore.tutorial.lexical_cast">lexical_cast</a>
 </h4>

@@ -155,10 +167,10 @@
vi.push_back(1);
vi.push_back(2);
vi.push_back(3);
-std::string outVal( boost::lexical_cast<std::string>(vi) );
+std::cout << boost::lexical_cast<std::string>(vi);
</pre>

- outVal equals
+ prints
 
<pre class="programlisting">[1, 2, 3]
</pre>

Modified: sandbox/explore/libs/explore/doc/html/boost_explore/tutorial/custom_containers.html
==============================================================================
--- sandbox/explore/libs/explore/doc/html/boost_explore/tutorial/custom_containers.html (original)
+++ sandbox/explore/libs/explore/doc/html/boost_explore/tutorial/custom_containers.html 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -7,7 +7,7 @@
<link rel="home" href="../../index.html" title="Boost.explore">
<link rel="up" href="../tutorial.html" title="Tutorial">
<link rel="prev" href="custom_delimeters.html" title="Custom Delimiters">
-<link rel="next" href="../dependencies_platforms.html" title="Dependencies and Platforms">
+<link rel="next" href="type_specific_formatting.html" title="Type Specific Formatting">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="custom_delimeters.html"><img src="../../../../../../doc/html/images/%20prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/%20up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/%20home.png" alt="Home"></a><a accesskey="n" href="../dependencies_platforms.html"><img src="../../../../../../doc/html/images/%20next.png" alt="Next"></a>
+<a accesskey="p" href="custom_delimeters.html"><img src="../../../../../../doc/html/images/%20prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/%20up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/%20home.png" alt="Home"></a><a accesskey="n" href="type_specific_formatting.html"><img src="../../../../../../doc/html/images/%20next.png" alt="Next"></a>
</div>
<div class="section" title="Custom Containers">
<div class="titlepage"><div><div><h3 class="title">
@@ -30,6 +30,11 @@
 You can use explore with your custom containers, or third party containers.
 However, explore needs a little help in understanding these classes.
 
+<a name="boost_explore.tutorial.custom_containers.standard_container"></a><h5>
+<a name="id557101"></a>
+ <a class="link" href="custom_containers.html#boost_explore.tutorial.custom_containers.standard_container">Standard
+ Container</a>
+ </h5>

 The following is a very simple class that contains a 1, 2, and 3 along with
 the begin and end functions to access the iterators for the container.
@@ -44,8 +49,16 @@
 m_vec.push_back(3);
 }

- friend std::ostream& operator<<(std::ostream& ostr, const user_vector& u);
-
+ std::vector<int>::iterator begin()
+ {
+ return m_vec.begin();
+ }
+
+ std::vector<int>::iterator end()
+ {
+ return m_vec.end();
+ }
+
private:
 std::vector<int> m_vec;
};
@@ -58,9 +71,10 @@
 passes into stream_container the result of the begin and end functions, and
 allows stream_container to process the contents for it.
 
-<pre class="programlisting">std::ostream& operator<<(std::ostream& ostr, const user_vector& u)
+<pre class="programlisting">template<typename Elem, typename Tr>
+std::basic_ostream<Elem, Tr>& operator<<(std::basic_ostream<Elem, Tr>& ostr, const user_vector& u)
{
- return explore::stream_container(ostr, u.m_vec.begin(), u.m_vec.end());
+ return explore::stream_container(ostr, u.begin(), u.end());
}
</pre>

@@ -74,60 +88,23 @@
 
<pre class="programlisting">[1, 2, 3]
</pre>
+<a name="boost_explore.tutorial.custom_containers.associative_container"></a><h5>
+<a name="id557753"></a>
+ <a class="link" href="custom_containers.html#boost_explore.tutorial.custom_containers.associative_container">Associative
+ Container</a>
+ </h5>

 If the container had been an associative container of pairs, then the operator<<
 code would have looked like this:
 
-<pre class="programlisting">std::ostream& operator<<(std::ostream& ostr, const user_vector& u)
+<pre class="programlisting">template<typename Elem, typename Tr>
+std::basic_ostream<Elem, Tr>& operator<<(std::basic_ostream<Elem, Tr>& ostr, const user_vector& u)
{
 return explore::stream_container(ostr, u.begin(), u.end(), explore::stream_associative_value());
}
</pre>

- If the custom container has a stream operator that defines manipulators that
- should always be in effect for that container, then it becomes necessary
- to use the custom() manipulator. For example:
- 
-<pre class="programlisting">ostream& operator<<(ostream& ostr, const user_vector& u)
-{
- return ostr << explore::custom() << explore::delimiters("/", "::", "/") << u.m_vec.m_data;
-}
-</pre>
-
- The desire here is to use the delimiters "/" for begin/end and
- "::" for the separator, independent of what depth the container
- is streamed at. The "custom" manipulator allows this to work. If
- this is not specified, you will receive a debug assertion. With this new
- overload, the code:
- 
-<pre class="programlisting">user_vector v;
-std::cout << v;
-</pre>
-
- prints
- 
-<pre class="programlisting">/1::2::3/
-</pre>
-
- But more interestingly:
- 
-<pre class="programlisting">std::vector<user_vector> v;
-v.push_back(user_vector());
-v.push_back(user_vector());
-
-std::cout << explore::delimiters("{\n ", "\n ", "\n}") << v;
-</pre>
-
- prints
- 
-<pre class="programlisting">{
- /1::2::3/
- /1::2::3/
-}
-</pre>
-
- So the same delimiters are always used for the custom container, even when
- that container is nested in another.
+ The critical difference is the addition of the third parameter <code class="computeroutput">explore::stream_associative_value()</code>.
 
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
@@ -140,7 +117,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="custom_delimeters.html"><img src="../../../../../../doc/html/images/%20prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/%20up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/%20home.png" alt="Home"></a><a accesskey="n" href="../dependencies_platforms.html"><img src="../../../../../../doc/html/images/%20next.png" alt="Next"></a>
+<a accesskey="p" href="custom_delimeters.html"><img src="../../../../../../doc/html/images/%20prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/%20up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/%20home.png" alt="Home"></a><a accesskey="n" href="type_specific_formatting.html"><img src="../../../../../../doc/html/images/%20next.png" alt="Next"></a>
</div>
</body>
</html>

Modified: sandbox/explore/libs/explore/doc/html/boost_explore/tutorial/custom_delimeters.html
==============================================================================
--- sandbox/explore/libs/explore/doc/html/boost_explore/tutorial/custom_delimeters.html (original)
+++ sandbox/explore/libs/explore/doc/html/boost_explore/tutorial/custom_delimeters.html 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -31,7 +31,7 @@
 streaming process through the use of several new stream manipulators.
 
<div class="table">
-<a name="id555307"></a>Table 1. Explore Stream Manipulators
+<a name="id555417"></a>Table 1. Explore Stream Manipulators
<div class="table-contents"><table class="table" summary="Explore Stream Manipulators">
<colgroup>
<col>
@@ -223,7 +223,7 @@
<pre class="programlisting"><1, 2, 3>
</pre>
<a name="boost_explore.tutorial.custom_delimeters.manipulator_helper_functions"></a><h5>
-<a name="id555793"></a>
+<a name="id555903"></a>
 <a class="link" href="custom_delimeters.html#boost_explore.tutorial.custom_delimeters.manipulator_helper_functions">Manipulator
 Helper Functions</a>
 </h5>
@@ -232,7 +232,7 @@
 one call.
 
<div class="table">
-<a name="id555811"></a>Table 2. Explore Stream Manipulator Helpers
+<a name="id555921"></a>Table 2. Explore Stream Manipulator Helpers
<div class="table-contents"><table class="table" summary="Explore Stream Manipulator Helpers">
<colgroup>
<col>
@@ -311,7 +311,7 @@
<pre class="programlisting">std::cout << explore::begin_end("<", ">") << vi;
</pre>
<a name="boost_explore.tutorial.custom_delimeters.delimeters_by_level"></a><h5>
-<a name="id556001"></a>
+<a name="id556111"></a>
 <a class="link" href="custom_delimeters.html#boost_explore.tutorial.custom_delimeters.delimeters_by_level">Delimeters
 by Level</a>
 </h5>
@@ -325,11 +325,11 @@
{
 using namespace explore;

- // level 0
- ostr << start("") << explore::end("") << separator("\n");
+ ostr << level(0);
+ ostr << start("") << explore::end("") << separator("\n");

- // level 1
- ostr << start("|", 1) << explore::end("|", 1) << separator(" ", 1);
+ ostr << level(1);
+ ostr << start("|") << explore::end("|") << separator(" ");

 return ostr;
}
@@ -369,7 +369,7 @@
}
</pre>
<a name="boost_explore.tutorial.custom_delimeters.item_width"></a><h5>
-<a name="id556907"></a>
+<a name="id557034"></a>
 <a class="link" href="custom_delimeters.html#boost_explore.tutorial.custom_delimeters.item_width">Item
 Width</a>
 </h5>
@@ -377,7 +377,7 @@
 TODO: finish this section
 
<a name="boost_explore.tutorial.custom_delimeters.retrieving_manipulator_values"></a><h5>
-<a name="id556931"></a>
+<a name="id557058"></a>
 <a class="link" href="custom_delimeters.html#boost_explore.tutorial.custom_delimeters.retrieving_manipulator_values">Retrieving
 Manipulator Values</a>
 </h5>

Added: sandbox/explore/libs/explore/doc/html/boost_explore/tutorial/type_specific_formatting.html
==============================================================================
--- (empty file)
+++ sandbox/explore/libs/explore/doc/html/boost_explore/tutorial/type_specific_formatting.html 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -0,0 +1,91 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Type Specific Formatting</title>
+<link rel="stylesheet" href="../../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="../../index.html" title="Boost.explore">
+<link rel="up" href="../tutorial.html" title="Tutorial">
+<link rel="prev" href="custom_containers.html" title="Custom Containers">
+<link rel="next" href="../dependencies_platforms.html" title="Dependencies and Platforms">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="custom_containers.html"><img src="../../../../../../doc/html/images/%20prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/%20up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/%20home.png" alt="Home"></a><a accesskey="n" href="../dependencies_platforms.html"><img src="../../../../../../doc/html/images/%20next.png" alt="Next"></a>
+</div>
+<div class="section" title="Type Specific Formatting">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_explore.tutorial.type_specific_formatting"></a><a class="link" href="type_specific_formatting.html" title="Type Specific Formatting"> Type
+ Specific Formatting</a>
+</h3></div></div></div>
+
+ It is possible to define a custom format that is always be used when streaming
+ a specific container type. To do so, you need to use the custom() manipulator.
+ For example:
+ 
+<pre class="programlisting">ostream& operator<<(ostream& ostr, const user_vector& u)
+{
+ return ostr << explore::custom() << explore::delimiters("/", "::", "/") << u.m_vec.m_data;
+}
+</pre>
+
+ The desire here is to use the delimiters "/" for begin/end and
+ "::" for the separator whenever an instance of user_vector is streamed,
+ independent of what depth the container is streamed at. The "custom"
+ manipulator allows this to work. Without it you will receive a debug assertion.
+ With this new overload, the code:
+ 
+<pre class="programlisting">user_vector v;
+std::cout << v;
+</pre>
+
+ prints
+ 
+<pre class="programlisting">/1::2::3/
+</pre>
+
+ This nested example is more interesting. Even though we set the manipulators
+ on the stream, the type's formatting is still used:
+ 
+<pre class="programlisting">std::vector<user_vector> v;
+v.push_back(user_vector());
+v.push_back(user_vector());
+
+std::cout << explore::delimiters("{\n ", "\n ", "\n}") << v;
+</pre>
+
+ prints
+ 
+<pre class="programlisting">{
+ /1::2::3/
+ /1::2::3/
+}
+</pre>
+
+ So the same delimiters are always used for the custom container, even when
+ that container is nested in another.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2007 Jeff Garland, 2008-2009 Jared McIntyre
+ 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)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="custom_containers.html"><img src="../../../../../../doc/html/images/%20prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/%20up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/%20home.png" alt="Home"></a><a accesskey="n" href="../dependencies_platforms.html"><img src="../../../../../../doc/html/images/%20next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Modified: sandbox/explore/libs/explore/doc/html/index.html
==============================================================================
--- sandbox/explore/libs/explore/doc/html/index.html (original)
+++ sandbox/explore/libs/explore/doc/html/index.html 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -37,6 +37,8 @@
<dd><dl>
<dt> Custom Delimiters</dt>
<dt> Custom Containers</dt>
+<dt><a href="boost_explore/tutorial/type_specific_formatting.html"> Type
+ Specific Formatting</a></dt>
</dl></dd>
<dt><a href="boost_explore/dependencies_platforms.html"> Dependencies and
 Platforms</a></dt>
@@ -47,7 +49,7 @@
 Boost.explore is a cross-platform C++ library for printing of containers.
 
<a name="boost_explore..getting_started"></a><h3>
-<a name="id558478"></a>
+<a name="id558869"></a>
 <a class="link" href="index.html#boost_explore..getting_started">Getting Started</a>
 </h3>

@@ -70,7 +72,7 @@
std::vector<std::vector<int> > vvi;
vvi.push_back(vi);
vvi.push_back(vi);
-std::cout << vvi; // prints [[1, 2, 3], [1, 2, 3]]
+std::cout << vvi; // prints [[1, 2, 3], [1, 2, 3]]

// associative containers
std::map<std::string, int> si_map;
@@ -97,11 +99,11 @@

 While explore is powerful and flexible, it is not infinitely flexible. The reasons
 for this are discussed in the <a class="link" href="boost_explore/design.html" title="Design Notes">design</a>
- section.For very complex output custom methods or a template output system should
+ section. For very complex output custom methods or a template output system should
 be considered.
 
<a name="boost_explore..supported_containers"></a><h3>
-<a name="id559600"></a>
+<a name="id559991"></a>
 <a class="link" href="index.html#boost_explore..supported_containers">Supported Containers</a>
 </h3>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
@@ -144,7 +146,7 @@
 can also be made to work with explore.
 
<a name="boost_explore..acknowledgements"></a><h3>
-<a name="id559664"></a>
+<a name="id560055"></a>
 <a class="link" href="index.html#boost_explore..acknowledgements">Acknowledgements</a>
 </h3>

Modified: sandbox/explore/libs/explore/doc/tutorial.qbk
==============================================================================
--- sandbox/explore/libs/explore/doc/tutorial.qbk (original)
+++ sandbox/explore/libs/explore/doc/tutorial.qbk 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -1,6 +1,6 @@
[/
 / Copyright (c) 2007 Jeff Garland (jeff at crystalclearsoftware dot com)
- / Copyright (c) 2008 Jared McIntyre
+ / Copyright (c) 2008-2009 Jared McIntyre
 /
 / 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)
@@ -17,10 +17,15 @@
 ``''''''``#include <boost/explore.hpp>
 ``''''''``using namespace boost::explore;

+However, this will pull in definitions of all the containers that Explore supports. To include only the definitions required for a
+specific container include each type's header file instead of `"explore.hpp"`.
+
+ ``''''''``#include <boost/explore/vector.hpp>
+ ``''''''``#include <boost/explore/boost_array.hpp>

[heading Printing of Contained Items]

-Basic printing of containers requires the inclusing of explore.hpp. Once included, containers can be be streamed in a formated manner.
+Once you have included the proper header files, containers can be be streamed in a formated manner.

 std::vector<int> vi;
 vi.push_back(1);
@@ -32,9 +37,11 @@

 [1, 2, 3]

-The beginning of the container will be marked with a '\[' and the end will be marked with a '\]'. Each item in the container will be seperated by a ', ' to allow for easier identification of each item.
+The beginning of the container will be marked with a '\[' and the end will be marked with a '\]'. Each item in the container will be seperated by
+a ', ' to allow for easier identification of each item.

-Containers that contain other containers will print the child containers using the same format for the parent, their children, their children's children, etc.
+Containers that contain other containers will print the child containers using the same format for the parent, their children, their children's
+children, etc.

 std::vector<std::vector<int> > vvi;
 vvi.push_back(vi);
@@ -47,7 +54,8 @@

[heading C Style Arrays]

-C style arrays have a standard streaming format, however, when you include explore.hpp, you override this default streaming format with the explore streaming format and all the abilities of it.
+C style arrays have a standard streaming format, however, when you include any explore header, including `"explore.hpp"` and
+`"boost/explore/c_array.hpp"`, you override this default streaming format with the explore streaming format and all the abilities of it.

 int arr[3] = {1,2,3};
 std::cout << arr;
@@ -70,7 +78,8 @@

 [[1, first], [2, second], [3, third]]

-But this format doesn't describe the associative nature of the elements well. So, explore uses special delimeters for the associations within associative containers, and the above code prints in a clearer format.
+But this format doesn't describe the associative nature of the elements well. So, explore uses special delimeters for the associations within
+associative containers, and the above code prints in a clearer format.

 [1:first, 2:second, 3:third]

@@ -83,15 +92,16 @@

[heading lexical_cast]

-Because explore works with streaming operators, boost::lexical_cast will work with the explore library to allow you to create strings with the printed output of explore for cases when you don't want to use streaming directly.
+Because explore works with streaming operators, boost::lexical_cast will work with the explore library to allow you to create strings with the
+printed output of explore for cases when you don't want to use streaming directly.

 std::vector<int> vi;
 vi.push_back(1);
 vi.push_back(2);
 vi.push_back(3);
- std::string outVal( boost::lexical_cast<std::string>(vi) );
+ std::cout << boost::lexical_cast<std::string>(vi);

-outVal equals
+prints

 [1, 2, 3]

@@ -99,4 +109,6 @@

[include custom_containers.qbk]

+[include type_specific_formatting.qbk]
+
[endsect]
\ No newline at end of file

Added: sandbox/explore/libs/explore/doc/type_specific_formatting.qbk
==============================================================================
--- (empty file)
+++ sandbox/explore/libs/explore/doc/type_specific_formatting.qbk 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -0,0 +1,44 @@
+[/
+ / Copyright (c) 2009 Jeffrey Faust
+ / Copyright (c) 2009 Jared McIntyre
+ /
+ / 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:type_specific_formatting Type Specific Formatting]
+
+It is possible to define a custom format that is always be used when streaming a specific container type. To do so, you need to use the custom() manipulator. For example:
+
+ ostream& operator<<(ostream& ostr, const user_vector& u)
+ {
+ return ostr << explore::custom() << explore::delimiters("/", "::", "/") << u.m_vec.m_data;
+ }
+
+The desire here is to use the delimiters "/" for begin/end and "::" for the separator whenever an instance of user_vector is streamed, independent of what depth the container is streamed at. The "custom" manipulator allows this to work. Without it you will receive a debug assertion. With this new overload, the code:
+
+ user_vector v;
+ std::cout << v;
+
+prints
+
+ /1::2::3/
+
+This nested example is more interesting. Even though we set the manipulators on the stream, the type's formatting is still used:
+
+ std::vector<user_vector> v;
+ v.push_back(user_vector());
+ v.push_back(user_vector());
+
+ std::cout << explore::delimiters("{\n ", "\n ", "\n}") << v;
+
+prints
+
+ {
+ /1::2::3/
+ /1::2::3/
+ }
+
+So the same delimiters are always used for the custom container, even when that container is nested in another.
+
+[endsect]

Modified: sandbox/explore/libs/explore/test/c_array.cpp
==============================================================================
--- sandbox/explore/libs/explore/test/c_array.cpp (original)
+++ sandbox/explore/libs/explore/test/c_array.cpp 2009-09-17 01:31:26 EDT (Thu, 17 Sep 2009)
@@ -10,7 +10,8 @@
#define BOOST_TEST_MODULE PrintLib
#include <boost/test/unit_test.hpp>
#include <vector>
-#include <boost/explore.hpp>
+#include <boost/explore/c_array.hpp>
+#include <boost/explore/vector.hpp>
#include "boost_explore_test_tools.hpp"

BOOST_AUTO_TEST_CASE_TEMPLATE( basic_c_array_stream_test, C, test_types )

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk