QTextStream(3qt)

1QTextStream(3qt)                                              QTextStream(3qt)
2
3
4

NAME

6       QTextStream - Basic functions for reading and writing text using a
7       QIODevice
8

SYNOPSIS

10       All the functions in this class are reentrant when Qt is built with
11       thread support.</p>
12
13       #include <qtextstream.h>
14
15       Inherited by QTextIStream and QTextOStream.
16
17   Public Members
18       enum Encoding { Locale, Latin1, Unicode, UnicodeNetworkOrder,
19           UnicodeReverse, RawUnicode, UnicodeUTF8 }
20       void setEncoding ( Encoding e )
21       void setCodec ( QTextCodec * codec )
22       QTextCodec * codec ()
23       QTextStream ()
24       QTextStream ( QIODevice * iod )
25       QTextStream ( QString * str, int filemode )
26       QTextStream ( QString & str, int filemode )  (obsolete)
27       QTextStream ( QByteArray a, int mode )
28       QTextStream ( FILE * fh, int mode )
29       virtual ~QTextStream ()
30       QIODevice * device () const
31       void setDevice ( QIODevice * iod )
32       void unsetDevice ()
33       bool atEnd () const
34       bool eof () const  (obsolete)
35       QTextStream & operator>> ( QChar & c )
36       QTextStream & operator>> ( char & c )
37       QTextStream & operator>> ( signed short & i )
38       QTextStream & operator>> ( unsigned short & i )
39       QTextStream & operator>> ( signed int & i )
40       QTextStream & operator>> ( unsigned int & i )
41       QTextStream & operator>> ( signed long & i )
42       QTextStream & operator>> ( unsigned long & i )
43       QTextStream & operator>> ( float & f )
44       QTextStream & operator>> ( double & f )
45       QTextStream & operator>> ( char * s )
46       QTextStream & operator>> ( QString & str )
47       QTextStream & operator>> ( QCString & str )
48       QTextStream & operator<< ( QChar c )
49       QTextStream & operator<< ( char c )
50       QTextStream & operator<< ( signed short i )
51       QTextStream & operator<< ( unsigned short i )
52       QTextStream & operator<< ( signed int i )
53       QTextStream & operator<< ( unsigned int i )
54       QTextStream & operator<< ( signed long i )
55       QTextStream & operator<< ( unsigned long i )
56       QTextStream & operator<< ( float f )
57       QTextStream & operator<< ( double f )
58       QTextStream & operator<< ( const char * s )
59       QTextStream & operator<< ( const QString & s )
60       QTextStream & operator<< ( const QCString & s )
61       QTextStream & operator<< ( void * ptr )
62       QTextStream & readRawBytes ( char * s, uint len )
63       QTextStream & writeRawBytes ( const char * s, uint len )
64       QString readLine ()
65       QString read ()
66       void skipWhiteSpace ()
67       int flags () const
68       int flags ( int f )
69       int setf ( int bits )
70       int setf ( int bits, int mask )
71       int unsetf ( int bits )
72       void reset ()
73       int width () const
74       int width ( int w )
75       int fill () const
76       int fill ( int f )
77       int precision () const
78       int precision ( int p )
79

DESCRIPTION

81       The QTextStream class provides basic functions for reading and writing
82       text using a QIODevice.
83
84       The text stream class has a functional interface that is very similar
85       to that of the standard C++ iostream class.
86
87       Qt provides several global functions similar to the ones in iostream:
88       <center>.nf
89
90       </center>
91
92       Warning: By default QTextStream will automatically detect whether
93       integers in the stream are in decimal, octal, hexadecimal or binary
94       format when reading from the stream. In particular, a leading '0'
95       signifies octal, i.e. the sequence "0100" will be interpreted as 64.
96
97       The QTextStream class reads and writes text; it is not appropriate for
98       dealing with binary data (but QDataStream is).
99
100       By default, output of Unicode text (i.e. QString) is done using the
101       local 8-bit encoding. This can be changed using the setEncoding()
102       method. For input, the QTextStream will auto-detect standard Unicode
103       "byte order marked" text files; otherwise the local 8-bit encoding is
104       used.
105
106       The QIODevice is set in the constructor, or later using setDevice(). If
107       the end of the input is reached atEnd() returns TRUE. Data can be read
108       into variables of the appropriate type using the operator>>()
109       overloads, or read in its entirety into a single string using read(),
110       or read a line at a time using readLine(). Whitespace can be skipped
111       over using skipWhiteSpace(). You can set flags for the stream using
112       flags() or setf(). The stream also supports width(), precision() and
113       fill(); use reset() to reset the defaults.
114
115       See also QDataStream, Input/Output and Networking, and Text Related
116       Classes.
117
118   Member Type Documentation

