From: Nico Vertriest Date: Tue, 30 Oct 2012 14:22:38 +0000 (+0100) Subject: Added doc with IO functions X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=a769a212e0c22283fc05d3f49c252f8e2a62ba3f;p=profile%2Fivi%2Fqtbase.git Added doc with IO functions Minor spelling and editorial issues see remarks J.Pasion 30 Oct. Corrected syllabifying error and minor punctuation issue Added link to Qt Core in introduction Change-Id: I1516c94c7f9b70125801ab7f9dfeeaed94db6d91 Reviewed-by: Mitch Curtis Reviewed-by: Geir Vattekar Reviewed-by: Jerome Pasion --- diff --git a/src/corelib/doc/src/filestorage.qdoc b/src/corelib/doc/src/filestorage.qdoc new file mode 100644 index 0000000..be548ad --- /dev/null +++ b/src/corelib/doc/src/filestorage.qdoc @@ -0,0 +1,109 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page io-functions.html +\title File and Datastream Functions + +The QIODevice class is the base interface class of all I/O devices in +\l {Qt Core}. QIODevice provides both a common implementation and an +abstract interface for devices that support reading and writing of blocks +of data. The device can be a memory buffer, a file, or a datastream. + +Some subclasses like QFile have been implemented using a memory buffer for +intermediate storing of data. This speeds up programs by reducing +read/write operations. Buffering makes functions like getChar() and putChar() +fast, as they can operate on the memory buffer instead of directly on the +device itself. + +The QFile class provides functions for reading from and writing to files. +A QFile may be used by itself or, more conveniently, with a QTextStream or +QDataStream. + +QBuffer allows you to access a QByteArray using the QIODevice interface. +The QByteArray is treated just as a standard random-accessed file. +An example: + + QBuffer buffer; + char ch; + + buffer.open(QBuffer::ReadWrite); + buffer.write("Qt rocks!"); + buffer.seek(0); + buffer.getChar(&ch); // ch == 'Q' + buffer.getChar(&ch); // ch == 't' + buffer.getChar(&ch); // ch == ' ' + buffer.getChar(&ch); // ch == 'r' + +Call open() to open the buffer. Then call write() or putChar() to write to +the buffer, and read(), readLine(), readAll(), or getChar() to read from it. +size() returns the current size of the buffer, and you can seek to arbitrary +positions in the buffer by calling seek(). When you are done with accessing +the buffer, call close(). + +The QDataStream class provides serialization of binary data to a QIODevice. +A data stream is a binary stream of encoded information which is 100% inde- +pendent of the host computer's operating system, CPU or byte order. For +example, a data stream that is written by a PC under Windows can be read +by a Sun SPARC running Solaris. You can also use a data stream to read/write +raw unencoded binary data. + +For more details on the datatypes that QDataStream can serialize, see +{Serializing Qt Data Types}. + +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. It's also common to use QTextStream to +read console input and write console output. + +There are three general ways to use QTextStream when reading text files: + +\list + \li Chunk by chunk, by calling readLine() or readAll(). + \li Word by word. QTextStream supports streaming into QStrings, QByteArrays + and char* buffers. Words are delimited by space, and leading white space + is automatically skipped. + \li Character by character, by streaming into QChar or char types. This + method is often used for convenient input handling when parsing files, + independent of character encoding and end-of-line semantics. To skip + white space, call skipWhiteSpace(). +\endlist + +QByteArray can be used to store both raw bytes (including \c{\0}) and traditional +8-bit '\\0'-terminated strings. Using QByteArray is much more convenient +than using const char *. It always ensures that the data is followed by a '\\0' +terminator, and uses \l{Implicit Sharing}{implicitly shared classes} (copy-on-write) +to reduce memory usage and avoid needless copying of data. + +In addition to QByteArray, Qt also provides the QString class to store string +data. For most purposes, QString is the most appropriate class to use. It stores +16-bit Unicode characters. It is, however, a good idea to use QByteArray when you +need to store raw binary data, and when memory conservation is critical (for +example, with Qt for Embedded Linux). + +*/