v8 12.4.254 (node 22.4.1)
V8 is Google's open source JavaScript engine
Loading...
Searching...
No Matches
v8-primitive.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_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
14namespace v8 {
15
16class Context;
17class Isolate;
18class String;
19
20namespace internal {
21class ExternalString;
22class ScopedExternalStringLock;
23class StringForwardingTable;
24} // namespace internal
25
29class V8_EXPORT Primitive : public Value {};
30
35class V8_EXPORT Boolean : public Primitive {
36 public:
37 bool Value() const;
38 V8_INLINE static Boolean* Cast(v8::Data* data) {
39#ifdef V8_ENABLE_CHECKS
40 CheckCast(data);
41#endif
42 return static_cast<Boolean*>(data);
43 }
44
45 V8_INLINE static Local<Boolean> New(Isolate* isolate, bool value);
46
47 private:
48 static void CheckCast(v8::Data* that);
49};
50
59 public:
60 static Local<PrimitiveArray> New(Isolate* isolate, int length);
61 int Length() const;
62 void Set(Isolate* isolate, int index, Local<Primitive> item);
63 Local<Primitive> Get(Isolate* isolate, int index);
64
66#ifdef V8_ENABLE_CHECKS
67 CheckCast(data);
68#endif
69 return reinterpret_cast<PrimitiveArray*>(data);
70 }
71
72 private:
73 static void CheckCast(Data* obj);
74};
75
79class V8_EXPORT Name : public Primitive {
80 public:
89
90 V8_INLINE static Name* Cast(Data* data) {
91#ifdef V8_ENABLE_CHECKS
92 CheckCast(data);
93#endif
94 return static_cast<Name*>(data);
95 }
96
97 private:
98 static void CheckCast(Data* that);
99};
100
107enum class NewStringType {
111 kNormal,
112
119};
120
124class V8_EXPORT String : public Name {
125 public:
126 static constexpr int kMaxLength =
127 internal::kApiSystemPointerSize == 4 ? (1 << 28) - 16 : (1 << 29) - 24;
128
129 enum Encoding {
130 UNKNOWN_ENCODING = 0x1,
131 TWO_BYTE_ENCODING = 0x0,
132 ONE_BYTE_ENCODING = 0x8
133 };
137 int Length() const;
138
143 int Utf8Length(Isolate* isolate) const;
144
151 bool IsOneByte() const;
152
159
186 NO_OPTIONS = 0,
187 HINT_MANY_WRITES_EXPECTED = 1,
188 NO_NULL_TERMINATION = 2,
189 PRESERVE_ONE_BYTE_NULL = 4,
190 // Used by WriteUtf8 to replace orphan surrogate code units with the
191 // unicode replacement character. Needs to be set to guarantee valid UTF-8
192 // output.
193 REPLACE_INVALID_UTF8 = 8
194 };
195
196 // 16-bit character codes.
197 int Write(Isolate* isolate, uint16_t* buffer, int start = 0, int length = -1,
198 int options = NO_OPTIONS) const;
199 // One byte characters.
200 int WriteOneByte(Isolate* isolate, uint8_t* buffer, int start = 0,
201 int length = -1, int options = NO_OPTIONS) const;
202 // UTF-8 encoded characters.
203 int WriteUtf8(Isolate* isolate, char* buffer, int length = -1,
204 int* nchars_ref = nullptr, int options = NO_OPTIONS) const;
205
209 V8_INLINE static Local<String> Empty(Isolate* isolate);
210
214 bool IsExternal() const;
215
219 bool IsExternalTwoByte() const;
220
224 bool IsExternalOneByte() const;
225
227 public:
228 virtual ~ExternalStringResourceBase() = default;
229
235 virtual bool IsCacheable() const { return true; }
236
237 // Disallow copying and assigning.
240
241 protected:
243
250 virtual void Dispose() { delete this; }
251
263 virtual void Lock() const {}
264
268 virtual void Unlock() const {}
269
270 private:
271 friend class internal::ExternalString;
272 friend class v8::String;
273 friend class internal::StringForwardingTable;
274 friend class internal::ScopedExternalStringLock;
275 };
276
284 public:
289 ~ExternalStringResource() override = default;
290
295 virtual const uint16_t* data() const = 0;
296
300 virtual size_t length() const = 0;
301
307 const uint16_t* cached_data() const {
308 CheckCachedDataInvariants();
309 return cached_data_;
310 }
311
317
318 protected:
320
321 private:
322 void CheckCachedDataInvariants() const;
323
324 const uint16_t* cached_data_ = nullptr;
325 };
326
339 public:
344 ~ExternalOneByteStringResource() override = default;
345
350 virtual const char* data() const = 0;
351
353 virtual size_t length() const = 0;
354
360 const char* cached_data() const {
361 CheckCachedDataInvariants();
362 return cached_data_;
363 }
364
370
371 protected:
373
374 private:
375 void CheckCachedDataInvariants() const;
377 const char* cached_data_ = nullptr;
378 };
385 V8_INLINE ExternalStringResourceBase* GetExternalStringResourceBase(
386 Encoding* encoding_out) const;
387
392 V8_INLINE ExternalStringResource* GetExternalStringResource() const;
393
399
400 V8_INLINE static String* Cast(v8::Data* data) {
401#ifdef V8_ENABLE_CHECKS
402 CheckCast(data);
403#endif
404 return static_cast<String*>(data);
405 }
406
416 template <int N>
418 Isolate* isolate, const char (&literal)[N],
419 NewStringType type = NewStringType::kNormal) {
420 static_assert(N <= kMaxLength, "String is too long");
421 return NewFromUtf8Literal(isolate, literal, type, N - 1);
422 }
423
427 Isolate* isolate, const char* data,
428 NewStringType type = NewStringType::kNormal, int length = -1);
429
433 Isolate* isolate, const uint8_t* data,
434 NewStringType type = NewStringType::kNormal, int length = -1);
435
439 Isolate* isolate, const uint16_t* data,
440 NewStringType type = NewStringType::kNormal, int length = -1);
441
447 Local<String> right);
448
458 Isolate* isolate, ExternalStringResource* resource);
459
470
480 Isolate* isolate, ExternalOneByteStringResource* resource);
481
492
497 bool CanMakeExternal(Encoding encoding) const;
498
503
512 public:
515 char* operator*() { return str_; }
516 const char* operator*() const { return str_; }
517 int length() const { return length_; }
518
519 // Disallow copying and assigning.
520 Utf8Value(const Utf8Value&) = delete;
521 void operator=(const Utf8Value&) = delete;
522
523 private:
524 char* str_;
525 int length_;
526 };
527
535 public:
538 uint16_t* operator*() { return str_; }
539 const uint16_t* operator*() const { return str_; }
540 int length() const { return length_; }
541
542 // Disallow copying and assigning.
543 Value(const Value&) = delete;
544 void operator=(const Value&) = delete;
545
546 private:
547 uint16_t* str_;
548 int length_;
549 };
550
551 private:
552 void VerifyExternalStringResourceBase(ExternalStringResourceBase* v,
553 Encoding encoding) const;
554 void VerifyExternalStringResource(ExternalStringResource* val) const;
555 ExternalStringResource* GetExternalStringResourceSlow() const;
556 ExternalStringResourceBase* GetExternalStringResourceBaseSlow(
557 String::Encoding* encoding_out) const;
558
559 static Local<v8::String> NewFromUtf8Literal(Isolate* isolate,
560 const char* literal,
561 NewStringType type, int length);
562
563 static void CheckCast(v8::Data* that);
564};
565
566// Zero-length string specialization (templated string size includes
567// terminator).
568template <>
570 Isolate* isolate, const char (&literal)[1], NewStringType type) {
571 return String::Empty(isolate);
572}
573
578 public:
579 virtual ~ExternalResourceVisitor() = default;
580 virtual void VisitExternalString(Local<String> string) {}
581};
582
586class V8_EXPORT Symbol : public Name {
587 public:
592
597 static Local<Symbol> New(Isolate* isolate,
598 Local<String> description = Local<String>());
599
608 static Local<Symbol> For(Isolate* isolate, Local<String> description);
609
614 static Local<Symbol> ForApi(Isolate* isolate, Local<String> description);
615
616 // Well-known symbols
628
629 V8_INLINE static Symbol* Cast(Data* data) {
630#ifdef V8_ENABLE_CHECKS
631 CheckCast(data);
632#endif
633 return static_cast<Symbol*>(data);
634 }
635
636 private:
637 Symbol();
638 static void CheckCast(Data* that);
639};
640
646 private:
647 Numeric();
648 static void CheckCast(v8::Data* that);
649};
650
654class V8_EXPORT Number : public Numeric {
655 public:
656 double Value() const;
657 static Local<Number> New(Isolate* isolate, double value);
658 V8_INLINE static Number* Cast(v8::Data* data) {
659#ifdef V8_ENABLE_CHECKS
660 CheckCast(data);
661#endif
662 return static_cast<Number*>(data);
663 }
664
665 private:
666 Number();
667 static void CheckCast(v8::Data* that);
668};
669
673class V8_EXPORT Integer : public Number {
674 public:
675 static Local<Integer> New(Isolate* isolate, int32_t value);
676 static Local<Integer> NewFromUnsigned(Isolate* isolate, uint32_t value);
677 int64_t Value() const;
679#ifdef V8_ENABLE_CHECKS
680 CheckCast(data);
681#endif
682 return static_cast<Integer*>(data);
683 }
684
685 private:
686 Integer();
687 static void CheckCast(v8::Data* that);
688};
689
693class V8_EXPORT Int32 : public Integer {
694 public:
695 int32_t Value() const;
696 V8_INLINE static Int32* Cast(v8::Data* data) {
697#ifdef V8_ENABLE_CHECKS
698 CheckCast(data);
699#endif
700 return static_cast<Int32*>(data);
701 }
702
703 private:
704 Int32();
705 static void CheckCast(v8::Data* that);
706};
707
711class V8_EXPORT Uint32 : public Integer {
712 public:
713 uint32_t Value() const;
714 V8_INLINE static Uint32* Cast(v8::Data* data) {
715#ifdef V8_ENABLE_CHECKS
716 CheckCast(data);
717#endif
718 return static_cast<Uint32*>(data);
719 }
720
721 private:
722 Uint32();
723 static void CheckCast(v8::Data* that);
724};
725
729class V8_EXPORT BigInt : public Numeric {
730 public:
731 static Local<BigInt> New(Isolate* isolate, int64_t value);
732 static Local<BigInt> NewFromUnsigned(Isolate* isolate, uint64_t value);
740 static MaybeLocal<BigInt> NewFromWords(Local<Context> context, int sign_bit,
741 int word_count, const uint64_t* words);
742
749 uint64_t Uint64Value(bool* lossless = nullptr) const;
750
756 int64_t Int64Value(bool* lossless = nullptr) const;
757
762 int WordCount() const;
763
772 void ToWordsArray(int* sign_bit, int* word_count, uint64_t* words) const;
773
774 V8_INLINE static BigInt* Cast(v8::Data* data) {
775#ifdef V8_ENABLE_CHECKS
776 CheckCast(data);
777#endif
778 return static_cast<BigInt*>(data);
779 }
780
781 private:
782 BigInt();
783 static void CheckCast(v8::Data* that);
784};
785
787 using S = internal::Address;
788 using I = internal::Internals;
789 I::CheckInitialized(isolate);
790 S* slot = I::GetRootSlot(isolate, I::kEmptyStringRootIndex);
791 return Local<String>::FromSlot(slot);
792}
793
795 using A = internal::Address;
796 using I = internal::Internals;
798
800 if (I::IsExternalTwoByteString(I::GetInstanceType(obj))) {
801 Isolate* isolate = I::GetIsolateForSandbox(obj);
802 A value = I::ReadExternalPointerField<internal::kExternalStringResourceTag>(
803 isolate, obj, I::kStringResourceOffset);
804 result = reinterpret_cast<String::ExternalStringResource*>(value);
805 } else {
806 result = GetExternalStringResourceSlow();
807 }
808#ifdef V8_ENABLE_CHECKS
809 VerifyExternalStringResource(result);
810#endif
811 return result;
812}
813
815 String::Encoding* encoding_out) const {
816 using A = internal::Address;
817 using I = internal::Internals;
819 int type = I::GetInstanceType(obj) & I::kStringRepresentationAndEncodingMask;
820 *encoding_out = static_cast<Encoding>(type & I::kStringEncodingMask);
822 if (type == I::kExternalOneByteRepresentationTag ||
823 type == I::kExternalTwoByteRepresentationTag) {
824 Isolate* isolate = I::GetIsolateForSandbox(obj);
825 A value = I::ReadExternalPointerField<internal::kExternalStringResourceTag>(
826 isolate, obj, I::kStringResourceOffset);
827 resource = reinterpret_cast<ExternalStringResourceBase*>(value);
828 } else {
829 resource = GetExternalStringResourceBaseSlow(encoding_out);
830 }
831#ifdef V8_ENABLE_CHECKS
832 VerifyExternalStringResourceBase(resource, *encoding_out);
833#endif
834 return resource;
835}
836
837// --- Statics ---
838
840 using S = internal::Address;
841 using I = internal::Internals;
842 I::CheckInitialized(isolate);
843 S* slot = I::GetRootSlot(isolate, I::kUndefinedValueRootIndex);
844 return Local<Primitive>::FromSlot(slot);
845}
846
848 using S = internal::Address;
849 using I = internal::Internals;
850 I::CheckInitialized(isolate);
851 S* slot = I::GetRootSlot(isolate, I::kNullValueRootIndex);
852 return Local<Primitive>::FromSlot(slot);
853}
854
856 using S = internal::Address;
857 using I = internal::Internals;
858 I::CheckInitialized(isolate);
859 S* slot = I::GetRootSlot(isolate, I::kTrueValueRootIndex);
860 return Local<Boolean>::FromSlot(slot);
861}
862
864 using S = internal::Address;
865 using I = internal::Internals;
866 I::CheckInitialized(isolate);
867 S* slot = I::GetRootSlot(isolate, I::kFalseValueRootIndex);
868 return Local<Boolean>::FromSlot(slot);
869}
870
871Local<Boolean> Boolean::New(Isolate* isolate, bool value) {
872 return value ? True(isolate) : False(isolate);
873}
874
875} // namespace v8
876
877#endif // INCLUDE_V8_PRIMITIVE_H_
static MaybeLocal< BigInt > NewFromWords(Local< Context > context, int sign_bit, int word_count, const uint64_t *words)
static Local< BigInt > New(Isolate *isolate, int64_t value)
void ToWordsArray(int *sign_bit, int *word_count, uint64_t *words) const
uint64_t Uint64Value(bool *lossless=nullptr) const
static V8_INLINE BigInt * Cast(v8::Data *data)
int WordCount() const
static Local< BigInt > NewFromUnsigned(Isolate *isolate, uint64_t value)
int64_t Int64Value(bool *lossless=nullptr) const
bool Value() const
static V8_INLINE Boolean * Cast(v8::Data *data)
static V8_INLINE Local< Boolean > New(Isolate *isolate, bool value)
virtual void VisitExternalString(Local< String > string)
virtual ~ExternalResourceVisitor()=default
int32_t Value() const
static V8_INLINE Int32 * Cast(v8::Data *data)
int64_t Value() const
static Local< Integer > New(Isolate *isolate, int32_t value)
static V8_INLINE Integer * Cast(v8::Data *data)
static Local< Integer > NewFromUnsigned(Isolate *isolate, uint32_t value)
static V8_INLINE Name * Cast(Data *data)
int GetIdentityHash()
static V8_INLINE Number * Cast(v8::Data *data)
double Value() const
static Local< Number > New(Isolate *isolate, double value)
void Set(Isolate *isolate, int index, Local< Primitive > item)
int Length() const
Local< Primitive > Get(Isolate *isolate, int index)
static Local< PrimitiveArray > New(Isolate *isolate, int length)
static V8_INLINE PrimitiveArray * Cast(Data *data)
~ExternalOneByteStringResource() override=default
virtual const char * data() const =0
virtual ~ExternalStringResourceBase()=default
void operator=(const ExternalStringResourceBase &)=delete
ExternalStringResourceBase(const ExternalStringResourceBase &)=delete
~ExternalStringResource() override=default
const uint16_t * cached_data() const
virtual const uint16_t * data() const =0
virtual size_t length() const =0
void operator=(const Utf8Value &)=delete
const char * operator*() const
Utf8Value(const Utf8Value &)=delete
Utf8Value(Isolate *isolate, Local< v8::Value > obj)
const uint16_t * operator*() const
uint16_t * operator*()
void operator=(const Value &)=delete
Value(Isolate *isolate, Local< v8::Value > obj)
int length() const
Value(const Value &)=delete
bool ContainsOnlyOneByte() const
static V8_WARN_UNUSED_RESULT MaybeLocal< String > NewFromTwoByte(Isolate *isolate, const uint16_t *data, NewStringType type=NewStringType::kNormal, int length=-1)
V8_INLINE ExternalStringResource * GetExternalStringResource() const
bool IsExternalTwoByte() const
static V8_WARN_UNUSED_RESULT Local< String > NewFromUtf8Literal(Isolate *isolate, const char(&literal)[N], NewStringType type=NewStringType::kNormal)
int Length() const
bool IsOneByte() const
bool MakeExternal(ExternalStringResource *resource)
static V8_INLINE String * Cast(v8::Data *data)
static V8_INLINE Local< String > Empty(Isolate *isolate)
const ExternalOneByteStringResource * GetExternalOneByteStringResource() const
V8_INLINE ExternalStringResourceBase * GetExternalStringResourceBase(Encoding *encoding_out) const
int WriteUtf8(Isolate *isolate, char *buffer, int length=-1, int *nchars_ref=nullptr, int options=NO_OPTIONS) const
int WriteOneByte(Isolate *isolate, uint8_t *buffer, int start=0, int length=-1, int options=NO_OPTIONS) const
bool MakeExternal(ExternalOneByteStringResource *resource)
bool StringEquals(Local< String > str) const
static V8_WARN_UNUSED_RESULT MaybeLocal< String > NewExternalTwoByte(Isolate *isolate, ExternalStringResource *resource)
static V8_WARN_UNUSED_RESULT MaybeLocal< String > NewFromUtf8(Isolate *isolate, const char *data, NewStringType type=NewStringType::kNormal, int length=-1)
static Local< String > Concat(Isolate *isolate, Local< String > left, Local< String > right)
bool IsExternalOneByte() const
int Utf8Length(Isolate *isolate) const
static V8_WARN_UNUSED_RESULT MaybeLocal< String > NewExternalOneByte(Isolate *isolate, ExternalOneByteStringResource *resource)
bool CanMakeExternal(Encoding encoding) const
bool IsExternal() const
int Write(Isolate *isolate, uint16_t *buffer, int start=0, int length=-1, int options=NO_OPTIONS) const
static V8_WARN_UNUSED_RESULT MaybeLocal< String > NewFromOneByte(Isolate *isolate, const uint8_t *data, NewStringType type=NewStringType::kNormal, int length=-1)
static Local< Symbol > New(Isolate *isolate, Local< String > description=Local< String >())
static Local< Symbol > GetIterator(Isolate *isolate)
static V8_INLINE Symbol * Cast(Data *data)
static Local< Symbol > GetToPrimitive(Isolate *isolate)
static Local< Symbol > GetHasInstance(Isolate *isolate)
static Local< Symbol > GetIsConcatSpreadable(Isolate *isolate)
static Local< Symbol > GetToStringTag(Isolate *isolate)
static Local< Symbol > ForApi(Isolate *isolate, Local< String > description)
static Local< Symbol > GetReplace(Isolate *isolate)
Local< Value > Description(Isolate *isolate) const
static Local< Symbol > For(Isolate *isolate, Local< String > description)
static Local< Symbol > GetAsyncIterator(Isolate *isolate)
static Local< Symbol > GetMatch(Isolate *isolate)
static Local< Symbol > GetSplit(Isolate *isolate)
static Local< Symbol > GetUnscopables(Isolate *isolate)
static Local< Symbol > GetSearch(Isolate *isolate)
static V8_INLINE Uint32 * Cast(v8::Data *data)
uint32_t Value() const
static V8_INLINE Address ValueAsAddress(const T *value)
uintptr_t Address
Definition v8-internal.h:31
V8_INLINE Local< Primitive > Null(Isolate *isolate)
V8_INLINE Local< Boolean > True(Isolate *isolate)
V8_INLINE Local< Boolean > False(Isolate *isolate)
V8_INLINE Local< Primitive > Undefined(Isolate *isolate)
NewStringType
#define V8_EXPORT
Definition v8config.h:753
#define V8_INLINE
Definition v8config.h:477
#define V8_WARN_UNUSED_RESULT
Definition v8config.h:628