QTextStream::Encoding

120       QTextStream::Locale
121
122       QTextStream::Latin1
123
124       QTextStream::Unicode
125
126       QTextStream::UnicodeNetworkOrder
127
128       QTextStream::UnicodeReverse
129
130       QTextStream::RawUnicode
131
132       QTextStream::UnicodeUTF8
133
134       See setEncoding() for an explanation of the encodings.
135

MEMBER FUNCTION DOCUMENTATION

QTextStream::QTextStream ()

138       Constructs a data stream that has no IO device.
139

QTextStream::QTextStream ( QIODevice * iod )

141       Constructs a text stream that uses the IO device iod.
142

QTextStream::QTextStream ( QString * str, int filemode )

144       Constructs a text stream that operates on the Unicode QString, str,
145       through an internal device. The filemode argument is passed to the
146       device's open() function; see QIODevice::mode().
147
148       If you set an encoding or codec with setEncoding() or setCodec(), this
149       setting is ignored for text streams that operate on QString.
150
151       Example:
152
153           QString str;
154           QTextStream ts( &str, IO_WriteOnly );
155           ts << "pi = " << 3.14; // str == "pi = 3.14"
156
157       Writing data to the text stream will modify the contents of the string.
158       The string will be expanded when data is written beyond the end of the
159       string. Note that the string will not be truncated:
160
161           QString str = "pi = 3.14";
162           QTextStream ts( &str, IO_WriteOnly );
163           ts <<  "2+2 = " << 2+2; // str == "2+2 = 414"
164
165       Note that because QString is Unicode, you should not use readRawBytes()
166       or writeRawBytes() on such a stream.
167

QTextStream::QTextStream ( QString & str, int filemode )

169       This function is obsolete. It is provided to keep old source working.
170       We strongly advise against using it in new code.
171
172       This constructor is equivalent to the constructor taking a QString*
173       parameter.
174

QTextStream::QTextStream ( QByteArray a, int mode )

176       Constructs a text stream that operates on the byte array, a, through an
177       internal QBuffer device. The mode argument is passed to the device's
178       open() function; see QIODevice::mode().
179
180       Example:
181
182           QByteArray array;
183           QTextStream ts( array, IO_WriteOnly );
184           ts << "pi = " << 3.14 << '\0'; // array == "pi = 3.14"
185
186       Writing data to the text stream will modify the contents of the array.
187       The array will be expanded when data is written beyond the end of the
188       string.
189
190       Same example, using a QBuffer:
191
192           QByteArray array;
193           QBuffer buf( array );
194           buf.open( IO_WriteOnly );
195           QTextStream ts( &buf );
196           ts << "pi = " << 3.14 << '\0'; // array == "pi = 3.14"
197           buf.close();
198

QTextStream::QTextStream ( FILE * fh, int mode )

200       Constructs a text stream that operates on an existing file handle fh
201       through an internal QFile device. The mode argument is passed to the
202       device's open() function; see QIODevice::mode().
203
204       Note that if you create a QTextStream cout or another name that is also
205       used for another variable of a different type, some linkers may confuse
206       the two variables, which will often cause crashes.
207

QTextStream::~QTextStream () [virtual]

209       Destroys the text stream.
210
211       The destructor does not affect the current IO device.
212

bool QTextStream::atEnd () const

214       Returns TRUE if the IO device has reached the end position (end of the
215       stream or file) or if there is no IO device set; otherwise returns
216       FALSE.
217
218       See also QIODevice::atEnd().
219
220       Examples:
221

QTextCodec * QTextStream::codec ()

223       Returns the codec actually used for this stream.
224
225       If Unicode is automatically detected in input, a codec with name()
226       "ISO-10646-UCS-2" is returned.
227
228       See also setCodec().
229

QIODevice * QTextStream::device () const

231       Returns the IO device currently set.
232
233       See also setDevice() and unsetDevice().
234

bool QTextStream::eof () const

