new QByteArrayList class

Initial submission of a new class QByteArrayList with the
purpose of aggregating and then joining QByteArray instances.

[ChangeLog][QtCore] Added new QByteArrayList class.

Change-Id: I2a9dc71ff7aadb19ebc129a0d47ac8cd33895924
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@digia.com>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

3 files changed, 385 insertions, 0 deletions

diff --git a/src/corelib/tools/qbytearraylist.cpp b/src/corelib/tools/qbytearraylist.cpp
new file mode 100644
index 0000000000..817342d682
--- /dev/null
+++ b/src/corelib/tools/qbytearraylist.cpp
@@ -0,0 +1,258 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 by Southwest Research Institute (R)
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the QtCore module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Digia gives you certain additional
+** rights.  These rights are described in the Digia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <qbytearraylist.h>
+
+QT_BEGIN_NAMESPACE
+
+/*! \typedef QByteArrayListIterator
+    \relates QByteArrayList
+
+    The QByteArrayListIterator type definition provides a Java-style const
+    iterator for QByteArrayList.
+
+    QByteArrayList provides both \l{Java-style iterators} and
+    \l{STL-style iterators}. The Java-style const iterator is simply
+    a type definition for QListIterator<QByteArray>.
+
+    \sa QMutableByteArrayListIterator, QByteArrayList::const_iterator
+*/
+
+/*! \typedef QMutableByteArrayListIterator
+    \relates QByteArrayList
+
+    The QByteArrayListIterator type definition provides a Java-style
+    non-const iterator for QByteArrayList.
+
+    QByteArrayList provides both \l{Java-style iterators} and
+    \l{STL-style iterators}. The Java-style non-const iterator is
+    simply a type definition for QMutableListIterator<QByteArray>.
+
+    \sa QByteArrayListIterator, QByteArrayList::iterator
+*/
+
+/*!
+    \class QByteArrayList
+    \inmodule QtCore
+    \since 5.3
+    \brief The QByteArrayList class provides a list of byte arrays.
+
+    \ingroup tools
+    \ingroup shared
+    \ingroup string-processing
+
+    \reentrant
+
+    QByteArrayList inherits from QList<QByteArray>. Like QList, QByteArrayList is
+    \l{implicitly shared}. It provides fast index-based access as well as fast
+    insertions and removals. Passing string lists as value parameters is both
+    fast and safe.
+
+    All of QList's functionality also applies to QByteArrayList. For example, you
+    can use isEmpty() to test whether the list is empty, and you can call
+    functions like append(), prepend(), insert(), replace(), removeAll(),
+    removeAt(), removeFirst(), removeLast(), and removeOne() to modify a
+    QByteArrayList. In addition, QByteArrayList provides several join()
+    methods for concatenating the list into a single QByteArray.
+
+    The purpose of QByteArrayList is quite different from that of QStringList.
+    Whereas QStringList has many methods for manipulation of elements within
+    the list, QByteArrayList does not.
+    Normally, QStringList should be used whenever working with a list of printable
+    strings. QByteArrayList should be used to handle and efficiently join large blobs
+    of binary data, as when sequentially receiving serialized data through a
+    QIODevice.
+
+    \sa QByteArray, QStringList
+*/
+
+/*!
+    \fn QByteArrayList::QByteArrayList()
+
+    Constructs an empty byte array list.
+*/
+
+/*!
+    \fn QByteArrayList::QByteArrayList(const QByteArray &ba)
+
+    Constructs a byte array list that contains the given byte array,
+    \a ba. Longer lists are easily created like this:
+
+    \snippet qbytearraylist/main.cpp 0
+
+    \sa append()
+*/
+
+/*!
+    \fn QByteArrayList::QByteArrayList(const QByteArrayList &other)
+
+    Constructs a copy of the \a other byte array list.
+
+    This operation takes \l{constant time} because QByteArrayList is
+    \l{implicitly shared}, making the process of returning a
+    QByteArrayList from a function very fast. If a shared instance is
+    modified, it will be copied (copy-on-write), and that takes
+    \l{linear time}.
+
+    \sa operator=()
+*/
+
+/*!
+    \fn QByteArrayList::QByteArrayList(const QList<QByteArray> &other)
+
+    Constructs a copy of \a other.
+
+    This operation takes \l{constant time}, because QByteArrayList is
+    \l{implicitly shared}. This makes returning a QByteArrayList from a
+    function very fast. If a shared instance is modified, it will be
+    copied (copy-on-write), and that takes \l{linear time}.
+
+    \sa operator=()
+*/
+
+/*! \fn QByteArrayList::QByteArrayList(std::initializer_list<QByteArray> args)
+
+    Construct a list from a std::initializer_list given by \a args.
+
+    This constructor is only enabled if the compiler supports C++11 initializer
+    lists.
+*/
+
+/*!
+    \fn QByteArray QByteArrayList::join() const
+
+    Joins all the byte arrays into a single byte array.
+*/
+
+/*!
+    \fn QByteArray QByteArrayList::join(const QByteArray &separator) const
+
+    Joins all the byte arrays into a single byte array with each
+    element separated by the given \a separator.
+*/
+
+int QByteArrayList_joinedSize(const QByteArrayList *that, int seplen)
+{
+    int totalLength = 0;
+    const int size = that->size();
+
+    for (int i = 0; i < size; ++i)
+        totalLength += that->at(i).size();
+
+    if (size > 0)
+        totalLength += seplen * (size - 1);
+
+    return totalLength;
+}
+
+/*!
+    \fn QByteArray QByteArrayList::join(char separator) const
+
+    Joins all the byte arrays into a single byte array with each
+    element separated by the given \a separator.
+*/
+QByteArray QtPrivate::QByteArrayList_join(const QByteArrayList *that, const char *sep, int seplen)
+{
+    int totalLength = QByteArrayList_joinedSize(that, seplen);
+    QByteArray res;
+    if (totalLength == 0)
+        return res;
+    res.reserve(totalLength);
+    for (int i = 0; i < that->size(); ++i) {
+        if (i)
+            res.append(sep, seplen);
+        res += that->at(i);
+    }
+    return res;
+}
+
+/*!
+    \fn QByteArrayList operator+(const QByteArrayList &list1, const QByteArrayList &list2)
+    \relates QByteArrayList
+
+    Returns a byte array list that is the concatenation of \a list1 and \a list2.
+*/
+
+/*!
+    \fn QByteArrayList& operator+=(QByteArrayList &list1, const QByteArrayList &list2)
+    \relates QByteArrayList
+
+    Appends \a list2 to \a list1 and returns a reference to \a list1.
+*/
+
+/*!
+    \fn QByteArrayList &QByteArrayList::operator<<(const QByteArray &ba)
+
+    Appends the given byte array, \a ba, to this byte array list and returns
+    a reference to the byte array list.
+
+    \sa append()
+*/
+
+/*!
+    \fn QByteArrayList &QByteArrayList::operator<<(const QByteArrayList &other)
+
+    \overload
+
+    Appends the \a other byte array list to the byte array list and returns a reference to
+    the latter byte array list.
+*/
+
+/*!
+    \fn QDataStream &operator>>(QDataStream &in, QByteArrayList &list)
+    \relates QByteArrayList
+
+    Reads a byte array list from the given \a in stream into the specified
+    \a list.
+
+    \sa {Serializing Qt Data Types}
+*/
+
+/*!
+    \fn QDataStream &operator<<(QDataStream &out, const QByteArrayList &list)
+    \relates QByteArrayList
+
+    Writes the given byte array \a list to the specified \a out stream.
+
+    \sa {Serializing Qt Data Types}
+*/
+
+QT_END_NAMESPACE
diff --git a/src/corelib/tools/qbytearraylist.h b/src/corelib/tools/qbytearraylist.h
new file mode 100644
index 0000000000..5ce6509c28
--- /dev/null
+++ b/src/corelib/tools/qbytearraylist.h
@@ -0,0 +1,125 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 by Southwest Research Institute (R)
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the QtCore module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Digia gives you certain additional
+** rights.  These rights are described in the Digia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+
+#ifndef QBYTEARRAYLIST_H
+#define QBYTEARRAYLIST_H
+
+#include <QtCore/qdatastream.h>
+#include <QtCore/qlist.h>
+#include <QtCore/qbytearray.h>
+
+QT_BEGIN_NAMESPACE
+
+
+typedef QListIterator<QByteArray> QByteArrayListIterator;
+typedef QMutableListIterator<QByteArray> QMutableByteArrayListIterator;
+
+class QByteArrayList : public QList<QByteArray>
+{
+public:
+    inline QByteArrayList() { }
+    inline explicit QByteArrayList(const QByteArray &i) { append(i); }
+    inline QByteArrayList(const QByteArrayList &l) : QList<QByteArray>(l) { }
+    inline QByteArrayList(const QList<QByteArray> &l) : QList<QByteArray>(l) { }
+#ifdef Q_COMPILER_INITIALIZER_LISTS
+    inline QByteArrayList(std::initializer_list<QByteArray> args) : QList<QByteArray>(args) { }
+#endif
+
+    inline QByteArray join() const;
+    inline QByteArray join(const QByteArray &sep) const;
+    inline QByteArray join(char sep) const;
+
+    inline QByteArrayList &operator<<(const QByteArray &str)
+    { append(str); return *this; }
+    inline QByteArrayList &operator<<(const QByteArrayList &l)
+    { *this += l; return *this; }
+};
+
+Q_DECLARE_TYPEINFO(QByteArrayList, Q_MOVABLE_TYPE);
+
+namespace QtPrivate {
+    QByteArray Q_CORE_EXPORT QByteArrayList_join(const QByteArrayList *that, const char *s, int l);
+}
+
+inline QByteArray QByteArrayList::join() const
+{
+    return QtPrivate::QByteArrayList_join(this, 0, 0);
+}
+
+inline QByteArray QByteArrayList::join(const QByteArray &sep) const
+{
+    return QtPrivate::QByteArrayList_join(this, sep.constData(), sep.size());
+}
+
+inline QByteArray QByteArrayList::join(char sep) const
+{
+    return QtPrivate::QByteArrayList_join(this, &sep, 1);
+}
+
+inline QByteArrayList operator+(const QByteArrayList &lhs, const QByteArrayList &rhs)
+{
+    QByteArrayList res;
+    res.append( lhs );
+    res.append( rhs );
+    return res;
+}
+
+inline QByteArrayList& operator+=(QByteArrayList &lhs, const QByteArrayList &rhs)
+{
+    lhs.append( rhs );
+    return lhs;
+}
+
+#ifndef QT_NO_DATASTREAM
+inline QDataStream &operator>>(QDataStream &in, QByteArrayList &list)
+{
+    return operator>>(in, static_cast<QList<QByteArray> &>(list));
+}
+inline QDataStream &operator<<(QDataStream &out, const QByteArrayList &list)
+{
+    return operator<<(out, static_cast<const QList<QByteArray> &>(list));
+}
+#endif // QT_NO_DATASTREAM
+
+QT_END_NAMESPACE
+
+#endif // QBYTEARRAYLIST_H
diff --git a/src/corelib/tools/tools.pri b/src/corelib/tools/tools.pri
index 4ebd6ccd66..7ef7e6f46a 100644
--- a/src/corelib/tools/tools.pri
+++ b/src/corelib/tools/tools.pri
@@ -7,6 +7,7 @@ HEADERS +=  \
         tools/qarraydatapointer.h \
         tools/qbitarray.h \
         tools/qbytearray.h \
+        tools/qbytearraylist.h \
         tools/qbytearraymatcher.h \
         tools/qbytedata_p.h \
         tools/qcache.h \
@@ -75,6 +76,7 @@ SOURCES += \
         tools/qarraydata.cpp \
         tools/qbitarray.cpp \
         tools/qbytearray.cpp \
+        tools/qbytearraylist.cpp \
         tools/qbytearraymatcher.cpp \
         tools/qcollator.cpp \
         tools/qcommandlineoption.cpp \