Class Template code_converter

DescriptionHeadersReference

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\>](../../../../boost/iostreams/device/mapped_file.hpp)typedefcode_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\>](../../../../boost/iostreams/device/array.hpp)typedefcode_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

namespaceboost {namespaceiostreams {template<typename[Device](#template_params),typename[Codecvt](#template_params)=default\_valuetypename[Alloc](#template_params)= std::allocator<char> >class[code\_converter](#template_params){public:typedeftypenameCodecvt::intern_type char_type;typedefimplementation-definedcategory;[code\_converter](#constructors)();[code\_converter](#constructors)(constDevice& dev, 
                    int buffer_size =default\_value);[code\_converter](code_converter.html#constructors)(device-constructor-args...,
                    int buffer_size =default\_value);void[open](code_converter.html#open)(constDevice& dev, 
               int buffer_size =default\_value);void[open](code_converter.html#open)(device-constructor-args...,
               int buffer_size =default\_value);bool[is\_open](#is_open)()const;void[close](#close)();
    std::locale[imbue](#imbue)(conststd::locale& loc);
    Device&[operator\*](#operator_star)();
    Device*[operator-\>](#operator_arrow)();
};

} }// 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(constDevice& 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(conststd::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

voidopen(constDevice& dev,
                std::streamsize buffer_size =default\_value);voidopen(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

boolis_open()const;

Returns true if there is an instance of the Device type Device associated with this instance of code_converter.

code_converter::close

voidclose();

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.

© 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)