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.

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.

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