1// Copyright (C) 2023 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
4\page qtqml-typesystem-sequencetypes.html
5\title QML Sequence Types
6\brief Description of QML sequence types
8For every \l{qtqml-typesystem-objecttypes.html}{object type} and
9\l{qtqml-typesystem-valuetypes.html}{value type} a sequence type for storing
10multiple instances of the type is automatically made available. You can use
11the \c list keyword to create properties of sequence types:
17 property list<int> ints: [1, 2, 3, 4]
18 property list<Connection> connections: [
29Sequences of value types are implemented as \l{QList} and sequences of object
30types are implemented as \l{QQmlListProperty}.
32Sequences in QML generally behave like the JavaScript \c Array type, with some
33important differences which result from the use of a C++ storage type in the
37\li Deleting an element from a sequence will result in a default-constructed
38 value replacing that element, rather than an \c undefined value.
39\li Setting the \c length property of a sequence to a value larger
40 than its current value will result in the sequence being padded out to the
41 specified length with default-constructed elements rather than \c undefined
43\li The Qt container classes support signed (rather than
44 unsigned) integer indexes; thus, attempting to access any index greater
45 than the maximum number \l qsizetype can hold will fail.
48If you wish to remove elements from a sequence rather than simply replace
49them with default constructed values, do not use the indexed delete operator
50(\c{delete sequence[i]}) but instead use the \c {splice} function
51(\c{sequence.splice(startIndex, deleteCount)}).
53In general any container recognizable by \l QMetaSequence can be passed from
54C++ to QML via \l Q_PROPERTY or \l Q_INVOKABLE methods. This includes, but is
55not limited to, all registered QList, QQueue, QStack, QSet, std::list,
56std::vector that contain a type marked with \l Q_DECLARE_METATYPE.
58Using a sequence via \l QMetaSequence results in expensive data conversions.
59To avoid the conversions you can register your own anonymous sequence types
60using \l{QML_SEQUENTIAL_CONTAINER} from C++. Types registered this way behave
61like the pre-defined sequence types and are stored as-is. However, they have
64\warning Sequences stored as a C++ container like \l QList or \c std::vector are
65subject to the effects caused by \l{QML Value Type and Sequence References} and
66should thus be handled with care. \l QQmlListProperty is not affected since
67it is only a view for an underlying container. C++ standard containers such as
68\c std::vector are not implicitly shared. Therefore, copying them always
69produces a deep copy. Since a sequence read from a property always has to be
70copied at least once, using such containers as QML sequences is rather
71expensive, even if you don't modify them from QML.
73The QtQml module contains a few \l [QML] {QtQml#Sequence Types}{sequence types}