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_PRIMITIVE_H_
6 #define INCLUDE_V8_PRIMITIVE_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-value.h" // NOLINT(build/include_directory)
12 #include "v8config.h" // NOLINT(build/include_directory)
13
14 namespace v8 {
15
16 class Context;
17 class Isolate;
18 class String;
19
20 namespace internal {
21 class ExternalString;
22 class ScopedExternalStringLock;
23 } // namespace internal
24
25 /**
26 * The superclass of primitive values. See ECMA-262 4.3.2.
27 */
28 class V8_EXPORT Primitive : public Value {};
29
30 /**
31 * A primitive boolean value (ECMA-262, 4.3.14). Either the true
32 * or false value.
33 */
34 class V8_EXPORT Boolean : public Primitive {
35 public:
36 bool Value() const;
Cast(v8::Data * data)37 V8_INLINE static Boolean* Cast(v8::Data* data) {
38 #ifdef V8_ENABLE_CHECKS
39 CheckCast(data);
40 #endif
41 return static_cast<Boolean*>(data);
42 }
43
44 V8_INLINE static Local<Boolean> New(Isolate* isolate, bool value);
45
46 private:
47 static void CheckCast(v8::Data* that);
48 };
49
50 /**
51 * An array to hold Primitive values. This is used by the embedder to
52 * pass host defined options to the ScriptOptions during compilation.
53 *
54 * This is passed back to the embedder as part of
55 * HostImportModuleDynamicallyCallback for module loading.
56 */
57 class V8_EXPORT PrimitiveArray : public Data {
58 public:
59 static Local<PrimitiveArray> New(Isolate* isolate, int length);
60 int Length() const;
61 void Set(Isolate* isolate, int index, Local<Primitive> item);
62 Local<Primitive> Get(Isolate* isolate, int index);
63
Cast(Data * data)64 V8_INLINE static PrimitiveArray* Cast(Data* data) {
65 #ifdef V8_ENABLE_CHECKS
66 CheckCast(data);
67 #endif
68 return reinterpret_cast<PrimitiveArray*>(data);
69 }
70
71 private:
72 static void CheckCast(Data* obj);
73 };
74
75 /**
76 * A superclass for symbols and strings.
77 */
78 class V8_EXPORT Name : public Primitive {
79 public:
80 /**
81 * Returns the identity hash for this object. The current implementation
82 * uses an inline property on the object to store the identity hash.
83 *
84 * The return value will never be 0. Also, it is not guaranteed to be
85 * unique.
86 */
87 int GetIdentityHash();
88
Cast(Data * data)89 V8_INLINE static Name* Cast(Data* data) {
90 #ifdef V8_ENABLE_CHECKS
91 CheckCast(data);
92 #endif
93 return static_cast<Name*>(data);
94 }
95
96 private:
97 static void CheckCast(Data* that);
98 };
99
100 /**
101 * A flag describing different modes of string creation.
102 *
103 * Aside from performance implications there are no differences between the two
104 * creation modes.
105 */
106 enum class NewStringType {
107 /**
108 * Create a new string, always allocating new storage memory.
109 */
110 kNormal,
111
112 /**
113 * Acts as a hint that the string should be created in the
114 * old generation heap space and be deduplicated if an identical string
115 * already exists.
116 */
117 kInternalized
118 };
119
120 /**
121 * A JavaScript string value (ECMA-262, 4.3.17).
122 */
123 class V8_EXPORT String : public Name {
124 public:
125 static constexpr int kMaxLength =
126 internal::kApiSystemPointerSize == 4 ? (1 << 28) - 16 : (1 << 29) - 24;
127
128 enum Encoding {
129 UNKNOWN_ENCODING = 0x1,
130 TWO_BYTE_ENCODING = 0x0,
131 ONE_BYTE_ENCODING = 0x8
132 };
133 /**
134 * Returns the number of characters (UTF-16 code units) in this string.
135 */
136 int Length() const;
137
138 /**
139 * Returns the number of bytes in the UTF-8 encoded
140 * representation of this string.
141 */
142 int Utf8Length(Isolate* isolate) const;
143
144 /**
145 * Returns whether this string is known to contain only one byte data,
146 * i.e. ISO-8859-1 code points.
147 * Does not read the string.
148 * False negatives are possible.
149 */
150 bool IsOneByte() const;
151
152 /**
153 * Returns whether this string contain only one byte data,
154 * i.e. ISO-8859-1 code points.
155 * Will read the entire string in some cases.
156 */
157 bool ContainsOnlyOneByte() const;
158
159 /**
160 * Write the contents of the string to an external buffer.
161 * If no arguments are given, expects the buffer to be large
162 * enough to hold the entire string and NULL terminator. Copies
163 * the contents of the string and the NULL terminator into the
164 * buffer.
165 *
166 * WriteUtf8 will not write partial UTF-8 sequences, preferring to stop
167 * before the end of the buffer.
168 *
169 * Copies up to length characters into the output buffer.
170 * Only null-terminates if there is enough space in the buffer.
171 *
172 * \param buffer The buffer into which the string will be copied.
173 * \param start The starting position within the string at which
174 * copying begins.
175 * \param length The number of characters to copy from the string. For
176 * WriteUtf8 the number of bytes in the buffer.
177 * \param nchars_ref The number of characters written, can be NULL.
178 * \param options Various options that might affect performance of this or
179 * subsequent operations.
180 * \return The number of characters copied to the buffer excluding the null
181 * terminator. For WriteUtf8: The number of bytes copied to the buffer
182 * including the null terminator (if written).
183 */
184 enum WriteOptions {
185 NO_OPTIONS = 0,
186 HINT_MANY_WRITES_EXPECTED = 1,
187 NO_NULL_TERMINATION = 2,
188 PRESERVE_ONE_BYTE_NULL = 4,
189 // Used by WriteUtf8 to replace orphan surrogate code units with the
190 // unicode replacement character. Needs to be set to guarantee valid UTF-8
191 // output.
192 REPLACE_INVALID_UTF8 = 8
193 };
194
195 // 16-bit character codes.
196 int Write(Isolate* isolate, uint16_t* buffer, int start = 0, int length = -1,
197 int options = NO_OPTIONS) const;
198 // One byte characters.
199 int WriteOneByte(Isolate* isolate, uint8_t* buffer, int start = 0,
200 int length = -1, int options = NO_OPTIONS) const;
201 // UTF-8 encoded characters.
202 int WriteUtf8(Isolate* isolate, char* buffer, int length = -1,
203 int* nchars_ref = nullptr, int options = NO_OPTIONS) const;
204
205 /**
206 * A zero length string.
207 */
208 V8_INLINE static Local<String> Empty(Isolate* isolate);
209
210 /**
211 * Returns true if the string is external.
212 */
213 bool IsExternal() const;
214
215 /**
216 * Returns true if the string is both external and two-byte.
217 */
218 bool IsExternalTwoByte() const;
219
220 /**
221 * Returns true if the string is both external and one-byte.
222 */
223 bool IsExternalOneByte() const;
224
225 class V8_EXPORT ExternalStringResourceBase {
226 public:
227 virtual ~ExternalStringResourceBase() = default;
228
229 /**
230 * If a string is cacheable, the value returned by
231 * ExternalStringResource::data() may be cached, otherwise it is not
232 * expected to be stable beyond the current top-level task.
233 */
IsCacheable()234 virtual bool IsCacheable() const { return true; }
235
236 // Disallow copying and assigning.
237 ExternalStringResourceBase(const ExternalStringResourceBase&) = delete;
238 void operator=(const ExternalStringResourceBase&) = delete;
239
240 protected:
241 ExternalStringResourceBase() = default;
242
243 /**
244 * Internally V8 will call this Dispose method when the external string
245 * resource is no longer needed. The default implementation will use the
246 * delete operator. This method can be overridden in subclasses to
247 * control how allocated external string resources are disposed.
248 */
Dispose()249 virtual void Dispose() { delete this; }
250
251 /**
252 * For a non-cacheable string, the value returned by
253 * |ExternalStringResource::data()| has to be stable between |Lock()| and
254 * |Unlock()|, that is the string must behave as is |IsCacheable()| returned
255 * true.
256 *
257 * These two functions must be thread-safe, and can be called from anywhere.
258 * They also must handle lock depth, in the sense that each can be called
259 * several times, from different threads, and unlocking should only happen
260 * when the balance of Lock() and Unlock() calls is 0.
261 */
Lock()262 virtual void Lock() const {}
263
264 /**
265 * Unlocks the string.
266 */
Unlock()267 virtual void Unlock() const {}
268
269 private:
270 friend class internal::ExternalString;
271 friend class v8::String;
272 friend class internal::ScopedExternalStringLock;
273 };
274
275 /**
276 * An ExternalStringResource is a wrapper around a two-byte string
277 * buffer that resides outside V8's heap. Implement an
278 * ExternalStringResource to manage the life cycle of the underlying
279 * buffer. Note that the string data must be immutable.
280 */
281 class V8_EXPORT ExternalStringResource : public ExternalStringResourceBase {
282 public:
283 /**
284 * Override the destructor to manage the life cycle of the underlying
285 * buffer.
286 */
287 ~ExternalStringResource() override = default;
288
289 /**
290 * The string data from the underlying buffer. If the resource is cacheable
291 * then data() must return the same value for all invocations.
292 */
293 virtual const uint16_t* data() const = 0;
294
295 /**
296 * The length of the string. That is, the number of two-byte characters.
297 */
298 virtual size_t length() const = 0;
299
300 /**
301 * Returns the cached data from the underlying buffer. This method can be
302 * called only for cacheable resources (i.e. IsCacheable() == true) and only
303 * after UpdateDataCache() was called.
304 */
cached_data()305 const uint16_t* cached_data() const {
306 CheckCachedDataInvariants();
307 return cached_data_;
308 }
309
310 /**
311 * Update {cached_data_} with the data from the underlying buffer. This can
312 * be called only for cacheable resources.
313 */
314 void UpdateDataCache();
315
316 protected:
317 ExternalStringResource() = default;
318
319 private:
320 void CheckCachedDataInvariants() const;
321
322 const uint16_t* cached_data_ = nullptr;
323 };
324
325 /**
326 * An ExternalOneByteStringResource is a wrapper around an one-byte
327 * string buffer that resides outside V8's heap. Implement an
328 * ExternalOneByteStringResource to manage the life cycle of the
329 * underlying buffer. Note that the string data must be immutable
330 * and that the data must be Latin-1 and not UTF-8, which would require
331 * special treatment internally in the engine and do not allow efficient
332 * indexing. Use String::New or convert to 16 bit data for non-Latin1.
333 */
334
335 class V8_EXPORT ExternalOneByteStringResource
336 : public ExternalStringResourceBase {
337 public:
338 /**
339 * Override the destructor to manage the life cycle of the underlying
340 * buffer.
341 */
342 ~ExternalOneByteStringResource() override = default;
343
344 /**
345 * The string data from the underlying buffer. If the resource is cacheable
346 * then data() must return the same value for all invocations.
347 */
348 virtual const char* data() const = 0;
349
350 /** The number of Latin-1 characters in the string.*/
351 virtual size_t length() const = 0;
352
353 /**
354 * Returns the cached data from the underlying buffer. If the resource is
355 * uncacheable or if UpdateDataCache() was not called before, it has
356 * undefined behaviour.
357 */
cached_data()358 const char* cached_data() const {
359 CheckCachedDataInvariants();
360 return cached_data_;
361 }
362
363 /**
364 * Update {cached_data_} with the data from the underlying buffer. This can
365 * be called only for cacheable resources.
366 */
367 void UpdateDataCache();
368
369 protected:
370 ExternalOneByteStringResource() = default;
371
372 private:
373 void CheckCachedDataInvariants() const;
374
375 const char* cached_data_ = nullptr;
376 };
377
378 /**
379 * If the string is an external string, return the ExternalStringResourceBase
380 * regardless of the encoding, otherwise return NULL. The encoding of the
381 * string is returned in encoding_out.
382 */
383 V8_INLINE ExternalStringResourceBase* GetExternalStringResourceBase(
384 Encoding* encoding_out) const;
385
386 /**
387 * Get the ExternalStringResource for an external string. Returns
388 * NULL if IsExternal() doesn't return true.
389 */
390 V8_INLINE ExternalStringResource* GetExternalStringResource() const;
391
392 /**
393 * Get the ExternalOneByteStringResource for an external one-byte string.
394 * Returns NULL if IsExternalOneByte() doesn't return true.
395 */
396 const ExternalOneByteStringResource* GetExternalOneByteStringResource() const;
397
Cast(v8::Data * data)398 V8_INLINE static String* Cast(v8::Data* data) {
399 #ifdef V8_ENABLE_CHECKS
400 CheckCast(data);
401 #endif
402 return static_cast<String*>(data);
403 }
404
405 /**
406 * Allocates a new string from a UTF-8 literal. This is equivalent to calling
407 * String::NewFromUtf(isolate, "...").ToLocalChecked(), but without the check
408 * overhead.
409 *
410 * When called on a string literal containing '\0', the inferred length is the
411 * length of the input array minus 1 (for the final '\0') and not the value
412 * returned by strlen.
413 **/
414 template <int N>
415 static V8_WARN_UNUSED_RESULT Local<String> NewFromUtf8Literal(
416 Isolate* isolate, const char (&literal)[N],
417 NewStringType type = NewStringType::kNormal) {
418 static_assert(N <= kMaxLength, "String is too long");
419 return NewFromUtf8Literal(isolate, literal, type, N - 1);
420 }
421
422 /** Allocates a new string from UTF-8 data. Only returns an empty value when
423 * length > kMaxLength. **/
424 static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromUtf8(
425 Isolate* isolate, const char* data,
426 NewStringType type = NewStringType::kNormal, int length = -1);
427
428 /** Allocates a new string from Latin-1 data. Only returns an empty value
429 * when length > kMaxLength. **/
430 static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromOneByte(
431 Isolate* isolate, const uint8_t* data,
432 NewStringType type = NewStringType::kNormal, int length = -1);
433
434 /** Allocates a new string from UTF-16 data. Only returns an empty value when
435 * length > kMaxLength. **/
436 static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromTwoByte(
437 Isolate* isolate, const uint16_t* data,
438 NewStringType type = NewStringType::kNormal, int length = -1);
439
440 /**
441 * Creates a new string by concatenating the left and the right strings
442 * passed in as parameters.
443 */
444 static Local<String> Concat(Isolate* isolate, Local<String> left,
445 Local<String> right);
446
447 /**
448 * Creates a new external string using the data defined in the given
449 * resource. When the external string is no longer live on V8's heap the
450 * resource will be disposed by calling its Dispose method. The caller of
451 * this function should not otherwise delete or modify the resource. Neither
452 * should the underlying buffer be deallocated or modified except through the
453 * destructor of the external string resource.
454 */
455 static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewExternalTwoByte(
456 Isolate* isolate, ExternalStringResource* resource);
457
458 /**
459 * Associate an external string resource with this string by transforming it
460 * in place so that existing references to this string in the JavaScript heap
461 * will use the external string resource. The external string resource's
462 * character contents need to be equivalent to this string.
463 * Returns true if the string has been changed to be an external string.
464 * The string is not modified if the operation fails. See NewExternal for
465 * information on the lifetime of the resource.
466 */
467 bool MakeExternal(ExternalStringResource* resource);
468
469 /**
470 * Creates a new external string using the one-byte data defined in the given
471 * resource. When the external string is no longer live on V8's heap the
472 * resource will be disposed by calling its Dispose method. The caller of
473 * this function should not otherwise delete or modify the resource. Neither
474 * should the underlying buffer be deallocated or modified except through the
475 * destructor of the external string resource.
476 */
477 static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewExternalOneByte(
478 Isolate* isolate, ExternalOneByteStringResource* resource);
479
480 /**
481 * Associate an external string resource with this string by transforming it
482 * in place so that existing references to this string in the JavaScript heap
483 * will use the external string resource. The external string resource's
484 * character contents need to be equivalent to this string.
485 * Returns true if the string has been changed to be an external string.
486 * The string is not modified if the operation fails. See NewExternal for
487 * information on the lifetime of the resource.
488 */
489 bool MakeExternal(ExternalOneByteStringResource* resource);
490
491 /**
492 * Returns true if this string can be made external.
493 */
494 bool CanMakeExternal() const;
495
496 /**
497 * Returns true if the strings values are equal. Same as JS ==/===.
498 */
499 bool StringEquals(Local<String> str) const;
500
501 /**
502 * Converts an object to a UTF-8-encoded character array. Useful if
503 * you want to print the object. If conversion to a string fails
504 * (e.g. due to an exception in the toString() method of the object)
505 * then the length() method returns 0 and the * operator returns
506 * NULL.
507 */
508 class V8_EXPORT Utf8Value {
509 public:
510 Utf8Value(Isolate* isolate, Local<v8::Value> obj);
511 ~Utf8Value();
512 char* operator*() { return str_; }
513 const char* operator*() const { return str_; }
length()514 int length() const { return length_; }
515
516 // Disallow copying and assigning.
517 Utf8Value(const Utf8Value&) = delete;
518 void operator=(const Utf8Value&) = delete;
519
520 private:
521 char* str_;
522 int length_;
523 };
524
525 /**
526 * Converts an object to a two-byte (UTF-16-encoded) string.
527 * If conversion to a string fails (eg. due to an exception in the toString()
528 * method of the object) then the length() method returns 0 and the * operator
529 * returns NULL.
530 */
531 class V8_EXPORT Value {
532 public:
533 Value(Isolate* isolate, Local<v8::Value> obj);
534 ~Value();
535 uint16_t* operator*() { return str_; }
536 const uint16_t* operator*() const { return str_; }
length()537 int length() const { return length_; }
538
539 // Disallow copying and assigning.
540 Value(const Value&) = delete;
541 void operator=(const Value&) = delete;
542
543 private:
544 uint16_t* str_;
545 int length_;
546 };
547
548 private:
549 void VerifyExternalStringResourceBase(ExternalStringResourceBase* v,
550 Encoding encoding) const;
551 void VerifyExternalStringResource(ExternalStringResource* val) const;
552 ExternalStringResource* GetExternalStringResourceSlow() const;
553 ExternalStringResourceBase* GetExternalStringResourceBaseSlow(
554 String::Encoding* encoding_out) const;
555
556 static Local<v8::String> NewFromUtf8Literal(Isolate* isolate,
557 const char* literal,
558 NewStringType type, int length);
559
560 static void CheckCast(v8::Data* that);
561 };
562
563 // Zero-length string specialization (templated string size includes
564 // terminator).
565 template <>
NewFromUtf8Literal(Isolate * isolate,const char (& literal)[1],NewStringType type)566 inline V8_WARN_UNUSED_RESULT Local<String> String::NewFromUtf8Literal(
567 Isolate* isolate, const char (&literal)[1], NewStringType type) {
568 return String::Empty(isolate);
569 }
570
571 /**
572 * Interface for iterating through all external resources in the heap.
573 */
574 class V8_EXPORT ExternalResourceVisitor {
575 public:
576 virtual ~ExternalResourceVisitor() = default;
VisitExternalString(Local<String> string)577 virtual void VisitExternalString(Local<String> string) {}
578 };
579
580 /**
581 * A JavaScript symbol (ECMA-262 edition 6)
582 */
583 class V8_EXPORT Symbol : public Name {
584 public:
585 /**
586 * Returns the description string of the symbol, or undefined if none.
587 */
588 Local<Value> Description(Isolate* isolate) const;
589
590 /**
591 * Create a symbol. If description is not empty, it will be used as the
592 * description.
593 */
594 static Local<Symbol> New(Isolate* isolate,
595 Local<String> description = Local<String>());
596
597 /**
598 * Access global symbol registry.
599 * Note that symbols created this way are never collected, so
600 * they should only be used for statically fixed properties.
601 * Also, there is only one global name space for the descriptions used as
602 * keys.
603 * To minimize the potential for clashes, use qualified names as keys.
604 */
605 static Local<Symbol> For(Isolate* isolate, Local<String> description);
606
607 /**
608 * Retrieve a global symbol. Similar to |For|, but using a separate
609 * registry that is not accessible by (and cannot clash with) JavaScript code.
610 */
611 static Local<Symbol> ForApi(Isolate* isolate, Local<String> description);
612
613 // Well-known symbols
614 static Local<Symbol> GetAsyncIterator(Isolate* isolate);
615 static Local<Symbol> GetHasInstance(Isolate* isolate);
616 static Local<Symbol> GetIsConcatSpreadable(Isolate* isolate);
617 static Local<Symbol> GetIterator(Isolate* isolate);
618 static Local<Symbol> GetMatch(Isolate* isolate);
619 static Local<Symbol> GetReplace(Isolate* isolate);
620 static Local<Symbol> GetSearch(Isolate* isolate);
621 static Local<Symbol> GetSplit(Isolate* isolate);
622 static Local<Symbol> GetToPrimitive(Isolate* isolate);
623 static Local<Symbol> GetToStringTag(Isolate* isolate);
624 static Local<Symbol> GetUnscopables(Isolate* isolate);
625
Cast(Data * data)626 V8_INLINE static Symbol* Cast(Data* data) {
627 #ifdef V8_ENABLE_CHECKS
628 CheckCast(data);
629 #endif
630 return static_cast<Symbol*>(data);
631 }
632
633 private:
634 Symbol();
635 static void CheckCast(Data* that);
636 };
637
638 /**
639 * A JavaScript number value (ECMA-262, 4.3.20)
640 */
641 class V8_EXPORT Number : public Primitive {
642 public:
643 double Value() const;
644 static Local<Number> New(Isolate* isolate, double value);
Cast(v8::Data * data)645 V8_INLINE static Number* Cast(v8::Data* data) {
646 #ifdef V8_ENABLE_CHECKS
647 CheckCast(data);
648 #endif
649 return static_cast<Number*>(data);
650 }
651
652 private:
653 Number();
654 static void CheckCast(v8::Data* that);
655 };
656
657 /**
658 * A JavaScript value representing a signed integer.
659 */
660 class V8_EXPORT Integer : public Number {
661 public:
662 static Local<Integer> New(Isolate* isolate, int32_t value);
663 static Local<Integer> NewFromUnsigned(Isolate* isolate, uint32_t value);
664 int64_t Value() const;
Cast(v8::Data * data)665 V8_INLINE static Integer* Cast(v8::Data* data) {
666 #ifdef V8_ENABLE_CHECKS
667 CheckCast(data);
668 #endif
669 return static_cast<Integer*>(data);
670 }
671
672 private:
673 Integer();
674 static void CheckCast(v8::Data* that);
675 };
676
677 /**
678 * A JavaScript value representing a 32-bit signed integer.
679 */
680 class V8_EXPORT Int32 : public Integer {
681 public:
682 int32_t Value() const;
Cast(v8::Data * data)683 V8_INLINE static Int32* Cast(v8::Data* data) {
684 #ifdef V8_ENABLE_CHECKS
685 CheckCast(data);
686 #endif
687 return static_cast<Int32*>(data);
688 }
689
690 private:
691 Int32();
692 static void CheckCast(v8::Data* that);
693 };
694
695 /**
696 * A JavaScript value representing a 32-bit unsigned integer.
697 */
698 class V8_EXPORT Uint32 : public Integer {
699 public:
700 uint32_t Value() const;
Cast(v8::Data * data)701 V8_INLINE static Uint32* Cast(v8::Data* data) {
702 #ifdef V8_ENABLE_CHECKS
703 CheckCast(data);
704 #endif
705 return static_cast<Uint32*>(data);
706 }
707
708 private:
709 Uint32();
710 static void CheckCast(v8::Data* that);
711 };
712
713 /**
714 * A JavaScript BigInt value (https://tc39.github.io/proposal-bigint)
715 */
716 class V8_EXPORT BigInt : public Primitive {
717 public:
718 static Local<BigInt> New(Isolate* isolate, int64_t value);
719 static Local<BigInt> NewFromUnsigned(Isolate* isolate, uint64_t value);
720 /**
721 * Creates a new BigInt object using a specified sign bit and a
722 * specified list of digits/words.
723 * The resulting number is calculated as:
724 *
725 * (-1)^sign_bit * (words[0] * (2^64)^0 + words[1] * (2^64)^1 + ...)
726 */
727 static MaybeLocal<BigInt> NewFromWords(Local<Context> context, int sign_bit,
728 int word_count, const uint64_t* words);
729
730 /**
731 * Returns the value of this BigInt as an unsigned 64-bit integer.
732 * If `lossless` is provided, it will reflect whether the return value was
733 * truncated or wrapped around. In particular, it is set to `false` if this
734 * BigInt is negative.
735 */
736 uint64_t Uint64Value(bool* lossless = nullptr) const;
737
738 /**
739 * Returns the value of this BigInt as a signed 64-bit integer.
740 * If `lossless` is provided, it will reflect whether this BigInt was
741 * truncated or not.
742 */
743 int64_t Int64Value(bool* lossless = nullptr) const;
744
745 /**
746 * Returns the number of 64-bit words needed to store the result of
747 * ToWordsArray().
748 */
749 int WordCount() const;
750
751 /**
752 * Writes the contents of this BigInt to a specified memory location.
753 * `sign_bit` must be provided and will be set to 1 if this BigInt is
754 * negative.
755 * `*word_count` has to be initialized to the length of the `words` array.
756 * Upon return, it will be set to the actual number of words that would
757 * be needed to store this BigInt (i.e. the return value of `WordCount()`).
758 */
759 void ToWordsArray(int* sign_bit, int* word_count, uint64_t* words) const;
760
Cast(v8::Data * data)761 V8_INLINE static BigInt* Cast(v8::Data* data) {
762 #ifdef V8_ENABLE_CHECKS
763 CheckCast(data);
764 #endif
765 return static_cast<BigInt*>(data);
766 }
767
768 private:
769 BigInt();
770 static void CheckCast(v8::Data* that);
771 };
772
Empty(Isolate * isolate)773 Local<String> String::Empty(Isolate* isolate) {
774 using S = internal::Address;
775 using I = internal::Internals;
776 I::CheckInitialized(isolate);
777 S* slot = I::GetRoot(isolate, I::kEmptyStringRootIndex);
778 return Local<String>(reinterpret_cast<String*>(slot));
779 }
780
GetExternalStringResource()781 String::ExternalStringResource* String::GetExternalStringResource() const {
782 using A = internal::Address;
783 using I = internal::Internals;
784 A obj = *reinterpret_cast<const A*>(this);
785
786 ExternalStringResource* result;
787 if (I::IsExternalTwoByteString(I::GetInstanceType(obj))) {
788 internal::Isolate* isolate = I::GetIsolateForSandbox(obj);
789 A value =
790 I::ReadExternalPointerField(isolate, obj, I::kStringResourceOffset,
791 internal::kExternalStringResourceTag);
792 result = reinterpret_cast<String::ExternalStringResource*>(value);
793 } else {
794 result = GetExternalStringResourceSlow();
795 }
796 #ifdef V8_ENABLE_CHECKS
797 VerifyExternalStringResource(result);
798 #endif
799 return result;
800 }
801
GetExternalStringResourceBase(String::Encoding * encoding_out)802 String::ExternalStringResourceBase* String::GetExternalStringResourceBase(
803 String::Encoding* encoding_out) const {
804 using A = internal::Address;
805 using I = internal::Internals;
806 A obj = *reinterpret_cast<const A*>(this);
807 int type = I::GetInstanceType(obj) & I::kStringRepresentationAndEncodingMask;
808 *encoding_out = static_cast<Encoding>(type & I::kStringEncodingMask);
809 ExternalStringResourceBase* resource;
810 if (type == I::kExternalOneByteRepresentationTag ||
811 type == I::kExternalTwoByteRepresentationTag) {
812 internal::Isolate* isolate = I::GetIsolateForSandbox(obj);
813 A value =
814 I::ReadExternalPointerField(isolate, obj, I::kStringResourceOffset,
815 internal::kExternalStringResourceTag);
816 resource = reinterpret_cast<ExternalStringResourceBase*>(value);
817 } else {
818 resource = GetExternalStringResourceBaseSlow(encoding_out);
819 }
820 #ifdef V8_ENABLE_CHECKS
821 VerifyExternalStringResourceBase(resource, *encoding_out);
822 #endif
823 return resource;
824 }
825
826 // --- Statics ---
827
Undefined(Isolate * isolate)828 V8_INLINE Local<Primitive> Undefined(Isolate* isolate) {
829 using S = internal::Address;
830 using I = internal::Internals;
831 I::CheckInitialized(isolate);
832 S* slot = I::GetRoot(isolate, I::kUndefinedValueRootIndex);
833 return Local<Primitive>(reinterpret_cast<Primitive*>(slot));
834 }
835
Null(Isolate * isolate)836 V8_INLINE Local<Primitive> Null(Isolate* isolate) {
837 using S = internal::Address;
838 using I = internal::Internals;
839 I::CheckInitialized(isolate);
840 S* slot = I::GetRoot(isolate, I::kNullValueRootIndex);
841 return Local<Primitive>(reinterpret_cast<Primitive*>(slot));
842 }
843
True(Isolate * isolate)844 V8_INLINE Local<Boolean> True(Isolate* isolate) {
845 using S = internal::Address;
846 using I = internal::Internals;
847 I::CheckInitialized(isolate);
848 S* slot = I::GetRoot(isolate, I::kTrueValueRootIndex);
849 return Local<Boolean>(reinterpret_cast<Boolean*>(slot));
850 }
851
False(Isolate * isolate)852 V8_INLINE Local<Boolean> False(Isolate* isolate) {
853 using S = internal::Address;
854 using I = internal::Internals;
855 I::CheckInitialized(isolate);
856 S* slot = I::GetRoot(isolate, I::kFalseValueRootIndex);
857 return Local<Boolean>(reinterpret_cast<Boolean*>(slot));
858 }
859
New(Isolate * isolate,bool value)860 Local<Boolean> Boolean::New(Isolate* isolate, bool value) {
861 return value ? True(isolate) : False(isolate);
862 }
863
864 } // namespace v8
865
866 #endif // INCLUDE_V8_PRIMITIVE_H_
867