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 | |
8 | QT_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 | |
321 | QString 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 | |
339 | QT_END_NAMESPACE |
340 | |
341 | |