1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include <QtCore/qtyperevision.h>
5#include <QtCore/qhashfunctions.h>
6
7#ifndef QT_NO_DATASTREAM
8# include <QtCore/qdatastream.h>
9#endif
10
11#ifndef QT_NO_DEBUG_STREAM
12# include <QtCore/qdebug.h>
13#endif
14
15#include <algorithm>
16#include <limits>
17
18QT_BEGIN_NAMESPACE
19
20QT_IMPL_METATYPE_EXTERN(QTypeRevision)
21
22/*!
23 \class QTypeRevision
24 \inmodule QtCore
25 \since 6.0
26 \brief The QTypeRevision class contains a lightweight representation of
27 a version number with two 8-bit segments, major and minor, either
28 of which can be unknown.
29 \compares strong
30
31 Use this class to describe revisions of a type. Compatible revisions can be
32 expressed as increments of the minor version. Breaking changes can be
33 expressed as increments of the major version. The return values of
34 \l QMetaMethod::revision() and \l QMetaProperty::revision() can be passed to
35 \l QTypeRevision::fromEncodedVersion(). The resulting major and minor versions
36 specify in which Qt versions the properties and methods were added.
37
38 \sa QMetaMethod::revision(), QMetaProperty::revision()
39*/
40
41/*!
42 \fn template<typename Integer, QTypeRevision::if_valid_segment_type<Integer> = true> static bool QTypeRevision::isValidSegment(Integer segment)
43
44 Returns true if the given number can be used as either major or minor
45 version in a QTypeRevision. The valid range for \a segment is \c {>= 0} and \c {< 255}.
46*/
47
48/*!
49 \fn QTypeRevision::QTypeRevision()
50
51 Produces an invalid revision.
52
53 \sa isValid()
54*/
55
56/*!
57 \fn template<typename Major, typename Minor, QTypeRevision::if_valid_segment_type<Major> = true, QTypeRevision::if_valid_segment_type<Minor> = true> static QTypeRevision QTypeRevision::fromVersion(Major majorVersion, Minor minorVersion)
58
59 Produces a QTypeRevision from the given \a majorVersion and \a minorVersion,
60 both of which need to be a valid segments.
61
62 \sa isValidSegment()
63*/
64
65/*!
66 \fn template<typename Major, QTypeRevision::if_valid_segment_type<Major> = true> static QTypeRevision QTypeRevision::fromMajorVersion(Major majorVersion)
67
68 Produces a QTypeRevision from the given \a majorVersion with an invalid minor
69 version. \a majorVersion needs to be a valid segment.
70
71 \sa isValidSegment()
72*/
73
74/*!
75 \fn template<typename Minor, QTypeRevision::if_valid_segment_type<Minor> = true> static QTypeRevision QTypeRevision::fromMinorVersion(Minor minorVersion)
76
77 Produces a QTypeRevision from the given \a minorVersion with an invalid major
78 version. \a minorVersion needs to be a valid segment.
79
80 \sa isValidSegment()
81*/
82
83/*!
84 \fn template<typename Integer, QTypeRevision::if_valid_value_type<Integer> = true> static QTypeRevision QTypeRevision::fromEncodedVersion(Integer value)
85
86 Produces a QTypeRevision from the given \a value. \a value encodes both the
87 minor and major versions in the least significant and second least
88 significant byte, respectively.
89
90 \a value must not have any bits outside the least significant two bytes set.
91 \c Integer needs to be at least 16 bits wide, and must not have a sign bit
92 in the least significant 16 bits.
93
94 \sa toEncodedVersion()
95*/
96
97/*!
98 \fn static QTypeRevision QTypeRevision::zero()
99
100 Produces a QTypeRevision with major and minor version \c{0}.
101*/
102
103/*!
104 \fn bool QTypeRevision::hasMajorVersion() const
105
106 Returns true if the major version is known, otherwise false.
107
108 \sa majorVersion(), hasMinorVersion()
109*/
110
111/*!
112 \fn quint8 QTypeRevision::majorVersion() const
113
114 Returns the major version encoded in the revision.
115
116 \sa hasMajorVersion(), minorVersion()
117*/
118
119/*!
120 \fn bool QTypeRevision::hasMinorVersion() const
121
122 Returns true if the minor version is known, otherwise false.
123
124 \sa minorVersion(), hasMajorVersion()
125*/
126
127/*!
128 \fn quint8 QTypeRevision::minorVersion() const
129
130 Returns the minor version encoded in the revision.
131
132 \sa hasMinorVersion(), majorVersion()
133*/
134
135/*!
136 \fn bool QTypeRevision::isValid() const
137
138 Returns true if the major version or the minor version is known,
139 otherwise false.
140
141 \sa hasMajorVersion(), hasMinorVersion()
142*/
143
144/*!
145 \fn template<typename Integer, QTypeRevision::if_valid_value_type<Integer> = true> Integer QTypeRevision::toEncodedVersion() const
146
147 Transforms the revision into an integer value, encoding the minor
148 version into the least significant byte, and the major version into
149 the second least significant byte.
150
151 \c Integer needs to be at least 16 bits wide, and must not have a sign bit
152 in the least significant 16 bits.
153
154 \sa fromEncodedVersion()
155*/
156
157#ifndef QT_NO_DATASTREAM
158/*!
159 \fn QDataStream& operator<<(QDataStream &out, const QTypeRevision &revision)
160 \relates QTypeRevision
161 \since 6.0
162
163 Writes the revision \a revision to stream \a out.
164 */
165QDataStream &operator<<(QDataStream &out, const QTypeRevision &revision)
166{
167 return out << revision.toEncodedVersion<quint16>();
168}
169
170/*!
171 \fn QDataStream& operator>>(QDataStream &in, QTypeRevision &revision)
172 \relates QTypeRevision
173 \since 6.0
174
175 Reads a revision from stream \a in and stores it in \a revision.
176 */
177QDataStream &operator>>(QDataStream &in, QTypeRevision &revision)
178{
179 quint16 value;
180 in >> value;
181 revision = QTypeRevision::fromEncodedVersion(value);
182 return in;
183}
184#endif
185
186#ifndef QT_NO_DEBUG_STREAM
187QDebug operator<<(QDebug debug, const QTypeRevision &revision)
188{
189 QDebugStateSaver saver(debug);
190 if (revision.hasMajorVersion()) {
191 if (revision.hasMinorVersion())
192 debug.nospace() << revision.majorVersion() << '.' << revision.minorVersion();
193 else
194 debug.nospace().noquote() << revision.majorVersion() << ".x";
195 } else {
196 if (revision.hasMinorVersion())
197 debug << revision.minorVersion();
198 else
199 debug.noquote() << "invalid";
200 }
201 return debug;
202}
203#endif
204
205/*!
206 \qhashold{QHash}
207 \since 6.0
208*/
209size_t qHash(const QTypeRevision &key, size_t seed)
210{
211 return qHash(key: key.toEncodedVersion<quint16>(), seed);
212}
213
214QT_END_NAMESPACE
215

source code of qtbase/src/corelib/tools/qtyperevision.cpp