Class Template code_converter

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

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