# Newline Filters

Overview
Headers
Synopsis
Reference

1. namespace `boost::iostreams::newline`
2. Class `newline_filter`
3. Class `newline_checker`
4. Class `newline_error`

## Overview

Boost.Iostreams provides two components for working with line-ending conventions: the class template `newline_filter` translates between line-ending conventions, and the class template `newline_checker` verifies that a character sequence conforms to a given line-ending convention.

## Headers

`<boost/iostreams/filter/newline.hpp>`

## Synopsis

    namespace boost { namespace iostreams {

    namespace newline {

    const int posix             = 1;    // Use CR as line separator.
    const int mac               = 2;    // Use LF as line separator.
    const int dos               = 4;    // Use CRLF as line separator.
    const int mixed             = 8;    // Mixed line endings.
    const int final_newline     = 16;

    }   // End namespace boost::iostreams::newline

    class newline_filter;
    class newline_checker;
    class newline_error;

    } } // End namespace boost::io

## Reference

### 1. Namespace `boost::iostreams::newline`

The namespace `boost::iostreams::newline` contains integral constants used to configure `newline_filter`, `newline_checker` and to report errors. The constants have the following interpretations.

Constant | Interpretation
--- | ---
`posix` | Used to indicate POSIX line-ending conventions.
`dos` | Used to indicate DOS line-ending conventions.
`mac` | Used to indicate classic Mac line-ending conventions.
`mixed` | Used to describe a document with mixed line endings.
`final_newline` | Used to indicate that a document ends in a newline sequence.

### 2. Class `newline_filter`

#### Description

DualUseFilter which converts between the line-ending conventions used by various operating systems. Its sole constructor takes an integral parameter used to specify the target format.

#### Synopsis

    class newline_filter {
    public:
        typedef char                      char_type;
        typedef [implementation-defined]  category;
        explicit newline_filter(int target);
    };

#### `newline_filter::newline_filter`

        explicit newline_filter(int target);

Constructs a newline_filter for converting to the specified format. The parameter target must be `newline::posix`, `newline::dos` or `newline::mac`.

### 3. Class `newline_checker`

#### Description

DualUseFilter used to verify that a character sequence conforms to a given line-ending convention.

#### Synopsis

    class newline_checker {
    public:
        typedef char                      char_type;
        typedef [implementation-defined]  category;
        explicit newline_checker(int target = default_value );
        bool is_posix() const;
        bool is_dos() const;
        bool is_mac() const;
        bool is_mixed_posix() const;
        bool is_mixed_dos() const;
        bool is_mixed_mac() const;
        bool is_mixed() const;
        bool has_final_newline() const;
    };

#### `newline_checker::newline_checker`

        explicit newline_checker(int target = default_value );

Constructs a newline_checker. If a target is specified, a newline_error will be thrown as soon as a line-ending sequence is encountered which does not conform to the target. The value target must be be `newline::posix`, `newline::dos` or `newline::mac` or the bitwise OR of one of these values with `newline::final_newline`.

Note: If a `newline_checker` is being used to perform output, the failure of a character sequence to end with a newline sequence may be discovered only when the newline_checker is closed. There are certain circumstances in which exceptions thrown by `close` are caught and ignored by the Iostreams library. Consequently, when performing output specifying `newline::final_newline` as part of `target` may have no effect. To check whether a character sequence ends with a newline sequence, call `has_final_newline` after the `newline_checker` has been closed.

#### `newline_checker::is_posix`

        bool is_posix() const;

Returns true if the characters examined so far contained at least one POSIX line-ending sequence and no line-ending sequences of any other type.

#### `newline_checker::is_dos`

        bool is_dos() const;

Returns true if the characters examined so far contained at least one DOS line-ending sequence and no line-ending sequences of any other type.

#### `newline_checker::is_mac`

        bool is_mac() const;

Returns true if the characters examined so far contained at least one classic Mac line-ending sequence and no line-ending sequences of any other type.

#### `newline_checker::is_mixed_posix`

        bool is_mixed_posix() const;

Returns true if the characters examined so far contained at least one POSIX line-ending sequence.

#### `newline_checker::is_mixed_dos`

        bool is_mixed_dos() const;

Returns true if the characters examined so far contained at least one DOS line-ending sequence.

#### `newline_checker::is_mixed_mac`

        bool is_mixed_mac() const;

Returns true if the characters examined so far contained at least one classic Mac line-ending sequence.

#### `newline_checker::is_mixed`

        bool is_mixed() const;

Returns true if the characters examined so far contained line-ending sequences of more than one type.

#### `newline_checker::has_final_newline`

        bool has_final_newline() const;

Returns `true` if this `newline_checker` has either been closed or has reached end-of-stream, and if the examined character sequence ended with a newline sequence.

### 4. Class template `newline_error`

#### Description

Used by `newline_checker` to report errors.

#### Synopsis

    class newline_error : public std::ios_base::failure {
    public:
        bool is_posix() const;
        bool is_dos() const;
        bool is_mac() const;
        bool is_mixed_posix() const;
        bool is_mixed_dos() const;
        bool is_mixed_mac() const;
        bool is_mixed() const;
        bool has_final_newline() const;
    };

#### `newline_error::is_posix`

        bool is_posix() const;

Returns true if the characters examined by the `newline_checker` which threw this exception contained at least one POSIX line-ending sequence and no line-ending sequences of any other type.

#### `newline_error::is_dos`

        bool is_dos() const;

Returns true if the characters examined by the `newline_checker` which threw this exception contained at least one DOS line-ending sequence and no line-ending sequences of any other type.

#### `newline_error::is_mac`

        bool is_mac() const;

Returns true if the characters examined by the `newline_checker` which threw this exception contained at least one classic Mac line-ending sequence and no line-ending sequences of any other type.

#### `newline_error::is_mixed_posix`

        bool is_mixed_posix() const;

Returns true if the characters examined by the `newline_checker` which threw this exception contained at least one POSIX line-ending sequence.

#### `newline_error::is_mixed_dos`

        bool is_mixed_dos() const;

Returns true if the characters examined by the `newline_checker` which threw this exception contained at least one DOS line-ending sequence.

#### `newline_error::is_mixed_mac`

        bool is_mixed_mac() const;

Returns true if the characters examined by the `newline_checker` which threw this exception contained at least one classic Mac line-ending sequence.

#### `newline_error::is_mixed`

        bool is_mixed() const;

Returns true if the characters examined by the `newline_checker` which threw this exception contained line-ending sequences of more than one type.

#### `newline_error::has_final_newline`

        bool has_final_newline() const;

Returns `true` if the `newline_checker` which threw this exception was either closed or had reached end-of-stream and if the examined character sequence ended with a newline sequence.

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)