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 };
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
497 bool CanMakeExternal(Encoding encoding) const;
498
503
512 public:
514 WriteOptions options = REPLACE_INVALID_UTF8);
516 char* operator*() { return str_; }
517 const char* operator*() const { return str_; }
518 int length() const { return length_; }
519
520 // Disallow copying and assigning.
521 Utf8Value(const Utf8Value&) = delete;
522 void operator=(const Utf8Value&) = delete;
523
524 private:
525 char* str_;
526 int length_;
527 };
528
536 public:
539 uint16_t* operator*() { return str_; }
540 const uint16_t* operator*() const { return str_; }
541 int length() const { return length_; }
542
543 // Disallow copying and assigning.
544 Value(const Value&) = delete;
545 void operator=(const Value&) = delete;
546
547 private:
548 uint16_t* str_;
549 int length_;
550 };
551
552 private:
553 void VerifyExternalStringResourceBase(ExternalStringResourceBase* v,
554 Encoding encoding) const;
555 void VerifyExternalStringResource(ExternalStringResource* val) const;
556 ExternalStringResource* GetExternalStringResourceSlow() const;
557 ExternalStringResourceBase* GetExternalStringResourceBaseSlow(
558 String::Encoding* encoding_out) const;
559
560 static Local<v8::String> NewFromUtf8Literal(Isolate* isolate,
561 const char* literal,
562 NewStringType type, int length);
563
564 static void CheckCast(v8::Data* that);
565};
566
567// Zero-length string specialization (templated string size includes
568// terminator).
569template <>
571 Isolate* isolate, const char (&literal)[1], NewStringType type) {
572 return String::Empty(isolate);
573}
574
579 public:
580 virtual ~ExternalResourceVisitor() = default;
581 virtual void VisitExternalString(Local<String> string) {}
582};
583
587class V8_EXPORT Symbol : public Name {
588 public:
593
598 static Local<Symbol> New(Isolate* isolate,
599 Local<String> description = Local<String>());
600
609 static Local<Symbol> For(Isolate* isolate, Local<String> description);
610
615 static Local<Symbol> ForApi(Isolate* isolate, Local<String> description);
616
617 // Well-known symbols
629
630 V8_INLINE static Symbol* Cast(Data* data) {
631#ifdef V8_ENABLE_CHECKS
632 CheckCast(data);
633#endif
634 return static_cast<Symbol*>(data);
635 }
636
637 private:
638 Symbol();
639 static void CheckCast(Data* that);
640};
641
647 private:
648 Numeric();
649 static void CheckCast(v8::Data* that);
650};
651
655class V8_EXPORT Number : public Numeric {
656 public:
657 double Value() const;
658 static Local<Number> New(Isolate* isolate, double value);
659 V8_INLINE static Number* Cast(v8::Data* data) {
660#ifdef V8_ENABLE_CHECKS
661 CheckCast(data);
662#endif
663 return static_cast<Number*>(data);
664 }
665
666 private:
667 Number();
668 static void CheckCast(v8::Data* that);
669};
670
674class V8_EXPORT Integer : public Number {
675 public:
676 static Local<Integer> New(Isolate* isolate, int32_t value);
677 static Local<Integer> NewFromUnsigned(Isolate* isolate, uint32_t value);
678 int64_t Value() const;
680#ifdef V8_ENABLE_CHECKS
681 CheckCast(data);
682#endif
683 return static_cast<Integer*>(data);
684 }
685
686 private:
687 Integer();
688 static void CheckCast(v8::Data* that);
689};
690
694class V8_EXPORT Int32 : public Integer {
695 public:
696 int32_t Value() const;
697 V8_INLINE static Int32* Cast(v8::Data* data) {
698#ifdef V8_ENABLE_CHECKS
699 CheckCast(data);
700#endif
701 return static_cast<Int32*>(data);
702 }
703
704 private:
705 Int32();
706 static void CheckCast(v8::Data* that);
707};
708
712class V8_EXPORT Uint32 : public Integer {
713 public:
714 uint32_t Value() const;
715 V8_INLINE static Uint32* Cast(v8::Data* data) {
716#ifdef V8_ENABLE_CHECKS
717 CheckCast(data);
718#endif
719 return static_cast<Uint32*>(data);
720 }
721
722 private:
723 Uint32();
724 static void CheckCast(v8::Data* that);
725};
726
730class V8_EXPORT BigInt : public Numeric {
731 public:
732 static Local<BigInt> New(Isolate* isolate, int64_t value);
733 static Local<BigInt> NewFromUnsigned(Isolate* isolate, uint64_t value);
741 static MaybeLocal<BigInt> NewFromWords(Local<Context> context, int sign_bit,
742 int word_count, const uint64_t* words);
743
750 uint64_t Uint64Value(bool* lossless = nullptr) const;
751
757 int64_t Int64Value(bool* lossless = nullptr) const;
758
763 int WordCount() const;
764
773 void ToWordsArray(int* sign_bit, int* word_count, uint64_t* words) const;
774
775 V8_INLINE static BigInt* Cast(v8::Data* data) {
776#ifdef V8_ENABLE_CHECKS
777 CheckCast(data);
778#endif
779 return static_cast<BigInt*>(data);
780 }
781
782 private:
783 BigInt();
784 static void CheckCast(v8::Data* that);
785};
786
788 using S = internal::Address;
789 using I = internal::Internals;
790 I::CheckInitialized(isolate);
791 S* slot = I::GetRootSlot(isolate, I::kEmptyStringRootIndex);
792 return Local<String>::FromSlot(slot);
793}
794
796 using A = internal::Address;
797 using I = internal::Internals;
799
801 if (I::IsExternalTwoByteString(I::GetInstanceType(obj))) {
802 Isolate* isolate = I::GetIsolateForSandbox(obj);
803 A value = I::ReadExternalPointerField<internal::kExternalStringResourceTag>(
804 isolate, obj, I::kStringResourceOffset);
805 result = reinterpret_cast<String::ExternalStringResource*>(value);
806 } else {
807 result = GetExternalStringResourceSlow();
808 }
809#ifdef V8_ENABLE_CHECKS
810 VerifyExternalStringResource(result);
811#endif
812 return result;
813}
814
816 String::Encoding* encoding_out) const {
817 using A = internal::Address;
818 using I = internal::Internals;
820 int type = I::GetInstanceType(obj) & I::kStringRepresentationAndEncodingMask;
821 *encoding_out = static_cast<Encoding>(type & I::kStringEncodingMask);
823 if (type == I::kExternalOneByteRepresentationTag ||
824 type == I::kExternalTwoByteRepresentationTag) {
825 Isolate* isolate = I::GetIsolateForSandbox(obj);
826 A value = I::ReadExternalPointerField<internal::kExternalStringResourceTag>(
827 isolate, obj, I::kStringResourceOffset);
828 resource = reinterpret_cast<ExternalStringResourceBase*>(value);
829 } else {
830 resource = GetExternalStringResourceBaseSlow(encoding_out);
831 }
832#ifdef V8_ENABLE_CHECKS
833 VerifyExternalStringResourceBase(resource, *encoding_out);
834#endif
835 return resource;
836}
837
838// --- Statics ---
839
841 using S = internal::Address;
842 using I = internal::Internals;
843 I::CheckInitialized(isolate);
844 S* slot = I::GetRootSlot(isolate, I::kUndefinedValueRootIndex);
845 return Local<Primitive>::FromSlot(slot);
846}
847
849 using S = internal::Address;
850 using I = internal::Internals;
851 I::CheckInitialized(isolate);
852 S* slot = I::GetRootSlot(isolate, I::kNullValueRootIndex);
853 return Local<Primitive>::FromSlot(slot);
854}
855
857 using S = internal::Address;
858 using I = internal::Internals;
859 I::CheckInitialized(isolate);
860 S* slot = I::GetRootSlot(isolate, I::kTrueValueRootIndex);
861 return Local<Boolean>::FromSlot(slot);
862}
863
865 using S = internal::Address;
866 using I = internal::Internals;
867 I::CheckInitialized(isolate);
868 S* slot = I::GetRootSlot(isolate, I::kFalseValueRootIndex);
869 return Local<Boolean>::FromSlot(slot);
870}
871
872Local<Boolean> Boolean::New(Isolate* isolate, bool value) {
873 return value ? True(isolate) : False(isolate);
874}
875
876} // namespace v8
877
878#endif // INCLUDE_V8_PRIMITIVE_H_
Definition: v8-primitive.h:730
uint64_t Uint64Value(bool *lossless=nullptr) const
static BigInt * Cast(v8::Data *data)
Definition: v8-primitive.h:775
static Local< BigInt > New(Isolate *isolate, int64_t value)
int64_t Int64Value(bool *lossless=nullptr) const
static MaybeLocal< BigInt > NewFromWords(Local< Context > context, int sign_bit, int word_count, const uint64_t *words)
int WordCount() const
static Local< BigInt > NewFromUnsigned(Isolate *isolate, uint64_t value)
void ToWordsArray(int *sign_bit, int *word_count, uint64_t *words) const
Definition: v8-primitive.h:35
bool Value() const
static Local< Boolean > New(Isolate *isolate, bool value)
Definition: v8-primitive.h:872
static Boolean * Cast(v8::Data *data)
Definition: v8-primitive.h:38
Definition: v8-data.h:18
Definition: v8-primitive.h:578
virtual ~ExternalResourceVisitor()=default
virtual void VisitExternalString(Local< String > string)
Definition: v8-primitive.h:581
Definition: v8-primitive.h:694
static Int32 * Cast(v8::Data *data)
Definition: v8-primitive.h:697
int32_t Value() const
Definition: v8-primitive.h:674
static Integer * Cast(v8::Data *data)
Definition: v8-primitive.h:679
static Local< Integer > New(Isolate *isolate, int32_t value)
static Local< Integer > NewFromUnsigned(Isolate *isolate, uint32_t value)
int64_t Value() const
Definition: v8-isolate.h:210
Definition: v8-local-handle.h:256
Definition: v8-local-handle.h:615
Definition: v8-primitive.h:79
static Name * Cast(Data *data)
Definition: v8-primitive.h:90
int GetIdentityHash()
Definition: v8-primitive.h:655
static Local< Number > New(Isolate *isolate, double value)
static Number * Cast(v8::Data *data)
Definition: v8-primitive.h:659
double Value() const
Definition: v8-primitive.h:646
Definition: v8-primitive.h:58
static Local< PrimitiveArray > New(Isolate *isolate, int length)
Local< Primitive > Get(Isolate *isolate, int index)
static PrimitiveArray * Cast(Data *data)
Definition: v8-primitive.h:65
int Length() const
void Set(Isolate *isolate, int index, Local< Primitive > item)
Definition: v8-primitive.h:29
Definition: v8-primitive.h:338
const char * cached_data() const
Definition: v8-primitive.h:360
~ExternalOneByteStringResource() override=default
virtual const char * data() const =0
Definition: v8-primitive.h:226
void operator=(const ExternalStringResourceBase &)=delete
ExternalStringResourceBase(const ExternalStringResourceBase &)=delete
virtual ~ExternalStringResourceBase()=default
virtual void Unlock() const
Definition: v8-primitive.h:268
virtual bool IsCacheable() const
Definition: v8-primitive.h:235
virtual void Lock() const
Definition: v8-primitive.h:263
virtual void Dispose()
Definition: v8-primitive.h:250
Definition: v8-primitive.h:283
virtual const uint16_t * data() const =0
const uint16_t * cached_data() const
Definition: v8-primitive.h:307
virtual size_t length() const =0
~ExternalStringResource() override=default
Definition: v8-primitive.h:511
char * operator*()
Definition: v8-primitive.h:516
Utf8Value(Isolate *isolate, Local< v8::Value > obj, WriteOptions options=REPLACE_INVALID_UTF8)
Utf8Value(const Utf8Value &)=delete
const char * operator*() const
Definition: v8-primitive.h:517
void operator=(const Utf8Value &)=delete
int length() const
Definition: v8-primitive.h:518
Definition: v8-primitive.h:535
const uint16_t * operator*() const
Definition: v8-primitive.h:540
uint16_t * operator*()
Definition: v8-primitive.h:539
Value(Isolate *isolate, Local< v8::Value > obj)
Value(const Value &)=delete
void operator=(const Value &)=delete
int length() const
Definition: v8-primitive.h:541
Definition: v8-primitive.h:124
bool IsExternalTwoByte() const
bool IsExternal() const
static Local< String > Concat(Isolate *isolate, Local< String > left, Local< String > right)
bool IsExternalOneByte() const
bool ContainsOnlyOneByte() const
Encoding
Definition: v8-primitive.h:129
ExternalStringResourceBase * GetExternalStringResourceBase(Encoding *encoding_out) const
Definition: v8-primitive.h:815
static MaybeLocal< String > NewExternalOneByte(Isolate *isolate, ExternalOneByteStringResource *resource)
bool StringEquals(Local< String > str) const
bool MakeExternal(ExternalStringResource *resource)
bool MakeExternal(ExternalOneByteStringResource *resource)
int WriteOneByte(Isolate *isolate, uint8_t *buffer, int start=0, int length=-1, int options=NO_OPTIONS) const
static MaybeLocal< String > NewFromUtf8(Isolate *isolate, const char *data, NewStringType type=NewStringType::kNormal, int length=-1)
int Write(Isolate *isolate, uint16_t *buffer, int start=0, int length=-1, int options=NO_OPTIONS) const
int WriteUtf8(Isolate *isolate, char *buffer, int length=-1, int *nchars_ref=nullptr, int options=NO_OPTIONS) const
const ExternalOneByteStringResource * GetExternalOneByteStringResource() const
static MaybeLocal< String > NewExternalTwoByte(Isolate *isolate, ExternalStringResource *resource)
static MaybeLocal< String > NewFromOneByte(Isolate *isolate, const uint8_t *data, NewStringType type=NewStringType::kNormal, int length=-1)
bool IsOneByte() const
static String * Cast(v8::Data *data)
Definition: v8-primitive.h:400
WriteOptions
Definition: v8-primitive.h:185
static Local< String > Empty(Isolate *isolate)
Definition: v8-primitive.h:787
static MaybeLocal< String > NewFromTwoByte(Isolate *isolate, const uint16_t *data, NewStringType type=NewStringType::kNormal, int length=-1)
static Local< String > NewFromUtf8Literal(Isolate *isolate, const char(&literal)[N], NewStringType type=NewStringType::kNormal)
Definition: v8-primitive.h:417
ExternalStringResource * GetExternalStringResource() const
Definition: v8-primitive.h:795
bool CanMakeExternal(Encoding encoding) const
int Utf8Length(Isolate *isolate) const
int Length() const
Definition: v8-primitive.h:587
static Local< Symbol > GetMatch(Isolate *isolate)
static Local< Symbol > GetIterator(Isolate *isolate)
static Symbol * Cast(Data *data)
Definition: v8-primitive.h:630
static Local< Symbol > ForApi(Isolate *isolate, Local< String > description)
static Local< Symbol > GetSearch(Isolate *isolate)
static Local< Symbol > GetToPrimitive(Isolate *isolate)
static Local< Symbol > GetAsyncIterator(Isolate *isolate)
static Local< Symbol > GetIsConcatSpreadable(Isolate *isolate)
static Local< Symbol > New(Isolate *isolate, Local< String > description=Local< String >())
static Local< Symbol > GetReplace(Isolate *isolate)
static Local< Symbol > GetToStringTag(Isolate *isolate)
static Local< Symbol > GetSplit(Isolate *isolate)
static Local< Symbol > GetUnscopables(Isolate *isolate)
static Local< Symbol > For(Isolate *isolate, Local< String > description)
Local< Value > Description(Isolate *isolate) const
static Local< Symbol > GetHasInstance(Isolate *isolate)
Definition: v8-primitive.h:712
static Uint32 * Cast(v8::Data *data)
Definition: v8-primitive.h:715
uint32_t Value() const
Definition: v8-value.h:32
Definition: v8-internal.h:794
static Address ValueAsAddress(const T *value)
Definition: v8-internal.h:1544
uintptr_t Address
Definition: v8-internal.h:33
Definition: libplatform.h:15
Local< Primitive > Null(Isolate *isolate)
Definition: v8-primitive.h:848
Local< Primitive > Undefined(Isolate *isolate)
Definition: v8-primitive.h:840
Local< Boolean > False(Isolate *isolate)
Definition: v8-primitive.h:864
Local< Boolean > True(Isolate *isolate)
Definition: v8-primitive.h:856
NewStringType
Definition: v8-primitive.h:107
#define V8_EXPORT
Definition: v8config.h:771
#define V8_INLINE
Definition: v8config.h:485
#define V8_WARN_UNUSED_RESULT
Definition: v8config.h:646