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 */
17namespace v8 {
18
19class BigInt;
20class Int32;
21class Integer;
22class Number;
23class Object;
24class String;
25class Uint32;
26
27/**
28 * The superclass of all JavaScript values and objects.
29 */
30class 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 a WeakRef.
249   */
250  bool IsWeakRef() const;
251
252  /**
253   * Returns true if this value is an ArrayBuffer.
254   */
255  bool IsArrayBuffer() const;
256
257  /**
258   * Returns true if this value is an ArrayBufferView.
259   */
260  bool IsArrayBufferView() const;
261
262  /**
263   * Returns true if this value is one of TypedArrays.
264   */
265  bool IsTypedArray() const;
266
267  /**
268   * Returns true if this value is an Uint8Array.
269   */
270  bool IsUint8Array() const;
271
272  /**
273   * Returns true if this value is an Uint8ClampedArray.
274   */
275  bool IsUint8ClampedArray() const;
276
277  /**
278   * Returns true if this value is an Int8Array.
279   */
280  bool IsInt8Array() const;
281
282  /**
283   * Returns true if this value is an Uint16Array.
284   */
285  bool IsUint16Array() const;
286
287  /**
288   * Returns true if this value is an Int16Array.
289   */
290  bool IsInt16Array() const;
291
292  /**
293   * Returns true if this value is an Uint32Array.
294   */
295  bool IsUint32Array() const;
296
297  /**
298   * Returns true if this value is an Int32Array.
299   */
300  bool IsInt32Array() const;
301
302  /**
303   * Returns true if this value is a Float32Array.
304   */
305  bool IsFloat32Array() const;
306
307  /**
308   * Returns true if this value is a Float64Array.
309   */
310  bool IsFloat64Array() const;
311
312  /**
313   * Returns true if this value is a BigInt64Array.
314   */
315  bool IsBigInt64Array() const;
316
317  /**
318   * Returns true if this value is a BigUint64Array.
319   */
320  bool IsBigUint64Array() const;
321
322  /**
323   * Returns true if this value is a DataView.
324   */
325  bool IsDataView() const;
326
327  /**
328   * Returns true if this value is a SharedArrayBuffer.
329   */
330  bool IsSharedArrayBuffer() const;
331
332  /**
333   * Returns true if this value is a JavaScript Proxy.
334   */
335  bool IsProxy() const;
336
337  /**
338   * Returns true if this value is a WasmMemoryObject.
339   */
340  bool IsWasmMemoryObject() const;
341
342  /**
343   * Returns true if this value is a WasmModuleObject.
344   */
345  bool IsWasmModuleObject() const;
346
347  /**
348   * Returns true if this value is the WasmNull object.
349   */
350  bool IsWasmNull() const;
351
352  /**
353   * Returns true if the value is a Module Namespace Object.
354   */
355  bool IsModuleNamespaceObject() const;
356
357  /**
358   * Perform the equivalent of `BigInt(value)` in JS.
359   */
360  V8_WARN_UNUSED_RESULT MaybeLocal<BigInt> ToBigInt(
361      Local<Context> context) const;
362  /**
363   * Perform the equivalent of `Number(value)` in JS.
364   */
365  V8_WARN_UNUSED_RESULT MaybeLocal<Number> ToNumber(
366      Local<Context> context) const;
367  /**
368   * Perform the equivalent of `String(value)` in JS.
369   */
370  V8_WARN_UNUSED_RESULT MaybeLocal<String> ToString(
371      Local<Context> context) const;
372  /**
373   * Provide a string representation of this value usable for debugging.
374   * This operation has no observable side effects and will succeed
375   * unless e.g. execution is being terminated.
376   */
377  V8_WARN_UNUSED_RESULT MaybeLocal<String> ToDetailString(
378      Local<Context> context) const;
379  /**
380   * Perform the equivalent of `Object(value)` in JS.
381   */
382  V8_WARN_UNUSED_RESULT MaybeLocal<Object> ToObject(
383      Local<Context> context) const;
384  /**
385   * Perform the equivalent of `Number(value)` in JS and convert the result
386   * to an integer. Negative values are rounded up, positive values are rounded
387   * down. NaN is converted to 0. Infinite values yield undefined results.
388   */
389  V8_WARN_UNUSED_RESULT MaybeLocal<Integer> ToInteger(
390      Local<Context> context) const;
391  /**
392   * Perform the equivalent of `Number(value)` in JS and convert the result
393   * to an unsigned 32-bit integer by performing the steps in
394   * https://tc39.es/ecma262/#sec-touint32.
395   */
396  V8_WARN_UNUSED_RESULT MaybeLocal<Uint32> ToUint32(
397      Local<Context> context) const;
398  /**
399   * Perform the equivalent of `Number(value)` in JS and convert the result
400   * to a signed 32-bit integer by performing the steps in
401   * https://tc39.es/ecma262/#sec-toint32.
402   */
403  V8_WARN_UNUSED_RESULT MaybeLocal<Int32> ToInt32(Local<Context> context) const;
404
405  /**
406   * Perform the equivalent of `Boolean(value)` in JS. This can never fail.
407   */
408  Local<Boolean> ToBoolean(Isolate* isolate) const;
409
410  /**
411   * Attempts to convert a string to an array index.
412   * Returns an empty handle if the conversion fails.
413   */
414  V8_WARN_UNUSED_RESULT MaybeLocal<Uint32> ToArrayIndex(
415      Local<Context> context) const;
416
417  /** Returns the equivalent of `ToBoolean()->Value()`. */
418  bool BooleanValue(Isolate* isolate) const;
419
420  /** Returns the equivalent of `ToNumber()->Value()`. */
421  V8_WARN_UNUSED_RESULT Maybe<double> NumberValue(Local<Context> context) const;
422  /** Returns the equivalent of `ToInteger()->Value()`. */
423  V8_WARN_UNUSED_RESULT Maybe<int64_t> IntegerValue(
424      Local<Context> context) const;
425  /** Returns the equivalent of `ToUint32()->Value()`. */
426  V8_WARN_UNUSED_RESULT Maybe<uint32_t> Uint32Value(
427      Local<Context> context) const;
428  /** Returns the equivalent of `ToInt32()->Value()`. */
429  V8_WARN_UNUSED_RESULT Maybe<int32_t> Int32Value(Local<Context> context) const;
430
431  /** JS == */
432  V8_WARN_UNUSED_RESULT Maybe<bool> Equals(Local<Context> context,
433                                           Local<Value> that) const;
434  bool StrictEquals(Local<Value> that) const;
435  bool SameValue(Local<Value> that) const;
436
437  template <class T>
438  V8_INLINE static Value* Cast(T* value) {
439    return static_cast<Value*>(value);
440  }
441
442  Local<String> TypeOf(Isolate*);
443
444  Maybe<bool> InstanceOf(Local<Context> context, Local<Object> object);
445
446 private:
447  V8_INLINE bool QuickIsUndefined() const;
448  V8_INLINE bool QuickIsNull() const;
449  V8_INLINE bool QuickIsNullOrUndefined() const;
450  V8_INLINE bool QuickIsString() const;
451  bool FullIsUndefined() const;
452  bool FullIsNull() const;
453  bool FullIsString() const;
454
455  static void CheckCast(Data* that);
456};
457
458template <>
459V8_INLINE Value* Value::Cast(Data* value) {
460#ifdef V8_ENABLE_CHECKS
461  CheckCast(value);
462#endif
463  return static_cast<Value*>(value);
464}
465
466bool Value::IsUndefined() const {
467#ifdef V8_ENABLE_CHECKS
468  return FullIsUndefined();
469#else
470  return QuickIsUndefined();
471#endif
472}
473
474bool Value::QuickIsUndefined() const {
475  using A = internal::Address;
476  using I = internal::Internals;
477  A obj = internal::ValueHelper::ValueAsAddress(this);
478#if V8_STATIC_ROOTS_BOOL
479  return I::is_identical(obj, I::StaticReadOnlyRoot::kUndefinedValue);
480#else
481  if (!I::HasHeapObjectTag(obj)) return false;
482  if (I::GetInstanceType(obj) != I::kOddballType) return false;
483  return (I::GetOddballKind(obj) == I::kUndefinedOddballKind);
484#endif  // V8_STATIC_ROOTS_BOOL
485}
486
487bool Value::IsNull() const {
488#ifdef V8_ENABLE_CHECKS
489  return FullIsNull();
490#else
491  return QuickIsNull();
492#endif
493}
494
495bool Value::QuickIsNull() const {
496  using A = internal::Address;
497  using I = internal::Internals;
498  A obj = internal::ValueHelper::ValueAsAddress(this);
499#if V8_STATIC_ROOTS_BOOL
500  return I::is_identical(obj, I::StaticReadOnlyRoot::kNullValue);
501#else
502  if (!I::HasHeapObjectTag(obj)) return false;
503  if (I::GetInstanceType(obj) != I::kOddballType) return false;
504  return (I::GetOddballKind(obj) == I::kNullOddballKind);
505#endif  // V8_STATIC_ROOTS_BOOL
506}
507
508bool Value::IsNullOrUndefined() const {
509#ifdef V8_ENABLE_CHECKS
510  return FullIsNull() || FullIsUndefined();
511#else
512  return QuickIsNullOrUndefined();
513#endif
514}
515
516bool Value::QuickIsNullOrUndefined() const {
517#if V8_STATIC_ROOTS_BOOL
518  return QuickIsNull() || QuickIsUndefined();
519#else
520  using A = internal::Address;
521  using I = internal::Internals;
522  A obj = internal::ValueHelper::ValueAsAddress(this);
523  if (!I::HasHeapObjectTag(obj)) return false;
524  if (I::GetInstanceType(obj) != I::kOddballType) return false;
525  int kind = I::GetOddballKind(obj);
526  return kind == I::kNullOddballKind || kind == I::kUndefinedOddballKind;
527#endif  // V8_STATIC_ROOTS_BOOL
528}
529
530bool Value::IsString() const {
531#ifdef V8_ENABLE_CHECKS
532  return FullIsString();
533#else
534  return QuickIsString();
535#endif
536}
537
538bool Value::QuickIsString() const {
539  using A = internal::Address;
540  using I = internal::Internals;
541  A obj = internal::ValueHelper::ValueAsAddress(this);
542  if (!I::HasHeapObjectTag(obj)) return false;
543#if V8_STATIC_ROOTS_BOOL && !V8_MAP_PACKING
544  return I::CheckInstanceMapRange(obj, I::StaticReadOnlyRoot::kFirstStringMap,
545                                  I::StaticReadOnlyRoot::kLastStringMap);
546#else
547  return (I::GetInstanceType(obj) < I::kFirstNonstringType);
548#endif  // V8_STATIC_ROOTS_BOOL
549}
550
551}  // namespace v8
552
553#endif  // INCLUDE_V8_VALUE_H_
554