code_converter
The class templates code_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 which can either be specified as a template parameter or be fetched from a std::locale provided at runtime.
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 code_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 code_converter<array_sink> my_sink;
The mode of a specialization of code_converter is determined as follows. If a narrow character Device is read-only, the resulting specialization of code_converter has mode input. If a narrow character Device is write-only, the resulting specialization of code_converter has mode output. If a narrow character Device performs input and output using two distinct sequences (see Modes), the resulting specialization of code_converter has mode bidirectional. Otherwise, attempting to spcialize code_converter results in a compile-time error.
<boost/iostreams/code_converter.hpp>namespace boost { namespace iostreams {
template< typename Device,
typename Codecvt = default_value
typename Alloc = std::allocator<char> >
class code_converter {
public:
typedef typename Codecvt::intern_type char_type;
typedef implementation-defined category;
code_converter();
code_converter( const Device& dev,
int buffer_size = default_value );
code_converter( device-constructor-args...,
int buffer_size = default_value );
void open( const Device& dev,
int buffer_size = default_value );
void open( device-constructor-args...,
int buffer_size = default_value );
bool is_open() const;
void close();
std::locale imbue(const std::locale& loc);
Device& operator*();
Device* operator->();
};
} } // End namespace boost::io
| Device | - | A model of one of the Device concepts; typically has character type char. |
| Codecvt | - |
A standard library codecvt facet, which must be default constructible. If this parameter is not specified,
an instance of std::codecvt<wchar_t, char, std::mbstate_t> will be fetched from the global
local when a code_converter is constructed or opened.
|
| Alloc | - | A standard library allocator type ([ISO], 20.1.5), used to allocate character buffers |
code_converter::code_converter code_converter();
code_converter( const Device& dev,
int buffer_size );
code_converter( device-constructor-args...,
int buffer_size );
The first member constructs a code_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 code_converter based on the given instance of Device. The second parameter determines the size of the buffers or buffers used for code conversion. If a std::codecvt was specified as a template parameter, an instance of it will be default constructed. Otherwise, a copy of the global locale will be made, and an instance of std::codecvt<wchar_t, char, std::mbstate_t> will be fetched from it.
The third member constructs a code_converter based on the given instance of Device constructed with the forwarded arguments. Take care as the buffer_size can be confused for a constructor argument if it isn't an int.
code_converter::imbue std::locale imbue(const std::locale& loc);
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.
This function is a no-op if a std::codecvt facet was specified as a template parameter.
code_converter::openvoid open( const Device& dev, std::streamsize buffer_size = default_value ); void open( device-constructor-args, std::streamsize buffer_size = default_value );
Associates the given instance of Device with this instance of code_converter, if there is no such instance currently associated; otherwise, throws std::ios_base::failure. The second parameter determines the size of the buffer or buffers used for code conversion. If a std::codecvt was specified as a template parameter, an instance of it will be default constructed. Otherwise, a copy of the global locale will be made, and an instance of std::codecvt<wchar_t, char, std::mbstate_t> will be fetched from it.
The second member constructs a Device with the forwarded arguments. Take care as the buffer_size can be confused for a constructor argument if it isn't an int.
code_converter::is_openbool is_open() const;
Returns true if there is an instance of the Device type Device associated with this instance of code_converter.
code_converter::close void close();
Disassociates from this instance of code_converter any instance of the Device type Device currently associated with it, calling cleanup functions as appropriate and destroying the associated instance of Device.
code_converter::operator*Device& operator*();
Returns a reference to the instance of Device associated with this instance of code_converter, which must be open.
code_converter::operator->Device* operator->();
Returns a pointer to the instance of Device associated with this instance of code_converter, which must be open.
Revised 02 Feb 2008
© Copyright 2008 CodeRage, LLC
© Copyright 2004-2007 Jonathan Turkanis
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)