1 files changed, 76 insertions, 0 deletions
diff --git a/src/qml/doc/src/qmllanguageref/typesystem/sequencetypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/sequencetypes.qdoc
new file mode 100644
index 0000000000..ca10f8c23b
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/typesystem/sequencetypes.qdoc
@@ -0,0 +1,76 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+/*!
+\page qtqml-typesystem-sequencetypes.html
+\title QML Sequence Types
+\brief Description of QML sequence types
+
+For every \l{qtqml-typesystem-objecttypes.html}{object type} and
+\l{qtqml-typesystem-valuetypes.html}{value type} a sequence type for storing
+multiple instances of the type is automatically made available. You can use
+the \c list keyword to create properties of sequence types:
+
+\qml
+import QtQml
+
+QtObject {
+    property list<int> ints: [1, 2, 3, 4]
+    property list<Connection> connections: [
+        Connection {
+            // ...
+        },
+        Connection {
+            // ...
+        }
+    ]
+}
+\endqml
+
+Sequences of value types are implemented as \l{QList} and sequences of object
+types are implemented as \l{QQmlListProperty}.
+
+Sequences in QML generally behave like the JavaScript \c Array type, with some
+important differences which result from the use of a C++ storage type in the
+implementation:
+
+\list 1
+\li Deleting an element from a sequence will result in a default-constructed
+    value replacing that element, rather than an \c undefined value.
+\li Setting the \c length property of a sequence to a value larger
+    than its current value will result in the sequence being padded out to the
+    specified length with default-constructed elements rather than \c undefined
+    elements.
+\li The Qt container classes support signed (rather than
+    unsigned) integer indexes; thus, attempting to access any index greater
+    than the maximum number \l qsizetype can hold will fail.
+\endlist
+
+If you wish to remove elements from a sequence rather than simply replace
+them with default constructed values, do not use the indexed delete operator
+(\c{delete sequence[i]}) but instead use the \c {splice} function
+(\c{sequence.splice(startIndex, deleteCount)}).
+
+In general any container recognizable by \l QMetaSequence can be passed from
+C++ to QML via \l Q_PROPERTY or \l Q_INVOKABLE methods. This includes, but is
+not limited to, all registered QList, QQueue, QStack, QSet, std::list,
+std::vector that contain a type marked with \l Q_DECLARE_METATYPE.
+
+Using a sequence via \l QMetaSequence results in expensive data conversions.
+To avoid the conversions you can register your own anonymous sequence types
+using \l{QML_SEQUENTIAL_CONTAINER} from C++. Types registered this way behave
+like the pre-defined sequence types and are stored as-is. However, they have
+no QML names.
+
+\warning Sequences stored as a C++ container like \l QList or \c std::vector are
+subject to the effects caused by \l{QML Value Type and Sequence References} and
+should thus be handled with care. \l QQmlListProperty is not affected since
+it is only a view for an underlying container. C++ standard containers such as
+\c std::vector are not implicitly shared. Therefore, copying them always
+produces a deep copy. Since a sequence read from a property always has to be
+copied at least once, using such containers as QML sequences is rather
+expensive, even if you don't modify them from QML.
+
+The QtQml module contains a few \l [QML] {QtQml#Sequence Types}{sequence types}
+you may want to use.
+
+*/