|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.trolltech.qt.QSignalEmitter
com.trolltech.qt.QtJambiObject
com.trolltech.qt.core.QTextStream
public class QTextStream
The QTextStream class provides a convenient interface for reading and writing text.
QTextStream can operate on a QIODevice, a QByteArray or a QString. Using QTextStream's streaming operators, you can conveniently read and write words, lines and numbers. For generating text, QTextStream supports formatting options for field padding and alignment, and formatting of numbers. Example:
QFile data("output.txt");
if (data.open(QFile::WriteOnly | QFile::Truncate)) {
QTextStream out(&data);
out << "Result: " << qSetFieldWidth(10) << left << 3.14 << 2.7 << endl;
// writes "Result: 3.14 2.7 \n"
}
It's also common to use QTextStream to read console input and write console output. QTextStream is locale aware, and will automatically decode standard input using the correct codec. Example:
QTextStream stream(stdin); QString line; do { line = stream.readLine(); } while (!line.isNull());
Note that you cannot use QTextStream::atEnd(), which returns true when you have reached the end of the data stream, with stdin.
Besides using QTextStream's constructors, you can also set the device or string QTextStream operates on by calling setDevice or setString(). You can seek to a position by calling seek, and atEnd will return true when there is no data left to be read. If you call flush, QTextStream will empty all data from its write buffer into the device and call flush on the device.
Internally, QTextStream uses a Unicode based buffer, and QTextCodec is used by QTextStream to automatically support different character sets. By default, QTextCodec::codecForLocale() is used for reading and writing, but you can also set the codec by calling setCodec. Automatic Unicode detection is also supported. When this feature is enabled (the default behavior), QTextStream will detect the UTF-16 BOM (Byte Order Mark) and switch to the appropriate UTF-16 codec when reading. QTextStream does not write a BOM by default, but you can enable this by calling setGenerateByteOrderMark(true). When QTextStream operates on a QString directly, the codec is disabled.
There are three general ways to use QTextStream when reading text files:
Since the text stream uses a buffer, you should not read from the stream using the implementation of a superclass. For instance, if you have a QFile and read from it directly using QFile::readLine() instead of using the stream, the text stream's internal position will be out of sync with the file's position.
By default, when reading numbers from a stream of text, QTextStream will automatically detect the number's base representation. For example, if the number starts with "0x", it is assumed to be in hexadecimal form. If it starts with the digits 1-9, it is assumed to be in decimal form, and so on. You can set the integer base, thereby disabling the automatic detection, by calling setIntegerBase. Example:
QTextStream in("0x50 0x20"); int firstNumber, secondNumber; in >> firstNumber; // firstNumber == 80 in >> dec >> secondNumber; // secondNumber == 0 char ch; in >> ch; // ch == 'x'
QTextStream supports many formatting options for generating text. You can set the field width and pad character by calling setFieldWidth and setPadChar. Use setFieldAlignment to set the alignment within each field. For real numbers, call setRealNumberNotation and setRealNumberPrecision to set the notation (SmartNotation, ScientificNotation, FixedNotation) and precision in digits of the generated number. Some extra number formatting options are also available through setNumberFlags.
Like <iostream> in the standard C++ library, QTextStream also defines several global manipulator functions:
In addition, Qt provides three global manipulators that take a parameter: qSetFieldWidth(), qSetPadChar(), and qSetRealNumberPrecision().
Example
Nested Class Summary | |
---|---|
static class |
QTextStream.FieldAlignment
This enum specifies how to align text in fields when the field is wider than the text that occupies it. |
static class |
QTextStream.NumberFlag
This enum specifies various flags that can be set to affect the output of integers, floats, and doubles. |
static class |
QTextStream.NumberFlags
This QFlag class provides flags for the int enum. |
static class |
QTextStream.RealNumberNotation
This enum specifies which notations to use for expressing float and double as strings. |
static class |
QTextStream.Status
This enum describes the current status of the text stream. |
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter |
---|
QSignalEmitter.Signal0, QSignalEmitter.Signal1<A>, QSignalEmitter.Signal2<A,B>, QSignalEmitter.Signal3<A,B,C>, QSignalEmitter.Signal4<A,B,C,D>, QSignalEmitter.Signal5<A,B,C,D,E>, QSignalEmitter.Signal6<A,B,C,D,E,F>, QSignalEmitter.Signal7<A,B,C,D,E,F,G>, QSignalEmitter.Signal8<A,B,C,D,E,F,G,H>, QSignalEmitter.Signal9<A,B,C,D,E,F,G,H,I> |
Constructor Summary | |
---|---|
QTextStream()
Constructs a QTextStream. |
|
QTextStream(QByteArray array)
Equivalent to QTextStream(array, QIODevice::ReadOnly). |
|
QTextStream(QByteArray array,
QIODevice.OpenMode openMode)
Constructs a QTextStream that operates on array, using openMode to define the open mode. |
|
QTextStream(QIODevice device)
Constructs a QTextStream that operates on device. |
Method Summary | |
---|---|
boolean |
atEnd()
Returns true if there is no more data to be read from the QTextStream; otherwise returns false. |
boolean |
autoDetectUnicode()
Returns true if automatic Unicode detection is enabled; otherwise returns false. |
QTextCodec |
codec()
Returns the codec that is current assigned to the stream. |
QIODevice |
device()
Returns the current device associated with the QTextStream, or 0 if no device has been assigned. |
QTextStream.FieldAlignment |
fieldAlignment()
Returns the current field alignment. |
int |
fieldWidth()
Returns the current field width. |
void |
flush()
Flushes any buffered data waiting to be written to the device. |
static QTextStream |
fromNativePointer(QNativePointer nativePointer)
This function returns the QTextStream instance pointed to by nativePointer |
boolean |
generateByteOrderMark()
Returns true if QTextStream is set to generate the UTF-16 BOM (Byte Order Mark) when using a UTF-16 codec; otherwise returns false. |
int |
integerBase()
Returns the current base of integers. |
QTextStream.NumberFlags |
numberFlags()
Returns the current number flags. |
char |
padChar()
Returns the current pad character. |
long |
pos()
Returns the device position corresponding to the current position of the stream, or -1 if an error occurs (e.g., if there is no device or string, or if there's a device error). |
java.lang.String |
read(long maxlen)
Reads at most maxlen characters from the stream, and returns the data read as a QString. |
java.lang.String |
readAll()
Reads the entire content of the stream, and returns it as a QString. |
byte |
readByte()
Reads a byte from the stream. |
double |
readDouble()
Reads a double from the stream. |
float |
readFloat()
Reads a float from the stream. |
int |
readInt()
Reads an int from the stream. |
java.lang.String |
readLine()
Equivalent to readLine(0). |
java.lang.String |
readLine(long maxlen)
Reads one line of text from the stream, and returns it as a QString. |
long |
readLong()
Reads a long from the stream. |
short |
readShort()
Reads a short from the stream |
java.lang.String |
readString()
Reads a String from the stream. |
QTextStream.RealNumberNotation |
realNumberNotation()
Returns the current real number notation. |
int |
realNumberPrecision()
Returns the current real number precision, or the number of fraction digits QTextStream will write when generating real numbers. |
void |
reset()
Resets QTextStream's formatting options, bringing it back to its original constructed state. |
void |
resetStatus()
Resets the status of the text stream. |
boolean |
seek(long pos)
Seeks to the position pos in the device. |
void |
setAutoDetectUnicode(boolean enabled)
If enabled is true, QTextStream will attempt to detect Unicode encoding by peeking into the stream data to see if it can find the UTF-16 BOM (Byte Order Mark). |
void |
setCodec(QTextCodec codec)
Sets the codec for this stream to codec. |
void |
setCodec(java.lang.String codecName)
Sets the codec for this stream to the QTextCodec for the encoding specified by codecName. |
void |
setDevice(QIODevice device)
Sets the current device to device. |
void |
setFieldAlignment(QTextStream.FieldAlignment alignment)
Sets the field alignment to alignment. |
void |
setFieldWidth(int width)
Sets the current field width to width. |
void |
setGenerateByteOrderMark(boolean generate)
If generate is true and a UTF-16 codec is used, QTextStream will insert the BOM (Byte Order Mark) before any data has been written to the device. |
void |
setIntegerBase(int base)
Sets the base of integers to base, both for reading and for generating numbers. |
void |
setNumberFlags(QTextStream.NumberFlag... flags)
Sets the current number flags to flags. |
void |
setNumberFlags(QTextStream.NumberFlags flags)
Sets the current number flags to flags. |
void |
setPadChar(char ch)
Sets the pad character to ch. |
void |
setRealNumberNotation(QTextStream.RealNumberNotation notation)
Sets the real number notation to notation (SmartNotation, FixedNotation, ScientificNotation). |
void |
setRealNumberPrecision(int precision)
Sets the precision of real numbers to precision. |
void |
setStatus(QTextStream.Status status)
Sets the status of the text stream to the status given. |
void |
skipWhiteSpace()
Reads and discards whitespace from the stream until either a non-space character is detected, or until atEnd returns true. |
QTextStream.Status |
status()
Returns the status of the text stream. |
QTextStream |
writeBoolean(boolean b)
This method is used internally by Qt Jambi. |
QTextStream |
writeByte(byte ch)
Converts ch from ASCII to a QChar, then writes it to the stream. |
QTextStream |
writeDouble(double f)
Writes the double f to the stream. |
QTextStream |
writeFloat(float f)
Writes the real number f to the stream, then returns a reference to the QTextStream. |
QTextStream |
writeInt(int i)
Writes the signed int i to the stream. |
QTextStream |
writeLong(long i)
Writes the qlonglong i to the stream. |
QTextStream |
writeShort(short s)
Writes s to the stream. |
void |
writeString(java.lang.String string)
Writes string to the stream. |
Methods inherited from class com.trolltech.qt.QtJambiObject |
---|
dispose, disposed, finalize, reassignNativeResources, tr, tr, tr |
Methods inherited from class com.trolltech.qt.QSignalEmitter |
---|
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread |
Methods inherited from class java.lang.Object |
---|
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Methods inherited from interface com.trolltech.qt.QtJambiInterface |
---|
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership |
Constructor Detail |
---|
public QTextStream(QIODevice device)
Constructs a QTextStream that operates on device.
public QTextStream()
Constructs a QTextStream. Before you can use it for reading or writing, you must assign a device or a string.
public QTextStream(QByteArray array)
Equivalent to QTextStream(array, QIODevice::ReadOnly).
public QTextStream(QByteArray array, QIODevice.OpenMode openMode)
Constructs a QTextStream that operates on array, using openMode to define the open mode. The array is accessed as read-only, regardless of the values in openMode.
This constructor is convenient for working on constant strings. Example:
int main(int argc, char *argv[])
{
// read numeric arguments (123, 0x20, 4.5...)
for (int i = 1; i < argc; ++i) {
int number;
QTextStream in(argv[i]);
in >> number;
...
}
}
Method Detail |
---|
public final boolean atEnd()
Returns true if there is no more data to be read from the QTextStream; otherwise returns false. This is similar to, but not the same as calling QIODevice::atEnd(), as QTextStream also takes into account its internal Unicode buffer.
public final boolean autoDetectUnicode()
Returns true if automatic Unicode detection is enabled; otherwise returns false.
public final QTextCodec codec()
Returns the codec that is current assigned to the stream.
public final QIODevice device()
Returns the current device associated with the QTextStream, or 0 if no device has been assigned.
public final QTextStream.FieldAlignment fieldAlignment()
Returns the current field alignment.
public final int fieldWidth()
Returns the current field width.
public final void flush()
Flushes any buffered data waiting to be written to the device.
If QTextStream operates on a string, this function does nothing.
public final boolean generateByteOrderMark()
Returns true if QTextStream is set to generate the UTF-16 BOM (Byte Order Mark) when using a UTF-16 codec; otherwise returns false.
public final int integerBase()
Returns the current base of integers. 0 means that the base is detected when reading, or 10 (decimal) when generating numbers.
public final QTextStream.NumberFlags numberFlags()
Returns the current number flags.
public final QTextStream writeByte(byte ch)
Converts ch from ASCII to a QChar, then writes it to the stream.
public final QTextStream writeLong(long i)
Writes the qlonglong i to the stream.
public final QTextStream writeInt(int i)
Writes the signed int i to the stream.
public final QTextStream writeDouble(double f)
Writes the double f to the stream.
public final QTextStream writeBoolean(boolean b)
This method is used internally by Qt Jambi. Do not use it in your applications.
public final QTextStream writeFloat(float f)
Writes the real number f to the stream, then returns a reference to the QTextStream. By default, QTextStream stores it using SmartNotation, with up to 6 digits of precision. You can change the textual representation QTextStream will use for real numbers by calling setRealNumberNotation, setRealNumberPrecision and setNumberFlags.
public final char padChar()
Returns the current pad character.
public final long pos()
Returns the device position corresponding to the current position of the stream, or -1 if an error occurs (e.g., if there is no device or string, or if there's a device error).
Because QTextStream is buffered, this function may have to seek the device to reconstruct a valid device position. This operation can be expensive, so you may want to avoid calling this function in a tight loop.
public final java.lang.String read(long maxlen)
Reads at most maxlen characters from the stream, and returns the data read as a QString.
public final java.lang.String readAll()
Reads the entire content of the stream, and returns it as a QString. Avoid this function when working on large files, as it will consume a significant amount of memory.
Calling readLine is better if you do not know how much data is available.
public final java.lang.String readLine()
Equivalent to readLine(0).
public final java.lang.String readLine(long maxlen)
Reads one line of text from the stream, and returns it as a QString. The maximum allowed line length is set to maxlen. If the stream contains lines longer than this, then the lines will be split after maxlen characters and returned in parts.
If maxlen is 0, the lines can be of any length. A common value for maxlen is 75.
The returned line has no trailing end-of-line characters ("\n" or "\r\n"), so calling QString::trimmed() is unnecessary.
If the stream has read to the end of the file, readLine will return a null QString. For strings, or for devices that support it, you can explicitly test for the end of the stream using atEnd.
public final QTextStream.RealNumberNotation realNumberNotation()
Returns the current real number notation.
public final int realNumberPrecision()
Returns the current real number precision, or the number of fraction digits QTextStream will write when generating real numbers.
public final void reset()
Resets QTextStream's formatting options, bringing it back to its original constructed state. The device, string and any buffered data is left untouched.
public final void resetStatus()
Resets the status of the text stream.
public final boolean seek(long pos)
Seeks to the position pos in the device. Returns true on success; otherwise returns false.
public final void setAutoDetectUnicode(boolean enabled)
If enabled is true, QTextStream will attempt to detect Unicode encoding by peeking into the stream data to see if it can find the UTF-16 BOM (Byte Order Mark). If this mark is found, QTextStream will replace the current codec with the UTF-16 codec.
This function can be used together with setCodec. It is common to set the codec to UTF-8, and then enable UTF-16 detection.
public final void setCodec(QTextCodec codec)
Sets the codec for this stream to codec. The codec is used for decoding any data that is read from the assigned device, and for encoding any data that is written. By default, QTextCodec::codecForLocale() is used, and automatic unicode detection is enabled.
If QTextStream operates on a string, this function does nothing.
public final void setDevice(QIODevice device)
Sets the current device to device. If a device has already been assigned, QTextStream will call flush before the old device is replaced.
public final void setFieldAlignment(QTextStream.FieldAlignment alignment)
Sets the field alignment to alignment. When used together with setFieldWidth, this function allows you to generate formatted output with text aligned to the left, to the right or center aligned.
public final void setFieldWidth(int width)
Sets the current field width to width. If width is 0 (the default), the field width is equal to the length of the generated text.
public final void setGenerateByteOrderMark(boolean generate)
If generate is true and a UTF-16 codec is used, QTextStream will insert the BOM (Byte Order Mark) before any data has been written to the device. If generate is false, no BOM will be inserted. This function must be called before any data is written. Otherwise, it does nothing.
public final void setIntegerBase(int base)
Sets the base of integers to base, both for reading and for generating numbers. base can be either 2 (binary), 8 (octal), 10 (decimal) or 16 (hexadecimal). If base is 0, QTextStream will attempt to detect the base by inspecting the data on the stream. When generating numbers, QTextStream assumes base is 10 unless the base has been set explicitly.
public final void setNumberFlags(QTextStream.NumberFlag... flags)
Sets the current number flags to flags. flags is a set of flags from the NumberFlag enum, and describes options for formatting generated code (e.g., whether or not to always write the base or sign of a number).
public final void setNumberFlags(QTextStream.NumberFlags flags)
Sets the current number flags to flags. flags is a set of flags from the NumberFlag enum, and describes options for formatting generated code (e.g., whether or not to always write the base or sign of a number).
public final void setPadChar(char ch)
Sets the pad character to ch. The default value is the ASCII space character (' '), or QChar(0x20). This character is used to fill in the space in fields when generating text.
Example:
QString s; QTextStream out(&s); out.setFieldWidth(10); out.setPadChar('-'); out << "Qt" << endl << "rocks!" << endl;
Output:
----Qt---- --rocks!--
public final void setRealNumberNotation(QTextStream.RealNumberNotation notation)
Sets the real number notation to notation (SmartNotation, FixedNotation, ScientificNotation). When reading and generating numbers, QTextStream uses this value to detect the formatting of real numbers.
public final void setRealNumberPrecision(int precision)
Sets the precision of real numbers to precision. This value describes the number of fraction digits QTextStream should write when generating real numbers.
public final void setStatus(QTextStream.Status status)
Sets the status of the text stream to the status given.
public final void skipWhiteSpace()
Reads and discards whitespace from the stream until either a non-space character is detected, or until atEnd returns true. This function is useful when reading a stream character by character.
Whitespace characters are all characters for which QChar::isSpace() returns true.
public final QTextStream.Status status()
Returns the status of the text stream.
public static QTextStream fromNativePointer(QNativePointer nativePointer)
nativePointer
- the QNativePointer of which object should be returned.public final void setCodec(java.lang.String codecName)
Example:
QTextStream out(&file);
out.setCodec("UTF-8");
public final byte readByte()
public final short readShort()
public final int readInt()
public final long readLong()
public final float readFloat()
public final double readDouble()
public final QTextStream writeShort(short s)
public final java.lang.String readString()
public final void writeString(java.lang.String string)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |