Re: [boost] Re: io operations for stl containers?

From: Terje Slettebø (tslettebo_at_[hidden])
Date: 2003-03-26 11:29:01

Hi.

I've now uploaded the latest version of the composite stream operators
library at Yahoo Files
(http://groups.yahoo.com/group/boost/files/composite_stream_operators/) and
the Sandbox (boost/io/format/ and libs/io/format)..

Since the libraries in the Sandbox use the boost namespace, this one does
the same. All components are in the boost::io namespace.

There are no docs, yet, but there are several test programs, illustrating
use for all supported types (the list of these are given below). I also
include information here.

Feedback is welcome.

Examples of use:

std::vector
---------------
#include <boost/io/format/std/vector.hpp>

std::vector<int> v;

// Fill vector

// Output (using user-changeable default format)

std::cout << v;

Output:

[1,2,3,4,5,6,7,8,9,10]

std::map
------------
#include <boost/io/format/std/map.hpp>

typedef std::map<int,char> map;
typedef map::value_type value_type;

map values;

// Fill map

std::cout << format<value_type>("[", "]\n", " => ")
                << format<map>("","","")
                << values;

Output:

[1 => A]
[2 => B]
[3 => C]

Array
-------
#include <boost/io/format/array.hpp>

int array[]={1,2,3,4,5,6,7,8,9,10};

std::cout << array << '\n'
                << format<_ (&)[N]>("", "", "\n")
               << array;

Output:

[1,2,3,4,5,6,7,8,9,10]

1
2
3
4
5
6
7
8
9
10

Here is a synopsis
--------------------------

namespace boost::io
-----------------------------

format - Set output formatting
======================

Type options
------------------
"_" - Any type
"N" - Any size (for array)
template_name<_> - Any instantiation of the given template (may need more
"_"s, one for each parameter without default)

Syntax
----------
format<Type>(<start sequence>, <end sequence>, <delimiter>, [<start
element>, <end element>])[.set_default_format()]
format<Type>(<set/unset format>)

If set_default_format() is used, it may be used without a stream, and it
then sets the format for all streams.

Examples
--------------
stream << format<std::vector<int> >(...) // Set format for std::vector<int>
stream << format<std::vector<_> >(...) // Set format for any instantiation
of std::vector
stream << format<_>(...) // Set format for any type

stream << format<std::vector<int> >(false) // Unsets format for
std::vector<int>

It checks for format settings, going from the most specific to the most
general, stopping when it has found a set format. E.g. for the above
example, this means checking in the following order:

std::vector<int>
std::vector<_>
_
_ (any stream)

The library sets the following default for all streams (the last format
checked), which may be changed by the user. This default is set rather
arbitrarily, and is open to change. This is so that no formatting is needed
to be set, to get useful output:

format<_>("[", "]", ",").set_default_format() - Sets format for all types,
for all streams.

It also handles wide character formatting:

format<Type>(L"[", L"]", L",")

sequence - Lets a sequence, given with start/end iterators, be output as the
given type
==================================================================

Syntax
----------
sequence<Type>(<start iterator>, <end iterator>)

Examples
--------------
#include <boost/io/format/sequence.hpp>

std::vector<int> v;

// Fill vector

std::cout << sequence<_>(v.begin(),v.begin()+10);

Output:

[1,2,3,4,5,6,7,8,9,10]

typedef std::istream_iterator<int> in;

std::cout << sequence<_>(in(std::cin),in());

Input:

1 2 3 4 5 6 7 8 9 10

Output:

[1,2,3,4,5,6,7,8,9,10]

wrap - Lets a type be output using set format, even if it has its own output
operator
==============================================================

Some types, such as std::complex, std::bitset, and boost::dynamic_bitset
have already output stream operators defined, so to set their format, one
may wrap the value before outputting.

Syntax
---------
wrap(<value>)

Examples
--------------
#include <boost/io/format/std/complex.hpp>

std::complex<double> value(1.23, 2.34);

std::cout << value << '\n'
                << wrap(value);

Output:

(1.23,2.34)
[1.23,2.34]

Supported types
=============
Arrays

std
----
pair
complex (has output operator, use wrap)
vector
list
deque
set
multiset
map
multimap
bitset (has output operator, use wrap)
boost
--------
dynamic_bitset (has output operator, use wrap)
The supported types may also be extended by the user.
Header organisation
================
boost/io/format ---
                               |--- std
                               |--- boost
libs/format/io  ---
                            |--- tests
Compatibility
==========
The library uses standard C++, but isn't very portable currently. It has
been tested on Intel C++ 7.0 and g++ 3.2.
I plan to work on the portability, and should soon get it to work on MSVC,
etc., as well.
The names, syntax and semantics is open to suggestions for change.
I hope Daryle Walker doesn't mind that this library is sharing the "io"
directory and namespace, at the Sandbox. If so, I could change it from
"io/format" to "io_format".
Thanks for the patience to those who have waited for this update.
Regards,
Terje