v8  10.1.124 (node 18.2.0)
V8 is Google's open source JavaScript engine
v8-value.h
Go to the documentation of this file.
1 // Copyright 2021 the V8 project authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef INCLUDE_V8_VALUE_H_
6 #define INCLUDE_V8_VALUE_H_
7 
8 #include "v8-data.h" // NOLINT(build/include_directory)
9 #include "v8-internal.h" // NOLINT(build/include_directory)
10 #include "v8-local-handle.h" // NOLINT(build/include_directory)
11 #include "v8-maybe.h" // NOLINT(build/include_directory)
12 #include "v8config.h" // NOLINT(build/include_directory)
13 
14 /**
15  * The v8 JavaScript engine.
16  */
17 namespace v8 {
18 
19 class BigInt;
20 class Int32;
21 class Integer;
22 class Number;
23 class Object;
24 class String;
25 class Uint32;
26 
27 /**
28  * The superclass of all JavaScript values and objects.
29  */
30 class V8_EXPORT Value : public Data {
31  public:
32  /**
33  * Returns true if this value is the undefined value. See ECMA-262
34  * 4.3.10.
35  *
36  * This is equivalent to `value === undefined` in JS.
37  */
38  V8_INLINE bool IsUndefined() const;
39 
40  /**
41  * Returns true if this value is the null value. See ECMA-262
42  * 4.3.11.
43  *
44  * This is equivalent to `value === null` in JS.
45  */
46  V8_INLINE bool IsNull() const;
47 
48  /**
49  * Returns true if this value is either the null or the undefined value.
50  * See ECMA-262
51  * 4.3.11. and 4.3.12
52  *
53  * This is equivalent to `value == null` in JS.
54  */
55  V8_INLINE bool IsNullOrUndefined() const;
56 
57  /**
58  * Returns true if this value is true.
59  *
60  * This is not the same as `BooleanValue()`. The latter performs a
61  * conversion to boolean, i.e. the result of `Boolean(value)` in JS, whereas
62  * this checks `value === true`.
63  */
64  bool IsTrue() const;
65 
66  /**
67  * Returns true if this value is false.
68  *
69  * This is not the same as `!BooleanValue()`. The latter performs a
70  * conversion to boolean, i.e. the result of `!Boolean(value)` in JS, whereas
71  * this checks `value === false`.
72  */
73  bool IsFalse() const;
74 
75  /**
76  * Returns true if this value is a symbol or a string.
77  *
78  * This is equivalent to
79  * `typeof value === 'string' || typeof value === 'symbol'` in JS.
80  */
81  bool IsName() const;
82 
83  /**
84  * Returns true if this value is an instance of the String type.
85  * See ECMA-262 8.4.
86  *
87  * This is equivalent to `typeof value === 'string'` in JS.
88  */
89  V8_INLINE bool IsString() const;
90 
91  /**
92  * Returns true if this value is a symbol.
93  *
94  * This is equivalent to `typeof value === 'symbol'` in JS.
95  */
96  bool IsSymbol() const;
97 
98  /**
99  * Returns true if this value is a function.
100  *
101  * This is equivalent to `typeof value === 'function'` in JS.
102  */
103  bool IsFunction() const;
104 
105  /**
106  * Returns true if this value is an array. Note that it will return false for
107  * an Proxy for an array.
108  */
109  bool IsArray() const;
110 
111  /**
112  * Returns true if this value is an object.
113  */
114  bool IsObject() const;
115 
116  /**
117  * Returns true if this value is a bigint.
118  *
119  * This is equivalent to `typeof value === 'bigint'` in JS.
120  */
121  bool IsBigInt() const;
122 
123  /**
124  * Returns true if this value is boolean.
125  *
126  * This is equivalent to `typeof value === 'boolean'` in JS.
127  */
128  bool IsBoolean() const;
129 
130  /**
131  * Returns true if this value is a number.
132  *
133  * This is equivalent to `typeof value === 'number'` in JS.
134  */
135  bool IsNumber() const;
136 
137  /**
138  * Returns true if this value is an `External` object.
139  */
140  bool IsExternal() const;
141 
142  /**
143  * Returns true if this value is a 32-bit signed integer.
144  */
145  bool IsInt32() const;
146 
147  /**
148  * Returns true if this value is a 32-bit unsigned integer.
149  */
150  bool IsUint32() const;
151 
152  /**
153  * Returns true if this value is a Date.
154  */
155  bool IsDate() const;
156 
157  /**
158  * Returns true if this value is an Arguments object.
159  */
160  bool IsArgumentsObject() const;
161 
162  /**
163  * Returns true if this value is a BigInt object.
164  */
165  bool IsBigIntObject() const;
166 
167  /**
168  * Returns true if this value is a Boolean object.
169  */
170  bool IsBooleanObject() const;
171 
172  /**
173  * Returns true if this value is a Number object.
174  */
175  bool IsNumberObject() const;
176 
177  /**
178  * Returns true if this value is a String object.
179  */
180  bool IsStringObject() const;
181 
182  /**
183  * Returns true if this value is a Symbol object.
184  */
185  bool IsSymbolObject() const;
186 
187  /**
188  * Returns true if this value is a NativeError.
189  */
190  bool IsNativeError() const;
191 
192  /**
193  * Returns true if this value is a RegExp.
194  */
195  bool IsRegExp() const;
196 
197  /**
198  * Returns true if this value is an async function.
199  */
200  bool IsAsyncFunction() const;
201 
202  /**
203  * Returns true if this value is a Generator function.
204  */
205  bool IsGeneratorFunction() const;
206 
207  /**
208  * Returns true if this value is a Generator object (iterator).
209  */
210  bool IsGeneratorObject() const;
211 
212  /**
213  * Returns true if this value is a Promise.
214  */
215  bool IsPromise() const;
216 
217  /**
218  * Returns true if this value is a Map.
219  */
220  bool IsMap() const;
221 
222  /**
223  * Returns true if this value is a Set.
224  */
225  bool IsSet() const;
226 
227  /**
228  * Returns true if this value is a Map Iterator.
229  */
230  bool IsMapIterator() const;
231 
232  /**
233  * Returns true if this value is a Set Iterator.
234  */
235  bool IsSetIterator() const;
236 
237  /**
238  * Returns true if this value is a WeakMap.
239  */
240  bool IsWeakMap() const;
241 
242  /**
243  * Returns true if this value is a WeakSet.
244  */
245  bool IsWeakSet() const;
246 
247  /**
248  * Returns true if this value is an ArrayBuffer.
249  */
250  bool IsArrayBuffer() const;
251 
252  /**
253  * Returns true if this value is an ArrayBufferView.
254  */
255  bool IsArrayBufferView() const;
256 
257  /**
258  * Returns true if this value is one of TypedArrays.
259  */
260  bool IsTypedArray() const;
261 
262  /**
263  * Returns true if this value is an Uint8Array.
264  */
265  bool IsUint8Array() const;
266 
267  /**
268  * Returns true if this value is an Uint8ClampedArray.
269  */
270  bool IsUint8ClampedArray() const;
271 
272  /**
273  * Returns true if this value is an Int8Array.
274  */
275  bool IsInt8Array() const;
276 
277  /**
278  * Returns true if this value is an Uint16Array.
279  */
280  bool IsUint16Array() const;
281 
282  /**
283  * Returns true if this value is an Int16Array.
284  */
285  bool IsInt16Array() const;
286 
287  /**
288  * Returns true if this value is an Uint32Array.
289  */
290  bool IsUint32Array() const;
291 
292  /**
293  * Returns true if this value is an Int32Array.
294  */
295  bool IsInt32Array() const;
296 
297  /**
298  * Returns true if this value is a Float32Array.
299  */
300  bool IsFloat32Array() const;
301 
302  /**
303  * Returns true if this value is a Float64Array.
304  */
305  bool IsFloat64Array() const;
306 
307  /**
308  * Returns true if this value is a BigInt64Array.
309  */
310  bool IsBigInt64Array() const;
311 
312  /**
313  * Returns true if this value is a BigUint64Array.
314  */
315  bool IsBigUint64Array() const;
316 
317  /**
318  * Returns true if this value is a DataView.
319  */
320  bool IsDataView() const;
321 
322  /**
323  * Returns true if this value is a SharedArrayBuffer.
324  */
325  bool IsSharedArrayBuffer() const;
326 
327  /**
328  * Returns true if this value is a JavaScript Proxy.
329  */
330  bool IsProxy() const;
331 
332  /**
333  * Returns true if this value is a WasmMemoryObject.
334  */
335  bool IsWasmMemoryObject() const;
336 
337  /**
338  * Returns true if this value is a WasmModuleObject.
339  */
340  bool IsWasmModuleObject() const;
341 
342  /**
343  * Returns true if the value is a Module Namespace Object.
344  */
346 
347  /**
348  * Perform the equivalent of `BigInt(value)` in JS.
349  */
351  Local<Context> context) const;
352  /**
353  * Perform the equivalent of `Number(value)` in JS.
354  */
356  Local<Context> context) const;
357  /**
358  * Perform the equivalent of `String(value)` in JS.
359  */
361  Local<Context> context) const;
362  /**
363  * Provide a string representation of this value usable for debugging.
364  * This operation has no observable side effects and will succeed
365  * unless e.g. execution is being terminated.
366  */
368  Local<Context> context) const;
369  /**
370  * Perform the equivalent of `Object(value)` in JS.
371  */
373  Local<Context> context) const;
374  /**
375  * Perform the equivalent of `Number(value)` in JS and convert the result
376  * to an integer. Negative values are rounded up, positive values are rounded
377  * down. NaN is converted to 0. Infinite values yield undefined results.
378  */
380  Local<Context> context) const;
381  /**
382  * Perform the equivalent of `Number(value)` in JS and convert the result
383  * to an unsigned 32-bit integer by performing the steps in
384  * https://tc39.es/ecma262/#sec-touint32.
385  */
387  Local<Context> context) const;
388  /**
389  * Perform the equivalent of `Number(value)` in JS and convert the result
390  * to a signed 32-bit integer by performing the steps in
391  * https://tc39.es/ecma262/#sec-toint32.
392  */
394 
395  /**
396  * Perform the equivalent of `Boolean(value)` in JS. This can never fail.
397  */
398  Local<Boolean> ToBoolean(Isolate* isolate) const;
399 
400  /**
401  * Attempts to convert a string to an array index.
402  * Returns an empty handle if the conversion fails.
403  */
405  Local<Context> context) const;
406 
407  /** Returns the equivalent of `ToBoolean()->Value()`. */
408  bool BooleanValue(Isolate* isolate) const;
409 
410  /** Returns the equivalent of `ToNumber()->Value()`. */
412  /** Returns the equivalent of `ToInteger()->Value()`. */
414  Local<Context> context) const;
415  /** Returns the equivalent of `ToUint32()->Value()`. */
417  Local<Context> context) const;
418  /** Returns the equivalent of `ToInt32()->Value()`. */
420 
421  /** JS == */
423  Local<Value> that) const;
424  bool StrictEquals(Local<Value> that) const;
425  bool SameValue(Local<Value> that) const;
426 
427  template <class T>
428  V8_INLINE static Value* Cast(T* value) {
429  return static_cast<Value*>(value);
430  }
431 
433 
434  Maybe<bool> InstanceOf(Local<Context> context, Local<Object> object);
435 
436  private:
437  V8_INLINE bool QuickIsUndefined() const;
438  V8_INLINE bool QuickIsNull() const;
439  V8_INLINE bool QuickIsNullOrUndefined() const;
440  V8_INLINE bool QuickIsString() const;
441  bool FullIsUndefined() const;
442  bool FullIsNull() const;
443  bool FullIsString() const;
444 
445  static void CheckCast(Data* that);
446 };
447 
448 template <>
450 #ifdef V8_ENABLE_CHECKS
451  CheckCast(value);
452 #endif
453  return static_cast<Value*>(value);
454 }
455 
456 bool Value::IsUndefined() const {
457 #ifdef V8_ENABLE_CHECKS
458  return FullIsUndefined();
459 #else
460  return QuickIsUndefined();
461 #endif
462 }
463 
464 bool Value::QuickIsUndefined() const {
465  using A = internal::Address;
466  using I = internal::Internals;
467  A obj = *reinterpret_cast<const A*>(this);
468  if (!I::HasHeapObjectTag(obj)) return false;
469  if (I::GetInstanceType(obj) != I::kOddballType) return false;
471 }
472 
473 bool Value::IsNull() const {
474 #ifdef V8_ENABLE_CHECKS
475  return FullIsNull();
476 #else
477  return QuickIsNull();
478 #endif
479 }
480 
481 bool Value::QuickIsNull() const {
482  using A = internal::Address;
483  using I = internal::Internals;
484  A obj = *reinterpret_cast<const A*>(this);
485  if (!I::HasHeapObjectTag(obj)) return false;
486  if (I::GetInstanceType(obj) != I::kOddballType) return false;
487  return (I::GetOddballKind(obj) == I::kNullOddballKind);
488 }
489 
490 bool Value::IsNullOrUndefined() const {
491 #ifdef V8_ENABLE_CHECKS
492  return FullIsNull() || FullIsUndefined();
493 #else
494  return QuickIsNullOrUndefined();
495 #endif
496 }
497 
498 bool Value::QuickIsNullOrUndefined() const {
499  using A = internal::Address;
500  using I = internal::Internals;
501  A obj = *reinterpret_cast<const A*>(this);
502  if (!I::HasHeapObjectTag(obj)) return false;
503  if (I::GetInstanceType(obj) != I::kOddballType) return false;
504  int kind = I::GetOddballKind(obj);
505  return kind == I::kNullOddballKind || kind == I::kUndefinedOddballKind;
506 }
507 
508 bool Value::IsString() const {
509 #ifdef V8_ENABLE_CHECKS
510  return FullIsString();
511 #else
512  return QuickIsString();
513 #endif
514 }
515 
516 bool Value::QuickIsString() const {
517  using A = internal::Address;
518  using I = internal::Internals;
519  A obj = *reinterpret_cast<const A*>(this);
520  if (!I::HasHeapObjectTag(obj)) return false;
522 }
523 
524 } // namespace v8
525 
526 #endif // INCLUDE_V8_VALUE_H_