1// Copyright (C) 2020 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 "qjsprimitivevalue.h"
5
6#include <QtQml/private/qv4runtime_p.h>
7
8QT_BEGIN_NAMESPACE
9
10/*!
11 \since 6.1
12 \class QJSPrimitiveUndefined
13
14 \inmodule QtQml
15
16 \brief An empty marker type to signify the JavaScript Undefined type and its single value.
17 \inmodule QtQml
18 */
19
20/*!
21 \since 6.1
22 \class QJSPrimitiveNull
23
24 \inmodule QtQml
25
26 \brief An empty marker type to signify the JavaScript null value.
27 \inmodule QtQml
28 */
29
30/*!
31 \since 6.1
32 \class QJSPrimitiveValue
33
34 \brief The QJSPrimitiveValue class operates on primitive types in JavaScript semantics.
35
36 \ingroup qtjavascript
37 \inmodule QtQml
38
39 QJSPrimitiveValue supports most of the primitive types defined in the
40 \l{ECMA-262} standard, in particular Undefined, Boolean, Number, and String.
41 Additionally, you can store a JavaScript null in a QJSPrimitiveValue and as a
42 special case of Number, you can store an integer value.
43
44 All those values are stored immediately, without interacting with the
45 JavaScript heap. Therefore, you can pass QJSPrimitiveValues between different
46 JavaScript engines. In contrast to QJSManagedValue, there is also no danger
47 in destroying a QJSPrimitiveValue from a different thread than it was created
48 in. On the flip side, QJSPrimitiveValue does not hold a reference to any
49 JavaScript engine.
50
51 QJSPrimitiveValue implements the JavaScript arithmetic and comparison
52 operators on the supported types in JavaScript semantics. Types are coerced
53 like the JavaScript engine would coerce them if the operators were written
54 in a JavaScript expression.
55
56 The JavaScript Symbol type is not supported as it is of very limited utility
57 regarding arithmetic and comparison operators, the main purpose of
58 QJSPrimitiveValue. In particular, it causes an exception whenever you try to
59 coerce it to a number or a string, and we cannot throw exceptions without a
60 JavaScript Engine.
61 */
62
63/*!
64 \enum QJSPrimitiveValue::Type
65
66 This enum speicifies the types a QJSPrimitiveValue might contain.
67
68 \value Undefined The JavaScript Undefined value.
69 \value Null The JavaScript null value. This is in fact not a separate
70 JavaScript type but a special value of the Object type. As it is
71 very common and storable without JavaScript engine, it is still
72 supported.
73 \value Boolean A JavaScript Boolean value.
74 \value Integer An integer. This is a special case of the JavaScript Number
75 type. JavaScript does not have an actual integer type, but
76 the \l{ECMA-262} standard contains rules on how to transform a
77 Number in order to prepare it for certain operators that only
78 make sense on integers, in particular the bit shift operators.
79 QJSPrimitiveValue's Integer type represents the result of such
80 a transformation.
81 \value Double A JavaScript Number value.
82 \value String A JavaScript String value.
83 */
84
85/*!
86 \fn Type QJSPrimitiveValue::type() const
87
88 Returns the type of the QJSPrimitiveValue.
89 */
90
91/*!
92 \fn QJSPrimitiveValue::QJSPrimitiveValue()
93
94 Creates a QJSPrimitiveValue of type Undefined.
95 */
96
97/*!
98 \fn QJSPrimitiveValue::QJSPrimitiveValue(QJSPrimitiveUndefined undefined)
99
100 Creates a QJSPrimitiveValue of value \a undefined and type Undefined.
101 */
102
103/*!
104 \fn QJSPrimitiveValue::QJSPrimitiveValue(QJSPrimitiveNull null)
105
106 Creates a QJSPrimitiveValue of value \a null and type Null.
107 */
108
109/*!
110 \fn QJSPrimitiveValue::QJSPrimitiveValue(bool value)
111
112 Creates a QJSPrimitiveValue of value \a value and type Boolean.
113 */
114
115/*!
116 \fn QJSPrimitiveValue::QJSPrimitiveValue(int value)
117
118 Creates a QJSPrimitiveValue of value \a value and type Integer.
119 */
120
121/*!
122 \fn QJSPrimitiveValue::QJSPrimitiveValue(double value)
123
124 Creates a QJSPrimitiveValue of value \a value and type Double.
125 */
126
127/*!
128 \fn QJSPrimitiveValue::QJSPrimitiveValue(QString value)
129
130 Creates a QJSPrimitiveValue of value \a value and type String.
131 */
132
133/*!
134 \fn QJSPrimitiveValue::QJSPrimitiveValue(QMetaType type, const void *value)
135 \since 6.4
136
137 Creates a QJSPrimitiveValue of type \a type, and initializes with
138 \a value if \a type can be stored in QJSPrimtiveValue. \a value must not
139 be nullptr in that case. If \a type cannot be stored this results in a
140 QJSPrimitiveValue of type Undefined.
141
142 Note that you have to pass the address of the variable you want stored.
143
144 Usually, you never have to use this constructor, use the one taking QVariant
145 instead.
146 */
147
148/*!
149 \fn QJSPrimitiveValue::QJSPrimitiveValue(QMetaType type)
150 \since 6.6
151 \internal
152
153 Creates a QJSPrimitiveValue of type \a type, and initializes with a
154 default-constructed value if \a type can be stored in QJSPrimtiveValue.
155 If \a type cannot be stored this results in a QJSPrimitiveValue of type
156 Undefined.
157*/
158
159/*!
160 \fn QJSPrimitiveValue::QJSPrimitiveValue(const QVariant &value)
161
162 Creates a QJSPrimitiveValue from the contents of \a value if those contents
163 can be stored in QJSPrimtiveValue. Otherwise this results in a
164 QJSPrimitiveValue of type Undefined.
165 */
166
167/*!
168 \fn bool QJSPrimitiveValue::toBoolean() const
169
170 Returns the value coerced a boolean by JavaScript rules.
171 */
172
173/*!
174 \fn int QJSPrimitiveValue::toInteger() const
175
176 Returns the value coerced to an integral 32bit number by the rules JavaScript
177 would apply when preparing it for a bit shift operation.
178 */
179
180/*!
181 \fn double QJSPrimitiveValue::toDouble() const
182
183 Returns the value coerced to a JavaScript Number by JavaScript rules.
184 */
185
186/*!
187 \fn QString QJSPrimitiveValue::toString() const
188
189 Returns the value coerced to a JavaScript String by JavaScript rules.
190 */
191
192/*!
193 \fn QJSPrimitiveValue QJSPrimitiveValue::operator+(const QJSPrimitiveValue &lhs, const QJSPrimitiveValue &rhs)
194
195 \since 6.1
196
197 Perfoms the JavaScript '+' operation on \a lhs and \a rhs, and returns the
198 result.
199 */
200
201/*!
202 \fn QJSPrimitiveValue QJSPrimitiveValue::operator-(const QJSPrimitiveValue &lhs, const QJSPrimitiveValue &rhs)
203 \since 6.1
204
205 Performs the JavaScript '-' operation on \a lhs and \a rhs, and returns the
206 result.
207 */
208
209/*!
210 \fn QJSPrimitiveValue QJSPrimitiveValue::operator*(const QJSPrimitiveValue &lhs, const QJSPrimitiveValue &rhs)
211 \since 6.1
212
213 Performs the JavaScript '*' operation on \a lhs and \a rhs, and returns the
214 result.
215 */
216
217/*!
218 \fn QJSPrimitiveValue QJSPrimitiveValue::operator/(const QJSPrimitiveValue &lhs, const QJSPrimitiveValue &rhs)
219 \since 6.1
220
221 Performs the JavaScript '/' operation between \a lhs and \a rhs, and returns the
222 result.
223 */
224
225/*!
226 \fn bool QJSPrimitiveValue::strictlyEquals(const QJSPrimitiveValue &other) const
227
228 Performs the JavaScript '===' operation on this QJSPrimitiveValue and
229 \a other, and returns the result.
230 */
231
232/*!
233 \fn bool QJSPrimitiveValue::equals(const QJSPrimitiveValue &other) const
234
235 Performs the JavaScript '==' operation on this QJSPrimitiveValue and
236 \a other, and returns the result.
237 */
238
239/*!
240 \fn bool QJSPrimitiveValue::operator==(const QJSPrimitiveValue &lhs, const QJSPrimitiveValue &rhs)
241 \since 6.1
242
243 Performs the JavaScript '===' operation on \a lhs and \a rhs, and returns the
244 result.
245 */
246
247/*!
248 \fn bool QJSPrimitiveValue::operator!=(const QJSPrimitiveValue &lhs, const QJSPrimitiveValue &rhs)
249 \since 6.1
250
251 Performs the JavaScript '!==' operation on \a lhs and \a rhs, and returns the
252 result.
253 */
254
255/*!
256 \fn bool QJSPrimitiveValue::operator<(const QJSPrimitiveValue &lhs, const QJSPrimitiveValue &rhs)
257 \since 6.1
258
259 Performs the JavaScript '<' operation on \a lhs and \a rhs, and returns the
260 result.
261 */
262
263/*!
264 \fn bool QJSPrimitiveValue::operator>(const QJSPrimitiveValue &lhs, const QJSPrimitiveValue &rhs)
265 \since 6.1
266
267 Performs the JavaScript '>' operation on \a lhs and \a rhs, and returns the
268 result.
269 */
270
271/*!
272 \fn bool QJSPrimitiveValue::operator<=(const QJSPrimitiveValue &lhs, const QJSPrimitiveValue &rhs)
273 \since 6.1
274
275 Performs the JavaScript '<=' operation on \a lhs and \a rhs, and returns the
276 result.
277 */
278
279/*!
280 \fn bool QJSPrimitiveValue::operator>=(const QJSPrimitiveValue &lhs, const QJSPrimitiveValue &rhs)
281 \since 6.1
282
283 Performs the JavaScript '>=' operation on \a lhs and \a rhs, and returns the
284 result.
285 */
286
287/*!
288 \fn QMetaType QJSPrimitiveValue::metaType() const
289 \since 6.6
290
291 Returns the QMetaType of the value stored in the QJSPrimitiveValue.
292 */
293
294/*!
295 \fn const void *QJSPrimitiveValue::constData() const
296 \fn const void *QJSPrimitiveValue::data() const
297 \since 6.6
298
299 Returns a pointer to the contained value as a generic void* that cannot be
300 written to.
301 */
302
303/*!
304 \fn const void *QJSPrimitiveValue::data()
305 \since 6.6
306
307 Returns a pointer to the contained data as a generic void* that can be
308 written to.
309*/
310
311/*!
312 \fn template<Type type> QJSPrimitiveValue QJSPrimitiveValue::to() const
313 \since 6.6
314
315 Coerces the value to the specified \e type and returns the result as a new
316 QJSPrimitiveValue.
317
318 \sa toBoolean(), toInteger(), toDouble(), toString()
319*/
320
321QString QJSPrimitiveValue::toString(double d)
322{
323 QString result;
324 QV4::RuntimeHelpers::numberToString(result: &result, num: d);
325 return result;
326}
327
328/*!
329 \fn double QQmlPrivate::jsExponentiate(double base, double exponent)
330 \internal
331 \since 6.4
332
333 Performs JavaScript's Number::exponentiate operation on \a base and
334 \a exponent, and returns the result.
335
336 See https://tc39.es/ecma262/multipage/ecmascript-data-types-and-values.html#sec-numeric-types-number-exponentiate
337 */
338
339QT_END_NAMESPACE
340
341

source code of qtdeclarative/src/qml/jsapi/qjsprimitivevalue.cpp