236       This function is obsolete. It is provided to keep old source working.
237       We strongly advise against using it in new code.
238
239       This function has been renamed to atEnd().
240
241       See also QIODevice::atEnd().
242
243       Example: chart/chartform_files.cpp.
244

int QTextStream::fill () const

246       Returns the fill character. The default value is ' ' (space).
247

int QTextStream::fill ( int f )

249       This is an overloaded member function, provided for convenience. It
250       behaves essentially like the above function.
251
252       Sets the fill character to f. Returns the previous fill character.
253

int QTextStream::flags () const

255       Returns the current stream flags. The default value is 0.
256
257       <center>.nf
258
259       Flag
260       ─────
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276       </center>
277
278       Note that unless bin, oct, dec, or hex is set, the input base is octal
279       if the value starts with 0, hexadecimal if it starts with 0x, binary if
280       it starts with 0b, and decimal otherwise.
281
282       See also setf() and unsetf().
283

int QTextStream::flags ( int f )

285       This is an overloaded member function, provided for convenience. It
286       behaves essentially like the above function.
287
288       Sets the stream flags to f. Returns the previous stream flags.
289
290       See also setf() and unsetf().
291

QTextStream & QTextStream::operator<< ( QChar c )

293       Writes character char to the stream and returns a reference to the
294       stream.
295
296       The character c is assumed to be Latin1 encoded independent of the
297       Encoding set for the QTextStream.
298

QTextStream & QTextStream::operator<< ( char c )

300       This is an overloaded member function, provided for convenience. It
301       behaves essentially like the above function.
302
303       Writes character c to the stream and returns a reference to the stream.
304

QTextStream & QTextStream::operator<< ( signed short i )

306       This is an overloaded member function, provided for convenience. It
307       behaves essentially like the above function.
308
309       Writes a short integer i to the stream and returns a reference to the
310       stream.
311

QTextStream & QTextStream::operator<< ( unsigned short i )

313       This is an overloaded member function, provided for convenience. It
314       behaves essentially like the above function.
315
316       Writes an unsigned short integer i to the stream and returns a
317       reference to the stream.
318

QTextStream & QTextStream::operator<< ( signed int i )

320       This is an overloaded member function, provided for convenience. It
321       behaves essentially like the above function.
322
323       Writes an int i to the stream and returns a reference to the stream.
324

QTextStream & QTextStream::operator<< ( unsigned int i )

326       This is an overloaded member function, provided for convenience. It
327       behaves essentially like the above function.
328
329       Writes an unsigned int i to the stream and returns a reference to the
330       stream.
331

QTextStream & QTextStream::operator<< ( signed long i )

333       This is an overloaded member function, provided for convenience. It
334       behaves essentially like the above function.
335
336       Writes a long int i to the stream and returns a reference to the
337       stream.
338

QTextStream & QTextStream::operator<< ( unsigned long i )

340       This is an overloaded member function, provided for convenience. It
341       behaves essentially like the above function.
342
343       Writes an unsigned long int i to the stream and returns a reference to
344       the stream.
345

QTextStream & QTextStream::operator<< ( float f )

347       This is an overloaded member function, provided for convenience. It
348       behaves essentially like the above function.
349
350       Writes a float f to the stream and returns a reference to the stream.
351

QTextStream & QTextStream::operator<< ( double f )

353       This is an overloaded member function, provided for convenience. It
354       behaves essentially like the above function.
355
356       Writes a double f to the stream and returns a reference to the stream.
357

QTextStream & QTextStream::operator<< ( const char * s )

359       This is an overloaded member function, provided for convenience. It
360       behaves essentially like the above function.
361
362       Writes a string to the stream and returns a reference to the stream.
363
364       The string s is assumed to be Latin1 encoded independent of the
365       Encoding set for the QTextStream.
366

QTextStream & QTextStream::operator<< ( const QString & s )

368       This is an overloaded member function, provided for convenience. It
369       behaves essentially like the above function.
370
371       Writes s to the stream and returns a reference to the stream.
372

QTextStream & QTextStream::operator<< ( const QCString & s )

374       This is an overloaded member function, provided for convenience. It
375       behaves essentially like the above function.
376
377       Writes s to the stream and returns a reference to the stream.
378
379       The string s is assumed to be Latin1 encoded independent of the
380       Encoding set for the QTextStream.
381

