Class Template code_converter

Description
Headers
Reference

Description

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.

Headers

<boost/iostreams/code_converter.hpp>

Reference

Synopsis

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

Template parameters

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::open

     void 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_open

    bool 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.