ceph/src/boost/libs/iostreams/doc/classes/newline_filter.html

   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>&lt;boost/iostreams/filter/newline.hpp&gt;</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">&copy; Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>&copy; Copyright 2004-2007 <a href="http://www.coderage.com/turkanis/" 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>