QTextStream & QTextStream::operator<< ( void * ptr )

383       This is an overloaded member function, provided for convenience. It
384       behaves essentially like the above function.
385
386       Writes a pointer to the stream and returns a reference to the stream.
387
388       The ptr is output as an unsigned long hexadecimal integer.
389

QTextStream & QTextStream::operator>> ( QChar & c )

391       Reads a char c from the stream and returns a reference to the stream.
392       Note that whitespace is not skipped.
393

QTextStream & QTextStream::operator>> ( char & c )

395       This is an overloaded member function, provided for convenience. It
396       behaves essentially like the above function.
397
398       Reads a char c from the stream and returns a reference to the stream.
399       Note that whitespace is skipped.
400

QTextStream & QTextStream::operator>> ( signed short & i )

402       This is an overloaded member function, provided for convenience. It
403       behaves essentially like the above function.
404
405       Reads a signed short integer i from the stream and returns a reference
406       to the stream. See flags() for an explanation of the expected input
407       format.
408

QTextStream & QTextStream::operator>> ( unsigned short & i )

410       This is an overloaded member function, provided for convenience. It
411       behaves essentially like the above function.
412
413       Reads an unsigned short integer i from the stream and returns a
414       reference to the stream. See flags() for an explanation of the expected
415       input format.
416

QTextStream & QTextStream::operator>> ( signed int & i )

418       This is an overloaded member function, provided for convenience. It
419       behaves essentially like the above function.
420
421       Reads a signed int i from the stream and returns a reference to the
422       stream. See flags() for an explanation of the expected input format.
423

QTextStream & QTextStream::operator>> ( unsigned int & i )

425       This is an overloaded member function, provided for convenience. It
426       behaves essentially like the above function.
427
428       Reads an unsigned int i from the stream and returns a reference to the
429       stream. See flags() for an explanation of the expected input format.
430

QTextStream & QTextStream::operator>> ( signed long & i )

432       This is an overloaded member function, provided for convenience. It
433       behaves essentially like the above function.
434
435       Reads a signed long int i from the stream and returns a reference to
436       the stream. See flags() for an explanation of the expected input
437       format.
438

QTextStream & QTextStream::operator>> ( unsigned long & i )

440       This is an overloaded member function, provided for convenience. It
441       behaves essentially like the above function.
442
443       Reads an unsigned long int i from the stream and returns a reference to
444       the stream. See flags() for an explanation of the expected input
445       format.
446

QTextStream & QTextStream::operator>> ( float & f )

448       This is an overloaded member function, provided for convenience. It
449       behaves essentially like the above function.
450
451       Reads a float f from the stream and returns a reference to the stream.
452       See flags() for an explanation of the expected input format.
453

QTextStream & QTextStream::operator>> ( double & f )

455       This is an overloaded member function, provided for convenience. It
456       behaves essentially like the above function.
457
458       Reads a double f from the stream and returns a reference to the stream.
459       See flags() for an explanation of the expected input format.
460

QTextStream & QTextStream::operator>> ( char * s )

462       This is an overloaded member function, provided for convenience. It
463       behaves essentially like the above function.
464
465       Reads a "word" from the stream into s and returns a reference to the
466       stream.
467
468       A word consists of characters for which isspace() returns FALSE.
469

QTextStream & QTextStream::operator>> ( QString & str )

471       This is an overloaded member function, provided for convenience. It
472       behaves essentially like the above function.
473
474       Reads a "word" from the stream into str and returns a reference to the
475       stream.
476
477       A word consists of characters for which isspace() returns FALSE.
478

QTextStream & QTextStream::operator>> ( QCString & str )

480       This is an overloaded member function, provided for convenience. It
481       behaves essentially like the above function.
482
483       Reads a "word" from the stream into str and returns a reference to the
484       stream.
485
486       A word consists of characters for which isspace() returns FALSE.
487

int QTextStream::precision () const

489       Returns the precision. The default value is 6.
490

int QTextStream::precision ( int p )

492       This is an overloaded member function, provided for convenience. It
493       behaves essentially like the above function.
494
495       Sets the precision to p. Returns the previous precision setting.
496

QString QTextStream::read ()

498       Reads the entire stream from the current position, and returns a string
499       containing the text.
500
501       See also QIODevice::readLine().
502
503       Examples:
504

QString QTextStream::readLine ()

506       Reads a line from the stream and returns a string containing the text.
507
508       The returned string does not contain any trailing newline or carriage
509       return. Note that this is different from QIODevice::readLine(), which
510       does not strip the newline at the end of the line.
511
512       On EOF you will get a QString that is null. On reading an empty line
513       the returned QString is empty but not null.
514
515       See also QIODevice::readLine().
516
517       Examples:
518

QTextStream & QTextStream::readRawBytes ( char * s, uint len )

520       Reads len bytes from the stream into s and returns a reference to the
521       stream.
522
523       The buffer s must be preallocated.
524
525       Note that no encoding is done by this function.
526
527       Warning: The behavior of this function is undefined unless the stream's
528       encoding is set to Unicode or Latin1.
529
530       See also QIODevice::readBlock().
531

void QTextStream::reset ()

533       Resets the text stream.
534
535       All flags are set to 0.
536
537       The field width is set to 0.
538
539       The fill character is set to ' ' (Space).
540
541       The precision is set to 6.
542
543       See also setf(), width(), fill(), and precision().
544

void QTextStream::setCodec ( QTextCodec * codec )

546       Sets the codec for this stream to codec. Will not try to autodetect
547       Unicode.
548
549       Note that this function should be called before any data is read
550       to/written from the stream.
551
552       See also setEncoding() and codec().
553
554       Example: qwerty/qwerty.cpp.
555

void QTextStream::setDevice ( QIODevice * iod )

557       Sets the IO device to iod.
558
559       See also device() and unsetDevice().
560

void QTextStream::setEncoding ( Encoding e )

562       Sets the encoding of this stream to e, where e is one of the following
563       values: <center>.nf
564
565       </center>
566
567       Locale and all Unicode encodings, except RawUnicode, will look at the
568       first two bytes in an input stream to determine the byte order. The
569       initial byte order marker will be stripped off before data is read.
570
571       Note that this function should be called before any data is read to or
572       written from the stream.
573
574       See also setCodec().
575
576       Examples:
577

int QTextStream::setf ( int bits )

579       Sets the stream flag bits bits. Returns the previous stream flags.
580
581       Equivalent to flags( flags() | bits ).
582
583       See also unsetf().
584

int QTextStream::setf ( int bits, int mask )

586       This is an overloaded member function, provided for convenience. It
587       behaves essentially like the above function.
588
589       Sets the stream flag bits bits with a bit mask mask. Returns the
590       previous stream flags.
591
592       Equivalent to flags( (flags() & ~mask) | (bits & mask) ).
593
594       See also unsetf().
595

void QTextStream::skipWhiteSpace ()

597       Positions the read pointer at the first non-whitespace character.
598

void QTextStream::unsetDevice ()

600       Unsets the IO device. Equivalent to setDevice( 0 ).
601
602       See also device() and setDevice().
603

int QTextStream::unsetf ( int bits )

605       Clears the stream flag bits bits. Returns the previous stream flags.
606
607       Equivalent to flags( flags() & ~mask ).
608
609       See also setf().
610

int QTextStream::width () const

612       Returns the field width. The default value is 0.
613

int QTextStream::width ( int w )

615       This is an overloaded member function, provided for convenience. It
616       behaves essentially like the above function.
617
618       Sets the field width to w. Returns the previous field width.
619

QTextStream & QTextStream::writeRawBytes ( const char * s, uint len )

621       Writes the len bytes from s to the stream and returns a reference to
622       the stream.
623
624       Note that no encoding is done by this function.
625
626       See also QIODevice::writeBlock().
627
628

COPYRIGHT

634       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
635       license file included in the distribution for a complete license
636       statement.
637

AUTHOR

639       Generated automatically from the source code.
640

BUGS

642       If you find a bug in Qt, please report it as described in
643       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
644       help you. Thank you.
645
646       The definitive Qt documentation is provided in HTML format; it is
647       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
648       web browser. This man page is provided as a convenience for those users
649       who prefer man pages, although this format is not officially supported
650       by Trolltech.
651
652       If you find errors in this manual page, please report them to qt-
653       bugs@trolltech.com.  Please include the name of the manual page
654       (qtextstream.3qt) and the Qt version (3.3.8).
655
656
657
658Trolltech AS                    2 February 2007               QTextStream(3qt)