# Function Template `write`

Overview
Example
Headers
Reference

## Overview

The two overloads of the function template `write` provide a uniform interface for writing a sequence of characters to a Sink or OutputFilter.

- The first overload can be used directly in the definitions of new Filter types (see Example), and figures in the specification of the Device concepts.
- The second overload is primarily for internal use by the library.

## Example

The following code illustrates the use of the function `write` in the definition of an OutputFilter which reverses its controlled sequence.

        #include <algorithm>                      // reverse
        #include <vector>
        #include <boost/iostreams/concepts.hpp>   // output_filter
        #include <boost/iostreams/operations.hpp> // write

        using namespace std;
        using namespace boost::io;

        struct reversing_filter : public multichar_output_filter {
            template<typename Sink>
            std::streamsize write(Sink& snk, const char* s, streamsize n)
            {
                data.insert(data.end(), s, s + n);
                return n;
            }
            template<typename Sink>
            void close(Sink& snk)
            {
                std::reverse(data.begin(), data.end());
                boost::iostreams::write(&data[0], (streamsize) data.size());
                data.clear();
            }
            std::vector<char> data;
        };

## Headers

`<boost/iostreams/operations.hpp>`
`<boost/iostreams/write.hpp>`

## Reference

#### Description

Attempts to write a sequence of characters to a given instance of the template parameter `T`, returning the number of characters written.

#### Synopsis

    namespace boost { namespace iostreams {

    template<typename T>
    std::streamsize
    write( T& t,
           const typename char_type_of<T>::type* s,
           std::streamsize n );

    template<typename T, typename Sink>
    std::streamsize
    write( T& t,
           Sink& snk,
           const typename char_type_of<T>::type* s,
           std::streamsize n );

    } } // End namespace boost::io

#### Template Parameters

T | - | For the first overload, a model of Sink. For the second overload, a model of OutputFilter.
Sink | - | A model of Sink with the same character type as `T` whose mode refines that of `T`.

#### Function Parameters

t | - | An instance of T
s | - | A buffer containing characters to write
n | - | The number of characters to write
snk | - | An instance of `Sink`.

#### Semantics — Device Types

    template<typename T>
    std::streamsize
    write( T& t,
           const typename char_type_of<T>::type* s,
           std::streamsize n );

The semantics of `write` depends on the category of `T` as follows:

`category_of<T>::type` | semantics
--- | ---
convertible to `ostream_tag` | returns `t.rdbuf()->sputn(s, n)`
convertible to `streambuf_tag` but not to `ostream_tag` | returns `t.sputn(s, n)`
otherwise | returns `t.write(s, n)`

#### Semantics — Filter Types

    template<typename T, typename Sink>
    std::streamsize
    write( T& t,
           Sink& snk,
           const typename char_type_of<T>::type* s,
           std::streamsize n );

The semantics of `write` depends on the category of `T` as follows:

`category_of<T>::type` | semantics
--- | ---
convertible to `multichar_tag` | returns `t.write(snk, s, n)`
otherwise | Attempts to write `n` characters from `s` by invoking `t.put(snk, s[m])` for each value `m` in the interval `[0, n)`, halting if `put` returns `false`. Returns the number of characters written.

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)