converter
The class templates converter is a Device adapter which takes a Device with a narrow character type — typically char — and produces a Device with wide character type — typically wchar_t — by introducing a layer of code conversion. The code conversion is performed using a std::codecvt facet fetched from a contained std::locale object.
For example, we can define a wide-character Device for reading from a memory-mapped file as follows:
#include <boost/iostreams/maped_file.hpp> typedef converter<mapped_file_source> my_source;Similarly, we can define a wide-character Device which writes multibyte characters to an in-memory character sequence as follows:
#include <boost/iostreams/device/array.hpp> typedef converter<array_sink> my_sink;
The i/o mode of a specialization of converter is determined as follows. If a narrow character Device is read-only, the resulting specialization of converter has mode input. If a narrow character Device is write-only, the resulting specialization of converter has mode output. If a narrow character Device performs input and output using two distinct sequences (see Modes), the resulting specialization of converter has mode bidirectional. Otherwise, attempting to spcialize converter results in a compile-time error.
It would be possible for converter to permit random-access, provided that the underlying Device type permits random access and that its codecvt facect is sufficiently well-behaved. This behavior is not currently implemented.
<boost/iostreams/converter.hpp>namespace boost { namespace iostreams {
template< typename Device,
typename Alloc = std::allocator<char>,
typename Int = wchar_t,
typename IntTr = std::char_traits<Int> >
class converter {
public:
typedef Int char_type;
typedef implementation-defined io_category
converter();
converter( const Device& dev,
const std::locale& loc = classic locale,
std::streamsize buffer_size = default_value );
std::locale imbue(const std::locale& loc);
// streambuf_facade-like interface
void open( const Device& dev,
const std::locale& loc = classic locale,
std::streamsize buffer_size = default_value );
bool is_open() const;
void close();
// Device access
Device& operator*();
Device* operator->();
// Appropriate member functions for i/o, depending on
// the i/o mode of Device
};
} } // End namespace boost::io
| Device | - | A model of one of the Device concepts; typically has character type char. |
| Alloc | - | A standard library allocator type ([ISO], 20.1.5), used to allocate character buffers |
| Int | - | The internal — i.e., wide — character type |
| IntTr | - | The traits type associated with Int |
converter::converter converter();
converter( const Device& dev,
const std::locale& loc,
std::streamsize buffer_size );
The first member constructs a converter with no associated instance of the Device type Device. Before the instance can be used for i/o, the member function open() must be invoked. The second member constructs a converter based on a copy of the given instance of Device. The second parameter is a std::locale from which an appropriate std::codecvt facet will be fetched to perform the code conversion. The third parameter determines the size of the buffers or buffers used for code conversion.
converter::imbue
Used to specify a locale from which a std::codecvt facet will be fetched to perform code conversion. The effect of invoking imbue while code conversion is in progress is undefined.
converter::open
Assocaites the given instance of Device with this instance of converter, if there is no such instance currently associated; otherwise, throws std::ios_base::failure. The second parameter is a std::locale from which an appropriate std::codecvt facet will be fetched to perform the code conversion. The third parameter determines the size of the buffer or buffers used for code conversion.
converter::is_openReturns true if there is an instance of the Device type Device associated with this instance of converter.
converter::close
Disassociates from this instance of converter any instance of the Device type Device currently associated with it, calling cleanup functions as appropriate and destroying the associated instance of Device.
Revised 20 May, 2004
© Copyright Jonathan Turkanis, 2004
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)