v8 11.3.244 (node 20.3.0)
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
316 void UpdateDataCache();
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;
376
377 const char* cached_data_ = nullptr;
378 };
379
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
496 V8_DEPRECATE_SOON("Use the version that takes an encoding as argument.")
497 bool CanMakeExternal() const;
498
503 bool CanMakeExternal(Encoding encoding) const;
504
508 bool StringEquals(Local<String> str) const;
509
518 public:
521 char* operator*() { return str_; }
522 const char* operator*() const { return str_; }
523 int length() const { return length_; }
524
525 // Disallow copying and assigning.
526 Utf8Value(const Utf8Value&) = delete;
527 void operator=(const Utf8Value&) = delete;
528
529 private:
530 char* str_;
531 int length_;
532 };
533
541 public:
544 uint16_t* operator*() { return str_; }
545 const uint16_t* operator*() const { return str_; }
546 int length() const { return length_; }
547
548 // Disallow copying and assigning.
549 Value(const Value&) = delete;
550 void operator=(const Value&) = delete;
551
552 private:
553 uint16_t* str_;
554 int length_;
555 };
556
557 private:
558 void VerifyExternalStringResourceBase(ExternalStringResourceBase* v,
559 Encoding encoding) const;
560 void VerifyExternalStringResource(ExternalStringResource* val) const;
561 ExternalStringResource* GetExternalStringResourceSlow() const;
562 ExternalStringResourceBase* GetExternalStringResourceBaseSlow(
563 String::Encoding* encoding_out) const;
564
565 static Local<v8::String> NewFromUtf8Literal(Isolate* isolate,
566 const char* literal,
567 NewStringType type, int length);
568
569 static void CheckCast(v8::Data* that);
570};
571
572// Zero-length string specialization (templated string size includes
573// terminator).
574template <>
576 Isolate* isolate, const char (&literal)[1], NewStringType type) {
577 return String::Empty(isolate);
578}
579
584 public:
585 virtual ~ExternalResourceVisitor() = default;
586 virtual void VisitExternalString(Local<String> string) {}
587};
588
592class V8_EXPORT Symbol : public Name {
593 public:
598
603 static Local<Symbol> New(Isolate* isolate,
604 Local<String> description = Local<String>());
605
614 static Local<Symbol> For(Isolate* isolate, Local<String> description);
615
620 static Local<Symbol> ForApi(Isolate* isolate, Local<String> description);
621
622 // Well-known symbols
634
635 V8_INLINE static Symbol* Cast(Data* data) {
636#ifdef V8_ENABLE_CHECKS
637 CheckCast(data);
638#endif
639 return static_cast<Symbol*>(data);
640 }
641
642 private:
643 Symbol();
644 static void CheckCast(Data* that);
645};
646
650class V8_EXPORT Number : public Primitive {
651 public:
652 double Value() const;
653 static Local<Number> New(Isolate* isolate, double value);
654 V8_INLINE static Number* Cast(v8::Data* data) {
655#ifdef V8_ENABLE_CHECKS
656 CheckCast(data);
657#endif
658 return static_cast<Number*>(data);
659 }
660
661 private:
662 Number();
663 static void CheckCast(v8::Data* that);
664};
665
669class V8_EXPORT Integer : public Number {
670 public:
671 static Local<Integer> New(Isolate* isolate, int32_t value);
672 static Local<Integer> NewFromUnsigned(Isolate* isolate, uint32_t value);
673 int64_t Value() const;
675#ifdef V8_ENABLE_CHECKS
676 CheckCast(data);
677#endif
678 return static_cast<Integer*>(data);
679 }
680
681 private:
682 Integer();
683 static void CheckCast(v8::Data* that);
684};
685
689class V8_EXPORT Int32 : public Integer {
690 public:
691 int32_t Value() const;
692 V8_INLINE static Int32* Cast(v8::Data* data) {
693#ifdef V8_ENABLE_CHECKS
694 CheckCast(data);
695#endif
696 return static_cast<Int32*>(data);
697 }
698
699 private:
700 Int32();
701 static void CheckCast(v8::Data* that);
702};
703
707class V8_EXPORT Uint32 : public Integer {
708 public:
709 uint32_t Value() const;
710 V8_INLINE static Uint32* Cast(v8::Data* data) {
711#ifdef V8_ENABLE_CHECKS
712 CheckCast(data);
713#endif
714 return static_cast<Uint32*>(data);
715 }
716
717 private:
718 Uint32();
719 static void CheckCast(v8::Data* that);
720};
721
725class V8_EXPORT BigInt : public Primitive {
726 public:
727 static Local<BigInt> New(Isolate* isolate, int64_t value);
728 static Local<BigInt> NewFromUnsigned(Isolate* isolate, uint64_t value);
736 static MaybeLocal<BigInt> NewFromWords(Local<Context> context, int sign_bit,
737 int word_count, const uint64_t* words);
738
745 uint64_t Uint64Value(bool* lossless = nullptr) const;
746
752 int64_t Int64Value(bool* lossless = nullptr) const;
753
758 int WordCount() const;
759
768 void ToWordsArray(int* sign_bit, int* word_count, uint64_t* words) const;
769
770 V8_INLINE static BigInt* Cast(v8::Data* data) {
771#ifdef V8_ENABLE_CHECKS
772 CheckCast(data);
773#endif
774 return static_cast<BigInt*>(data);
775 }
776
777 private:
778 BigInt();
779 static void CheckCast(v8::Data* that);
780};
781
783 using S = internal::Address;
784 using I = internal::Internals;
785 I::CheckInitialized(isolate);
786 S* slot = I::GetRootSlot(isolate, I::kEmptyStringRootIndex);
787 return Local<String>::FromSlot(slot);
788}
789
791 using A = internal::Address;
792 using I = internal::Internals;
794
796 if (I::IsExternalTwoByteString(I::GetInstanceType(obj))) {
797 Isolate* isolate = I::GetIsolateForSandbox(obj);
798 A value = I::ReadExternalPointerField<internal::kExternalStringResourceTag>(
799 isolate, obj, I::kStringResourceOffset);
800 result = reinterpret_cast<String::ExternalStringResource*>(value);
801 } else {
802 result = GetExternalStringResourceSlow();
803 }
804#ifdef V8_ENABLE_CHECKS
805 VerifyExternalStringResource(result);
806#endif
807 return result;
808}
809
811 String::Encoding* encoding_out) const {
812 using A = internal::Address;
813 using I = internal::Internals;
815 int type = I::GetInstanceType(obj) & I::kStringRepresentationAndEncodingMask;
816 *encoding_out = static_cast<Encoding>(type & I::kStringEncodingMask);
818 if (type == I::kExternalOneByteRepresentationTag ||
819 type == I::kExternalTwoByteRepresentationTag) {
820 Isolate* isolate = I::GetIsolateForSandbox(obj);
821 A value = I::ReadExternalPointerField<internal::kExternalStringResourceTag>(
822 isolate, obj, I::kStringResourceOffset);
823 resource = reinterpret_cast<ExternalStringResourceBase*>(value);
824 } else {
825 resource = GetExternalStringResourceBaseSlow(encoding_out);
826 }
827#ifdef V8_ENABLE_CHECKS
828 VerifyExternalStringResourceBase(resource, *encoding_out);
829#endif
830 return resource;
831}
832
833// --- Statics ---
834
836 using S = internal::Address;
837 using I = internal::Internals;
838 I::CheckInitialized(isolate);
839 S* slot = I::GetRootSlot(isolate, I::kUndefinedValueRootIndex);
840 return Local<Primitive>::FromSlot(slot);
841}
842
844 using S = internal::Address;
845 using I = internal::Internals;
846 I::CheckInitialized(isolate);
847 S* slot = I::GetRootSlot(isolate, I::kNullValueRootIndex);
848 return Local<Primitive>::FromSlot(slot);
849}
850
852 using S = internal::Address;
853 using I = internal::Internals;
854 I::CheckInitialized(isolate);
855 S* slot = I::GetRootSlot(isolate, I::kTrueValueRootIndex);
856 return Local<Boolean>::FromSlot(slot);
857}
858
860 using S = internal::Address;
861 using I = internal::Internals;
862 I::CheckInitialized(isolate);
863 S* slot = I::GetRootSlot(isolate, I::kFalseValueRootIndex);
864 return Local<Boolean>::FromSlot(slot);
865}
866
867Local<Boolean> Boolean::New(Isolate* isolate, bool value) {
868 return value ? True(isolate) : False(isolate);
869}
870
871} // namespace v8
872
873#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)
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 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:29
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:719
#define V8_INLINE
Definition v8config.h:460
#define V8_DEPRECATE_SOON(message)
Definition v8config.h:552
#define V8_WARN_UNUSED_RESULT
Definition v8config.h:609