1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4 <TITLE>Newline Filters</TITLE> 5 <LINK REL="stylesheet" HREF="../../../../boost.css"> 6 <LINK REL="stylesheet" HREF="../theme/iostreams.css"> 7</HEAD> 8<BODY> 9 10<!-- Begin Banner --> 11 12 <H1 CLASS="title">Newline Filters</H1> 13 <HR CLASS="banner"> 14 15<!-- End Banner --> 16<DL class="page-index"> 17 <DT><A href="#overview">Overview</A></DT> 18 <DT><A href="#headers">Headers</A></DT> 19 <DT><A href="#synopsis">Synopsis</A></DT> 20 <DT><A HREF="#reference">Reference</A> 21 <DL class="page-index"> 22 <DT>1. <A HREF="#constants">namespace <CODE>boost::iostreams::newline</CODE></A></DT> 23 <DT>2. <A HREF="#newline_filter">Class <CODE>newline_filter</CODE></A></DT> 24 <DT>3. <A HREF="#newline_checker">Class <CODE>newline_checker</CODE></A></DT> 25 <DT>4. <A HREF="#newline_error">Class <CODE>newline_error</CODE></A></DT> 26 </DL> 27 </DT> 28</DL> 29 30<A NAME="overview"></A> 31<H2>Overview</H2> 32 33<P> 34 Boost.Iostreams provides two components for working with line-ending conventions: the class template <A HREF="#newline_filter"><CODE>newline_filter</CODE></A> translates between line-ending conventions, and the class template <A HREF="#newline_checker"><CODE>newline_checker</CODE></A> verifies that a character sequence conforms to a given line-ending convention. 35</P> 36 37<A NAME="headers"></A> 38<H2>Headers</H2> 39 40<DL> 41 <DT><A CLASS="header" HREF="../../../../boost/iostreams/filter/newline.hpp"><CODE><boost/iostreams/filter/newline.hpp></CODE></A></DT> 42</DL> 43 44<A name="synopsis"></A> 45<H2>Synopsis</H2> 46 47<PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams { 48 49<SPAN CLASS="keyword">namespace</SPAN> <A CLASS="documented" HREF="#constants">newline</A> { 50 51<SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS='documented' HREF='#posix'>posix</A> = 1; <SPAN CLASS='comment'>// Use CR as line separator.</SPAN> 52<SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS="documented" HREF="#mac">mac</A> = 2; <SPAN CLASS='comment'>// Use LF as line separator.</SPAN> 53<SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS="documented" HREF="#dos">dos</A> = 4; <SPAN CLASS='comment'>// Use CRLF as line separator.</SPAN> 54<SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS="documented" HREF="#mixed">mixed</A> = 8; <SPAN CLASS='comment'>// Mixed line endings.</SPAN> 55<SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS="documented" HREF="#final_newline">final_newline</A> = 16; 56 57} <SPAN CLASS="comment">// End namespace boost::iostreams::newline</SPAN> 58 59<SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#newline_filter">newline_filter</A>; 60<SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#newline_checker">newline_checker</A>; 61<SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#newline_error">newline_error</A>; 62 63} } <SPAN CLASS="comment">// End namespace boost::io</SPAN></PRE> 64 65<A name="reference"></A> 66<H2>Reference</H2> 67 68<A name="constants"></A> 69<H3>1. Namespace <CODE>boost::iostreams::newline</CODE></H3> 70 71<P>The namespace <CODE>boost::iostreams::newline</CODE> contains integral constants used to configure <CODE>newline_filter</CODE>, <CODE>newline_checker</CODE> and to report errors. The constants have the following interpretations.</P> 72 73<TABLE STYLE="margin-left:2em; margin-bottom:2em" BORDER=1 CELLPADDING=4> 74<TR><TH>Constant</TH><TH>Interpretation</TH></TR> 75 <TR> 76 <TD VALIGN="top"><A NAME="posix"></A><CODE>posix</CODE></TD> 77 <TD> 78 Used to indicate POSIX line-ending conventions. 79 </TD> 80 </TR> 81 <TR> 82 <TD VALIGN="top"><A NAME="dos"></A><CODE>dos</CODE></TD> 83 <TD> 84 Used to indicate DOS line-ending conventions. 85 </TD> 86 </TR> 87 <TR> 88 <TD VALIGN="top"><A NAME="mac"></A><CODE>mac</CODE></TD> 89 <TD> 90 Used to indicate classic Mac line-ending conventions. 91 </TD> 92 </TR> 93 <TR> 94 <TD VALIGN="top"><A NAME="mixed"></A><CODE>mixed</CODE></TD> 95 <TD> 96 Used to describe a document with mixed line endings. 97 </TD> 98 </TR> 99 <TR> 100 <TD VALIGN="top"><A NAME="final_newline"></A><CODE>final_newline</CODE></TD> 101 <TD> 102 Used to indicate that a document ends in a newline sequence. 103 </TD> 104 </TR> 105</TABLE> 106 107<A name="newline_filter"></A> 108<H3>2. Class <CODE>newline_filter</CODE></H3> 109 110<H4>Description</H4> 111 112<P> 113 <A HREF="../concepts/dual_use_filter.html">DualUseFilter</A> 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. 114</P> 115 116<H4>Synopsis</H4> 117 118<PRE CLASS="broken_ie"><SPAN CLASS="keyword">class</SPAN> <SPAN CLASS="defined">newline_filter</SPAN> { 119<SPAN CLASS='keyword'>public:</SPAN> 120 <SPAN CLASS='keyword'>typedef</SPAN> char char_type; 121 <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN> category; 122 <SPAN CLASS='keyword'>explicit</SPAN> <A CLASS="documented" HREF="#newline_filter_ctor">newline_filter</A>(<SPAN CLASS='keyword'>int</SPAN> target); 123};</PRE> 124 125<A name="newline_filter_ctor"></A> 126<H4><CODE>newline_filter::newline_filter</CODE></H4> 127 128<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>explicit</SPAN> newline_filter(<SPAN CLASS='keyword'>int</SPAN> target);</PRE> 129 130<P>Constructs a newline_filter for converting to the specified format. The parameter target must be <A HREF='#posix'><CODE>newline::posix</CODE></A>, <A HREF='#dos'><CODE>newline::dos</CODE></A> or <A HREF='#mac'><CODE>newline::mac</CODE></A>.</P> 131 132<A name="newline_checker"></A> 133<H3>3. Class <CODE>newline_checker</CODE></H3> 134 135<H4>Description</H4> 136 137<P> 138 <A HREF="../concepts/dual_use_filter.html">DualUseFilter</A> used to verify that a character sequence conforms to a given line-ending convention. 139</P> 140 141<H4>Synopsis</H4> 142 143<PRE CLASS="broken_ie"><SPAN CLASS="keyword">class</SPAN> <SPAN CLASS="defined">newline_checker</SPAN> { 144<SPAN CLASS='keyword'>public:</SPAN> 145 <SPAN CLASS='keyword'>typedef</SPAN> char char_type; 146 <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN> category; 147 <SPAN CLASS='keyword'>explicit</SPAN> <A CLASS="documented" HREF="#newline_filter_ctor">newline_checker</A>(<SPAN CLASS='keyword'>int</SPAN> target = <SPAN CLASS='omitted'>default_value</SPAN> ); 148 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS='documented' HREF='#newline_checker_is_posix'>is_posix</A>() <SPAN CLASS='keyword'>const</SPAN>; 149 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_checker_is_dos">is_dos</A>() <SPAN CLASS='keyword'>const</SPAN>; 150 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_checker_is_mac">is_mac</A>() <SPAN CLASS='keyword'>const</SPAN>; 151 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_checker_is_mixed_posix">is_mixed_posix</A>() <SPAN CLASS='keyword'>const</SPAN>; 152 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_checker_is_mixed_dos">is_mixed_dos</A>() <SPAN CLASS='keyword'>const</SPAN>; 153 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_checker_is_mixed_mac">is_mixed_mac</A>() <SPAN CLASS='keyword'>const</SPAN>; 154 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_checker_is_mixed">is_mixed</A>() <SPAN CLASS='keyword'>const</SPAN>; 155 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_checker_has_final_newline">has_final_newline</A>() <SPAN CLASS='keyword'>const</SPAN>; 156};</PRE> 157 158<A name="newline_checker::newline_checker_ctor"></A> 159<H4><CODE>newline_checker::newline_checker</CODE></H4> 160 161<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>explicit</SPAN> newline_checker(<SPAN CLASS='keyword'>int</SPAN> target = <SPAN CLASS='omitted'>default_value</SPAN> );</PRE> 162 163<P>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 <A HREF='#posix'><CODE>newline::posix</CODE></A>, <A HREF='#dos'><CODE>newline::dos</CODE></A> or <A HREF='#mac'><CODE>newline::mac</CODE></A> or the bitwise OR of one of these values with <A HREF='#mac'><CODE>newline::final_newline</CODE></A>.</P> 164 165<P><B>Note:</B> If a <CODE>newline_checker</CODE> 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 <A HREF='../functions/close.html'>closed</A>. There are certain circumstances in which exceptions thrown by <A HREF='../functions/close.html'><CODE>close</CODE></A> are caught and ignored by the Iostreams library. Consequently, when performing output specifying <CODE>newline::final_newline</CODE> as part of <CODE>target</CODE> may have no effect. To check whether a character sequence ends with a newline sequence, call <A HREF='#newline_checker_has_final_newline'><CODE>has_final_newline</CODE></A> after the <CODE>newline_checker</CODE> has been closed. 166 167<A name="newline_checker_is_posix"></A> 168<H4><CODE>newline_checker::is_posix</CODE></H4> 169 170<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_posix() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 171 172<P>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.</P> 173 174<A name="newline_checker_is_dos"></A> 175<H4><CODE>newline_checker::is_dos</CODE></H4> 176 177<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_dos() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 178 179<P>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.</P> 180 181<A name="newline_checker_is_mac"></A> 182<H4><CODE>newline_checker::is_mac</CODE></H4> 183 184<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_mac() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 185 186<P>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.</P> 187 188<A name="newline_checker_is_mixed_posix"></A> 189<H4><CODE>newline_checker::is_mixed_posix</CODE></H4> 190 191<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_mixed_posix() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 192 193<P>Returns true if the characters examined so far contained at least one POSIX line-ending sequence.</P> 194 195<A name="newline_checker_is_mixed_dos"></A> 196<H4><CODE>newline_checker::is_mixed_dos</CODE></H4> 197 198<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_mixed_dos() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 199 200<P>Returns true if the characters examined so far contained at least one DOS line-ending sequence.</P> 201 202<A name="newline_checker_is_mixed_mac"></A> 203<H4><CODE>newline_checker::is_mixed_mac</CODE></H4> 204 205<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_mixed_mac() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 206 207<P>Returns true if the characters examined so far contained at least one classic Mac line-ending sequence.</P> 208 209<A name="newline_checker_is_mixed"></A> 210<H4><CODE>newline_checker::is_mixed</CODE></H4> 211 212<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_mixed() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 213 214<P>Returns true if the characters examined so far contained line-ending sequences of more than one type.</P> 215 216<A name="newline_checker_has_final_newline"></A> 217<H4><CODE>newline_checker::has_final_newline</CODE></H4> 218 219<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> has_final_newline() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 220 221<P>Returns <CODE>true</CODE> if this <CODE>newline_checker</CODE> has either been closed or has reached end-of-stream, and if the examined character sequence ended with a newline sequence.</P> 222 223<A name="newline_error"></A> 224<H3>4. Class template <CODE>newline_error</CODE></H3> 225 226<H4>Description</H4> 227 228<P>Used by <A HREF='#newline_checker'><CODE>newline_checker</CODE></A> to report errors.</P> 229 230<H4>Synopsis</H4> 231 232<PRE CLASS="broken_ie"><SPAN CLASS="keyword">class</SPAN> <SPAN CLASS="defined">newline_error</SPAN> : <SPAN CLASS="keyword">public</SPAN> std::ios_base::failure { 233<SPAN CLASS='keyword'>public:</SPAN> 234 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS='documented' HREF='#newline_error_is_posix'>is_posix</A>() <SPAN CLASS='keyword'>const</SPAN>; 235 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_error_is_dos">is_dos</A>() <SPAN CLASS='keyword'>const</SPAN>; 236 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_error_is_mac">is_mac</A>() <SPAN CLASS='keyword'>const</SPAN>; 237 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_error_is_mixed_posix">is_mixed_posix</A>() <SPAN CLASS='keyword'>const</SPAN>; 238 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_error_is_mixed_dos">is_mixed_dos</A>() <SPAN CLASS='keyword'>const</SPAN>; 239 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_error_is_mixed_mac">is_mixed_mac</A>() <SPAN CLASS='keyword'>const</SPAN>; 240 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_error_is_mixed">is_mixed</A>() <SPAN CLASS='keyword'>const</SPAN>; 241 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS="documented" HREF="#newline_error_has_final_newline">has_final_newline</A>() <SPAN CLASS='keyword'>const</SPAN>; 242};</PRE> 243 244<A name="newline_error_is_posix"></A> 245<H4><CODE>newline_error::is_posix</CODE></H4> 246 247<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_posix() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 248 249<P>Returns true if the characters examined by the <CODE>newline_checker</CODE> which threw this exception contained at least one POSIX line-ending sequence and no line-ending sequences of any other type.</P> 250 251<A name="newline_error_is_dos"></A> 252<H4><CODE>newline_error::is_dos</CODE></H4> 253 254<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_dos() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 255 256<P>Returns true if the characters examined by the <CODE>newline_checker</CODE> which threw this exception contained at least one DOS line-ending sequence and no line-ending sequences of any other type.</P> 257 258<A name="newline_error_is_mac"></A> 259<H4><CODE>newline_error::is_mac</CODE></H4> 260 261<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_mac() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 262 263<P>Returns true if the characters examined by the <CODE>newline_checker</CODE> which threw this exception contained at least one classic Mac line-ending sequence and no line-ending sequences of any other type.</P> 264 265<A name="newline_error_is_mixed_posix"></A> 266<H4><CODE>newline_error::is_mixed_posix</CODE></H4> 267 268<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_mixed_posix() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 269 270<P>Returns true if the characters examined by the <CODE>newline_checker</CODE> which threw this exception contained at least one POSIX line-ending sequence.</P> 271 272<A name="newline_error_is_mixed_dos"></A> 273<H4><CODE>newline_error::is_mixed_dos</CODE></H4> 274 275<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_mixed_dos() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 276 277<P>Returns true if the characters examined by the <CODE>newline_checker</CODE> which threw this exception contained at least one DOS line-ending sequence.</P> 278 279<A name="newline_error_is_mixed_mac"></A> 280<H4><CODE>newline_error::is_mixed_mac</CODE></H4> 281 282<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_mixed_mac() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 283 284<P>Returns true if the characters examined by the <CODE>newline_checker</CODE> which threw this exception contained at least one classic Mac line-ending sequence.</P> 285 286<A name="newline_error_is_mixed"></A> 287<H4><CODE>newline_error::is_mixed</CODE></H4> 288 289<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_mixed() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 290 291<P>Returns true if the characters examined by the <CODE>newline_checker</CODE> which threw this exception contained line-ending sequences of more than one type.</P> 292 293<A name="newline_error_has_final_newline"></A> 294<H4><CODE>newline_error::has_final_newline</CODE></H4> 295 296<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> has_final_newline() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 297 298<P>Returns <CODE>true</CODE> if the <CODE>newline_checker</CODE> which threw this exception was either closed or had reached end-of-stream and if the examined character sequence ended with a newline sequence.</P> 299 300<!-- Begin Footer --> 301 302<HR> 303 304<P CLASS="copyright">© Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>© Copyright 2004-2007 <a href="https://www.boost.org/users/people/jonathan_turkanis.html" target="_top">Jonathan Turkanis</a></P> 305<P CLASS="copyright"> 306 Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at <A HREF="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>) 307</P> 308 309<!-- End Footer --> 310 311</BODY>