1/**************************************************************************** 2** 3** Copyright (C) 2016 The Qt Company Ltd. 4** Contact: https://www.qt.io/licensing/ 5** 6** This file is part of the documentation of the Qt Toolkit. 7** 8** $QT_BEGIN_LICENSE:FDL$ 9** Commercial License Usage 10** Licensees holding valid commercial Qt licenses may use this file in 11** accordance with the commercial license agreement provided with the 12** Software or, alternatively, in accordance with the terms contained in 13** a written agreement between you and The Qt Company. For licensing terms 14** and conditions see https://www.qt.io/terms-conditions. For further 15** information use the contact form at https://www.qt.io/contact-us. 16** 17** GNU Free Documentation License Usage 18** Alternatively, this file may be used under the terms of the GNU Free 19** Documentation License version 1.3 as published by the Free Software 20** Foundation and appearing in the file included in the packaging of 21** this file. Please review the following information to ensure 22** the GNU Free Documentation License version 1.3 requirements 23** will be met: https://www.gnu.org/licenses/fdl-1.3.html. 24** $QT_END_LICENSE$ 25** 26****************************************************************************/ 27 28/*! 29\page io-functions.html 30\title File and Datastream Functions 31 32The QIODevice class is the base interface class of all I/O devices in 33\l{Qt Core}. QIODevice provides both a common implementation and an 34abstract interface for devices that support reading and writing of blocks 35of data. The device can be a memory buffer, a file, or a datastream. 36 37Some subclasses like QFile have been implemented using a memory buffer for 38intermediate storing of data. This speeds up programs by reducing 39read/write operations. Buffering makes functions like \l{QFile::}{getChar()} and 40\l{QFile::}{putChar()} fast, as they can operate on the memory buffer instead of 41directly on the device itself. 42 43The QFile class provides functions for reading from and writing to files. 44A QFile may be used by itself or, more conveniently, with a QTextStream or 45QDataStream. 46 47QBuffer allows you to access a QByteArray using the QIODevice interface. 48The QByteArray is treated just as a standard random-accessed file. 49An example: 50 51\code 52 QBuffer buffer; 53 char ch; 54 55 buffer.open(QBuffer::ReadWrite); 56 buffer.write("Qt rocks!"); 57 buffer.seek(0); 58 buffer.getChar(&ch); // ch == 'Q' 59 buffer.getChar(&ch); // ch == 't' 60 buffer.getChar(&ch); // ch == ' ' 61 buffer.getChar(&ch); // ch == 'r' 62\endcode 63 64Call \l{QBuffer::}{open()} to open the buffer. Then call \l{QBuffer::}{write()} or \l{QBuffer::}{putChar()} to write to 65the buffer, and \l{QBuffer::}{read()}, \l{QBuffer::}{readLine()}, \l{QBuffer::}{readAll()}, or \l{QBuffer::}{getChar()} to read from it. 66\l{QBuffer::}{size()} returns the current size of the buffer, and you can seek to arbitrary 67positions in the buffer by calling \l{QBuffer::}{seek()}. When you are done with accessing 68the buffer, call \l{QBuffer::}{close()}. 69 70The QDataStream class provides serialization of binary data to a QIODevice. 71A data stream is a binary stream of encoded information which is 100% inde- 72pendent of the host computer's operating system, CPU or byte order. For 73example, a data stream that is written by a PC under Windows can be read 74by a Sun SPARC running Solaris. You can also use a data stream to read/write 75raw unencoded binary data. 76 77For more details on the datatypes that QDataStream can serialize, see 78\l{Serializing Qt Data Types}. 79 80The QTextStream class provides a convenient interface for reading and 81writing text. QTextStream can operate on a QIODevice, a QByteArray or 82a QString. Using QTextStream's streaming operators, you can conveniently read 83and write words, lines and numbers. It's also common to use QTextStream to 84read console input and write console output. 85 86There are three general ways to use QTextStream when reading text files: 87 88\list 89 \li Chunk by chunk, by calling \l{QBuffer::readLine()}{readLine()} or \l{QBuffer::readAll()}{readAll()}. 90 \li Word by word. QTextStream supports streaming into \l{QString}s, \l{QByteArray}s 91 and char* buffers. Words are delimited by space, and leading white space 92 is automatically skipped. 93 \li Character by character, by streaming into QChar or char types. This 94 method is often used for convenient input handling when parsing files, 95 independent of character encoding and end-of-line semantics. To skip 96 white space, call \l{QTextStream::}{skipWhiteSpace()}. 97\endlist 98 99QByteArray can be used to store both raw bytes (including \c{\0}) and traditional 1008-bit '\\0'-terminated strings. Using QByteArray is much more convenient 101than using const char *. It always ensures that the data is followed by a '\\0' 102terminator, and uses \l{Implicit Sharing}{implicitly shared classes} (copy-on-write) 103to reduce memory usage and avoid needless copying of data. 104 105In addition to QByteArray, Qt also provides the QString class to store string 106data. For most purposes, QString is the most appropriate class to use. It stores 10716-bit Unicode characters. It is, however, a good idea to use QByteArray when you 108need to store raw binary data, and when memory conservation is critical (for 109example, with Qt for Embedded Linux). 110 111*/ 112