# I/O Traits and Categories

Overview
Headers
Class template `char_type_of`
Class template `int_type_of`
Class template `category_of`
Category Tags

## Overview

The header `<boost/iostreams/categories.hpp>` contains category tags for classifying models of the various Filter and Device concepts. The header `<boost/iostreams/traits.hpp>` contains the definitions of the metafunctions `char_type_of` and `category`, used to associate two fundamental types with each model of one the Filter or Device concepts:

#### Character Type

The type of characters which a Filter or Device reads or writes.

#### Category

A tag structure which the Iostreams library relies on to determine which operations a Filter or Device supports. It indicates, for a given type `T`:

- whether `T` is a Filter or a Device
- the mode of `T`
- any optional_behavior `T` implements

Its function is similar to the `iterator_category` member of `std::iterator_traits`.[1] Types which serve as categories are called category tags.

## Headers

`<boost/iostreams/categories.hpp>`
`<boost/iostreams/traits.hpp>`

## Class Template `char_type_of`

#### Description

Metafunction associating a character type to each Filter or Device type. Although `char_type_of` is designed to be specialized for new Filter and Device types, the default implementation should be suitable for most purposes.

#### Synopsis

    namespace boost { namespace iostreams {

    template<typename T>
    struct char_type_of {
        typedef see below type;
    };

    } } // End namespace boost::io

#### Template parameters

T | - | A model of one of the Filter or Device concepts

#### `io_traits::type`

        typedef see below char_type;

The value of the nested type `type` depends on the template parameter `T` as follows:

`T` | `char_type`
--- | ---
Sepcialization of `std::back_insert_iterator` | The `value_type` of the iterator's `container_type`
All other types | `T::char_type`

## Class Template `int_type_of`

#### Description

Metafunction associating an integral type to each Filter or Device type. Although `int_type_of` is designed to be specialized for new Filter and Device types, the default implementation should be suitable for most purposes.

#### Synopsis

    namespace boost { namespace iostreams {

    template<typename T>
    struct int_type_of {
        typedef see below type;
    };

    } } // End namespace boost::io

#### Template parameters

T | - | A model of one of the Filter or Device concepts

#### `io_traits::type`

        typedef see below char_type;

Equal to `std::char_traits<char_type>::int_type`, where `char_type` is `char_type_of<T>::type`.

## Class Template `category_of`

#### Description

Metafunction associating a category tag to each Filter or Device type. Although `category` is designed to be specialized for new Filter and Device types, the default implementation should be suitable for most purposes.

#### Synopsis

    namespace boost { namespace iostreams {

    template<typename T>
    struct category_of {
        typedef see below type;
    };

    } } // End namespace boost::io

#### Template parameters

T | - | A model of one of the Filter or Device concepts

#### `category::type`

        typedef see below type;

The value of the nested type `type` depends on the template parameter `T` as follows:

`T` | `category`
--- | ---
Specialization of `std::basic_iostream`, or derived from such a specialization | `iostream_tag`
Specialization of `std::basic_istream`, or derived from such a specialization | `istream_tag`
Specialization of `std::basic_ostream`, or derived from such a specialization | `ostream_tag`
Specialization of `std::basic_streambuf`, or derived from such a specialization | `streambuf_tag`
Specialization of `std::back_insert_iterator`, or derived from such a specialization | `insert_iterator_tag`
All other types | `T::category`

For more information, see `<boost/iostreams/traits.hpp>`.

## Category Tags

In addition to the various mode tags, the header `<boost/iostreams/categories.hpp>` provides the category tags shown in the following table. To produce a new category tag which combines several existing tags, simply define a `struct` extending the existing tags. E.g.,

        struct category
            : seekable,
              filter_tag,
              localizable_tag
            { };

This defines a category tag representing Seekable, Localizable Filters.

Tag | Description
--- | ---
`filter_tag` | Indicates that a type models Filter
`device_tag` | Indicates that a type models Device
`closable_tag` `localizable_tag` `direct_tag` `peekable_tag` `multichar_tag` | Used to indicate optional behavior implemented by a Filter or Device type
`source_tag` `sink_tag` `bidirectional_device_tag` `seekable_device_tag` `input_filter_tag` `output_filter_tag` `bidirectional_filter_tag` `seekable_filter_tag` `multichar_input_filter_tag` `multichar_output_filter_tag` `multichar_bidirectional_filter_tag` `multichar_seekable_filter_tag` | Convenience tags for defining models of the various Filter and Device refinements
`istream_tag` `ostream_tag` `iostream_tag` `streambuf_tag` | Used internally to distinguish standard stream and stream buffer types
`insert_iterator_tag` | Used internally to distinguish specialization of `std::back_insert_iterator`

[1] [ISO] 24.3.1. See Tag Dispatching for a discussion.

© Copyright 2008 CodeRage, LLC
© Copyright 2004-2007 Jonathan Turkanis

Use modification and distribution are subject to 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)