v8-primitive.h

Go to the documentation of this file.

// Copyright 2021 the V8 project authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
 
#ifndef INCLUDE_V8_PRIMITIVE_H_
#define INCLUDE_V8_PRIMITIVE_H_
 
#include <string_view>
 
#include "v8-data.h"          // NOLINT(build/include_directory)
#include "v8-internal.h"      // NOLINT(build/include_directory)
#include "v8-local-handle.h"  // NOLINT(build/include_directory)
#include "v8-sandbox.h"       // NOLINT(build/include_directory)
#include "v8-value.h"         // NOLINT(build/include_directory)
#include "v8config.h"         // NOLINT(build/include_directory)
 
namespace v8 {
 
class Context;
class Isolate;
class String;
 
namespace internal {
class ExternalString;
class ExternalStringResourceWrapper;
class ScopedExternalStringLock;
class StringForwardingTable;
}  // namespace internal
 
class V8_EXPORT Primitive : public Value {};
 
class V8_EXPORT Boolean : public Primitive {
 public:
  bool Value() const;
  V8_INLINE static Boolean* Cast(v8::Data* data) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(data);
#endif
    return static_cast<Boolean*>(data);
  }
 
  V8_INLINE static Local<Boolean> New(Isolate* isolate, bool value);
 
 private:
  static void CheckCast(v8::Data* that);
};
 
class V8_EXPORT PrimitiveArray : public Data {
 public:
  static Local<PrimitiveArray> New(Isolate* isolate, int length);
  int Length() const;
  void Set(Isolate* isolate, int index, Local<Primitive> item);
  Local<Primitive> Get(Isolate* isolate, int index);
 
  V8_INLINE static PrimitiveArray* Cast(Data* data) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(data);
#endif
    return reinterpret_cast<PrimitiveArray*>(data);
  }
 
 private:
  static void CheckCast(Data* obj);
};
 
class V8_EXPORT Name : public Primitive {
 public:
  int GetIdentityHash();
 
  V8_INLINE static Name* Cast(Data* data) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(data);
#endif
    return static_cast<Name*>(data);
  }
 
 private:
  static void CheckCast(Data* that);
};
 
enum class NewStringType {
  kNormal,
 
  kInternalized
};
 
class V8_EXPORT String : public Name {
 public:
#ifndef V8_LOWER_LIMITS_MODE
  static constexpr int kMaxLength =
      internal::kApiSystemPointerSize == 4 ? (1 << 28) - 16 : (1 << 29) - 24;
#else
  static constexpr int kMaxLength = 1 << 20;
#endif  // V8_LOWER_LIMITS_MODE
 
  enum Encoding {
    UNKNOWN_ENCODING = 0x1,
    TWO_BYTE_ENCODING = 0x0,
    ONE_BYTE_ENCODING = 0x8
  };
  int Length() const;
 
  size_t Utf8Length(Isolate* isolate) const;
  // TODO(http://crbug.com/373485796): deprecate and remove.
  V8_DEPRECATE_SOON("Use Utf8Length(isolate) instead.")
  size_t Utf8LengthV2(Isolate* isolate) const { return Utf8Length(isolate); }
 
  bool IsOneByte() const;
 
  bool ContainsOnlyOneByte() const;
 
  struct WriteFlags {
    enum {
      kNone = 0,
      // Indicates that the output string should be null-terminated. In that
      // case, the output buffer must include sufficient space for the
      // additional null character.
      kNullTerminate = 1,
      // Used by WriteUtf8 to replace orphan surrogate code units with the
      // unicode replacement character. Needs to be set to guarantee valid UTF-8
      // output.
      kReplaceInvalidUtf8 = 2
    };
  };
 
  void Write(Isolate* isolate, uint32_t offset, uint32_t length,
             uint16_t* buffer, int flags = WriteFlags::kNone) const;
  void WriteOneByte(Isolate* isolate, uint32_t offset, uint32_t length,
                    uint8_t* buffer, int flags = WriteFlags::kNone) const;
  // TODO(http://crbug.com/373485796): deprecate and remove.
  V8_DEPRECATE_SOON("Use Write(..) instead.")
  void WriteV2(Isolate* isolate, uint32_t offset, uint32_t length,
               uint16_t* buffer, int flags = WriteFlags::kNone) const {
    Write(isolate, offset, length, buffer, flags);
  }
  // TODO(http://crbug.com/373485796): deprecate and remove.
  V8_DEPRECATE_SOON("Use WriteOneByte(..) instead.")
  void WriteOneByteV2(Isolate* isolate, uint32_t offset, uint32_t length,
                      uint8_t* buffer, int flags = WriteFlags::kNone) const {
    WriteOneByte(isolate, offset, length, buffer, flags);
  }
 
  size_t WriteUtf8(Isolate* isolate, char* buffer, size_t capacity,
                   int flags = WriteFlags::kNone,
                   size_t* processed_characters_return = nullptr) const;
  // TODO(http://crbug.com/373485796): deprecate and remove.
  V8_DEPRECATE_SOON("Use WriteUtf8(..) instead.")
  size_t WriteUtf8V2(Isolate* isolate, char* buffer, size_t capacity,
                     int flags = WriteFlags::kNone,
                     size_t* processed_characters_return = nullptr) const {
    return WriteUtf8(isolate, buffer, capacity, flags,
                     processed_characters_return);
  }
 
  V8_INLINE static Local<String> Empty(Isolate* isolate);
 
  bool IsExternal() const;
 
  bool IsExternalTwoByte() const;
 
  bool IsExternalOneByte() const;
 
  Local<String> InternalizeString(Isolate* isolate);
 
  bool IsInStringTable(Isolate* isolate) const;
 
  class V8_EXPORT ExternalStringResourceBase {
   public:
    virtual ~ExternalStringResourceBase() = default;
 
    virtual bool IsCacheable() const { return true; }
 
    virtual void Unaccount(Isolate* isolate) {}
 
    virtual size_t EstimateMemoryUsage() const {
      return kDefaultMemoryEstimate;
    }
    static constexpr size_t kDefaultMemoryEstimate = static_cast<size_t>(-1);
 
    class V8_EXPORT SharedMemoryUsageRecorder {
     public:
      virtual void RecordSharedMemoryUsage(const void* location,
                                           size_t size) = 0;
    };
 
    virtual void EstimateSharedMemoryUsage(
        SharedMemoryUsageRecorder* recorder) const {}
 
    // Disallow copying and assigning.
    ExternalStringResourceBase(const ExternalStringResourceBase&) = delete;
    void operator=(const ExternalStringResourceBase&) = delete;
 
   protected:
    ExternalStringResourceBase() = default;
 
    virtual void Dispose() { delete this; }
 
    virtual void Lock() const {}
 
    virtual void Unlock() const {}
 
   private:
    friend class internal::ExternalString;
    friend class internal::ExternalStringResourceWrapper;
    friend class v8::String;
    friend class internal::StringForwardingTable;
    friend class internal::ScopedExternalStringLock;
  };
 
  class V8_EXPORT ExternalStringResource : public ExternalStringResourceBase {
   public:
    ~ExternalStringResource() override = default;
 
    virtual const uint16_t* data() const = 0;
 
    virtual size_t length() const = 0;
 
    const uint16_t* cached_data() const {
      CheckCachedDataInvariants();
      return cached_data_;
    }
 
    void UpdateDataCache();
 
   protected:
    ExternalStringResource() = default;
 
   private:
    void CheckCachedDataInvariants() const;
 
    const uint16_t* cached_data_ = nullptr;
  };
 
  class V8_EXPORT ExternalOneByteStringResource
      : public ExternalStringResourceBase {
   public:
    ~ExternalOneByteStringResource() override = default;
 
    virtual const char* data() const = 0;
 
    virtual size_t length() const = 0;
 
    const char* cached_data() const {
      CheckCachedDataInvariants();
      return cached_data_;
    }
 
    void UpdateDataCache();
 
   protected:
    ExternalOneByteStringResource() = default;
 
   private:
    void CheckCachedDataInvariants() const;
 
    const char* cached_data_ = nullptr;
  };
 
  V8_INLINE ExternalStringResourceBase* GetExternalStringResourceBase(
      v8::Isolate* isolate, Encoding* encoding_out) const;
  V8_INLINE ExternalStringResourceBase* GetExternalStringResourceBase(
      Encoding* encoding_out) const;
 
  // TODO(pthier): Change return type to const ExternalStringResource*.
  V8_INLINE ExternalStringResource* GetExternalStringResource() const;
 
  V8_INLINE const ExternalOneByteStringResource*
  GetExternalOneByteStringResource() const;
 
  V8_INLINE static String* Cast(v8::Data* data) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(data);
#endif
    return static_cast<String*>(data);
  }
 
  template <int N>
  static V8_WARN_UNUSED_RESULT Local<String> NewFromUtf8Literal(
      Isolate* isolate, const char (&literal)[N],
      NewStringType type = NewStringType::kNormal) {
    static_assert(N <= kMaxLength, "String is too long");
    return NewFromUtf8Literal(isolate, literal, type, N - 1);
  }
 
  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromUtf8(
      Isolate* isolate, const char* data,
      NewStringType type = NewStringType::kNormal, int length = -1);
 
  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromOneByte(
      Isolate* isolate, const uint8_t* data,
      NewStringType type = NewStringType::kNormal, int length = -1);
 
  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromTwoByte(
      Isolate* isolate, const uint16_t* data,
      NewStringType type = NewStringType::kNormal, int length = -1);
 
  static Local<String> Concat(Isolate* isolate, Local<String> left,
                              Local<String> right);
 
  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewExternalTwoByte(
      Isolate* isolate, ExternalStringResource* resource);
 
  V8_DEPRECATE_SOON("Use the version with the isolate argument instead.")
  bool MakeExternal(ExternalStringResource* resource);
 
  bool MakeExternal(Isolate* isolate, ExternalStringResource* resource);
 
  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewExternalOneByte(
      Isolate* isolate, ExternalOneByteStringResource* resource);
 
  V8_DEPRECATE_SOON("Use the version with the isolate argument instead.")
  bool MakeExternal(ExternalOneByteStringResource* resource);
 
  bool MakeExternal(Isolate* isolate, ExternalOneByteStringResource* resource);
 
  bool CanMakeExternal(Encoding encoding) const;
 
  bool StringEquals(Local<String> str) const;
 
  class V8_EXPORT Utf8Value {
   public:
    Utf8Value(Isolate* isolate, Local<v8::Value> obj);
    ~Utf8Value();
    char* operator*() { return str_; }
    const char* operator*() const { return str_; }
    size_t length() const { return length_; }
    std::string_view as_view() const { return std::string_view(str_, length_); }
 
    // Disallow copying and assigning.
    Utf8Value(const Utf8Value&) = delete;
    void operator=(const Utf8Value&) = delete;
 
   private:
    char* str_;
    size_t length_;
  };
 
  class V8_DEPRECATED(
      "Prefer using String::ValueView if you can, or string->Write to a "
      "buffer if you cannot.") V8_EXPORT Value {
   public:
    V8_DEPRECATED(
        "Prefer using String::ValueView if you can, or string->Write to a "
        "buffer if you cannot.")
    Value(Isolate* isolate, Local<v8::Value> obj);
    ~Value();
    uint16_t* operator*() { return str_; }
    const uint16_t* operator*() const { return str_; }
    uint32_t length() const { return length_; }
 
    // Disallow copying and assigning.
    Value(const Value&) = delete;
    void operator=(const Value&) = delete;
 
   private:
    uint16_t* str_;
    uint32_t length_;
  };
 
  class V8_EXPORT ValueView {
   public:
    ValueView(Isolate* isolate, Local<v8::String> str);
    ~ValueView();
    const uint8_t* data8() const {
#if V8_ENABLE_CHECKS
      CheckOneByte(true);
#endif
      return data8_;
    }
    const uint16_t* data16() const {
#if V8_ENABLE_CHECKS
      CheckOneByte(false);
#endif
      return data16_;
    }
    uint32_t length() const { return length_; }
    bool is_one_byte() const { return is_one_byte_; }
 
    // Disallow copying and assigning.
    ValueView(const ValueView&) = delete;
    void operator=(const ValueView&) = delete;
 
   private:
    void CheckOneByte(bool is_one_byte) const;
 
    Local<v8::String> flat_str_;
    union {
      const uint8_t* data8_;
      const uint16_t* data16_;
    };
    uint32_t length_;
    bool is_one_byte_;
    // Avoid exposing the internal DisallowGarbageCollection scope.
    alignas(internal::Internals::
                kDisallowGarbageCollectionAlign) char no_gc_debug_scope_
        [internal::Internals::kDisallowGarbageCollectionSize];
  };
 
 private:
  void VerifyExternalStringResourceBase(const ExternalStringResourceBase* v,
                                        Encoding encoding) const;
  // Reads the resource of the external string at {obj}. Generally returns a
  // resource unless corruption results in sandbox violations.
  V8_INLINE static ExternalStringResourceBase* ReadExternalStringResource(
      v8::Isolate* isolate, internal::Address obj);
  ExternalStringResource* GetExternalStringResourceSlow() const;
  const ExternalOneByteStringResource* GetExternalOneByteStringResourceSlow()
      const;
  ExternalStringResourceBase* GetExternalStringResourceBaseSlow(
      String::Encoding* encoding_out) const;
 
  static Local<v8::String> NewFromUtf8Literal(Isolate* isolate,
                                              const char* literal,
                                              NewStringType type, int length);
 
  static void CheckCast(v8::Data* that);
};
 
// Zero-length string specialization (templated string size includes
// terminator).
template <>
inline V8_WARN_UNUSED_RESULT Local<String> String::NewFromUtf8Literal(
    Isolate* isolate, const char (&literal)[1], NewStringType type) {
  return String::Empty(isolate);
}
 
class V8_EXPORT ExternalResourceVisitor {
 public:
  virtual ~ExternalResourceVisitor() = default;
  virtual void VisitExternalString(Local<String> string) {}
};
 
class V8_EXPORT Symbol : public Name {
 public:
  Local<Value> Description(Isolate* isolate) const;
 
  static Local<Symbol> New(Isolate* isolate,
                           Local<String> description = Local<String>());
 
  static Local<Symbol> For(Isolate* isolate, Local<String> description);
 
  static Local<Symbol> ForApi(Isolate* isolate, Local<String> description);
 
  // Well-known symbols
  static Local<Symbol> GetAsyncIterator(Isolate* isolate);
  static Local<Symbol> GetHasInstance(Isolate* isolate);
  static Local<Symbol> GetIsConcatSpreadable(Isolate* isolate);
  static Local<Symbol> GetIterator(Isolate* isolate);
  static Local<Symbol> GetMatch(Isolate* isolate);
  static Local<Symbol> GetReplace(Isolate* isolate);
  static Local<Symbol> GetSearch(Isolate* isolate);
  static Local<Symbol> GetSplit(Isolate* isolate);
  static Local<Symbol> GetToPrimitive(Isolate* isolate);
  static Local<Symbol> GetToStringTag(Isolate* isolate);
  static Local<Symbol> GetUnscopables(Isolate* isolate);
  static Local<Symbol> GetDispose(Isolate* isolate);
  static Local<Symbol> GetAsyncDispose(Isolate* isolate);
 
  V8_INLINE static Symbol* Cast(Data* data) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(data);
#endif
    return static_cast<Symbol*>(data);
  }
 
 private:
  Symbol();
  static void CheckCast(Data* that);
};
 
class V8_EXPORT Numeric : public Primitive {
 private:
  Numeric();
  static void CheckCast(v8::Data* that);
};
 
class V8_EXPORT Number : public Numeric {
 public:
  double Value() const;
  static Local<Number> New(Isolate* isolate, double value);
  template <typename Int>
    requires(std::is_integral<Int>::value && !std::is_same<Int, bool>::value &&
             std::is_signed_v<Int> && sizeof(Int) <= sizeof(int32_t))
  V8_INLINE static Local<Number> New(Isolate* isolate, Int value) {
    return NewFromInt32(isolate, value);
  }
  template <typename UInt>
    requires(std::is_integral<UInt>::value &&
             !std::is_same<UInt, bool>::value && std::is_unsigned_v<UInt> &&
             sizeof(UInt) <= sizeof(uint32_t))
  V8_INLINE static Local<Number> New(Isolate* isolate, UInt value) {
    return NewFromUint32(isolate, value);
  }
  V8_INLINE static Number* Cast(v8::Data* data) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(data);
#endif
    return static_cast<Number*>(data);
  }
 
 private:
  Number();
  static Local<Number> NewFromInt32(Isolate* isolate, int32_t value);
  static Local<Number> NewFromUint32(Isolate* isolate, uint32_t value);
  static void CheckCast(v8::Data* that);
};
 
class V8_EXPORT Integer : public Number {
 public:
  static Local<Integer> New(Isolate* isolate, int32_t value);
  static Local<Integer> NewFromUnsigned(Isolate* isolate, uint32_t value);
  int64_t Value() const;
  V8_INLINE static Integer* Cast(v8::Data* data) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(data);
#endif
    return static_cast<Integer*>(data);
  }
 
 private:
  Integer();
  static void CheckCast(v8::Data* that);
};
 
class V8_EXPORT Int32 : public Integer {
 public:
  int32_t Value() const;
  V8_INLINE static Int32* Cast(v8::Data* data) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(data);
#endif
    return static_cast<Int32*>(data);
  }
 
 private:
  Int32();
  static void CheckCast(v8::Data* that);
};
 
class V8_EXPORT Uint32 : public Integer {
 public:
  uint32_t Value() const;
  V8_INLINE static Uint32* Cast(v8::Data* data) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(data);
#endif
    return static_cast<Uint32*>(data);
  }
 
 private:
  Uint32();
  static void CheckCast(v8::Data* that);
};
 
class V8_EXPORT BigInt : public Numeric {
 public:
  static Local<BigInt> New(Isolate* isolate, int64_t value);
  static Local<BigInt> NewFromUnsigned(Isolate* isolate, uint64_t value);
  static MaybeLocal<BigInt> NewFromWords(Local<Context> context, int sign_bit,
                                         int word_count, const uint64_t* words);
 
  uint64_t Uint64Value(bool* lossless = nullptr) const;
 
  int64_t Int64Value(bool* lossless = nullptr) const;
 
  int WordCount() const;
 
  void ToWordsArray(int* sign_bit, int* word_count, uint64_t* words) const;
 
  V8_INLINE static BigInt* Cast(v8::Data* data) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(data);
#endif
    return static_cast<BigInt*>(data);
  }
 
 private:
  BigInt();
  static void CheckCast(v8::Data* that);
};
 
Local<String> String::Empty(Isolate* isolate) {
  using S = internal::Address;
  using I = internal::Internals;
  I::CheckInitialized(isolate);
  S* slot = I::GetRootSlot(isolate, I::kEmptyStringRootIndex);
  return Local<String>::FromSlot(slot);
}
 
// static
String::ExternalStringResourceBase* String::ReadExternalStringResource(
    v8::Isolate* isolate, internal::Address obj) {
  using A = internal::Address;
  using I = internal::Internals;
  // The resource field references a cppgc wrapper object (through the
  // CppHeapPointerTable when pointer compression is enabled), which in turn
  // holds the resource. The wrapper is nullptr if the type check fails.
  A wrapper = reinterpret_cast<A>(internal::ReadCppHeapPointerField<void>(
      isolate, obj, I::kStringResourceOffset,
      CppHeapPointerTag::kExternalStringResourceTag));
  if (wrapper == internal::kNullAddress) return nullptr;
  return *reinterpret_cast<ExternalStringResourceBase* const*>(
      wrapper + I::kExternalStringResourceWrapperResourceOffset);
}
 
String::ExternalStringResource* String::GetExternalStringResource() const {
  using A = internal::Address;
  using I = internal::Internals;
  A obj = internal::ValueHelper::ValueAsAddress(this);
 
  ExternalStringResource* result;
  if (I::IsExternalTwoByteString(I::GetInstanceType(obj))) {
    Isolate* isolate = I::GetCurrentIsolate();
    result = static_cast<ExternalStringResource*>(
        ReadExternalStringResource(isolate, obj));
  } else {
    result = GetExternalStringResourceSlow();
  }
#ifdef V8_ENABLE_CHECKS
  VerifyExternalStringResourceBase(result, Encoding::TWO_BYTE_ENCODING);
#endif
  return result;
}
 
const String::ExternalOneByteStringResource*
String::GetExternalOneByteStringResource() const {
  using A = internal::Address;
  using I = internal::Internals;
  A obj = internal::ValueHelper::ValueAsAddress(this);
  const ExternalOneByteStringResource* result;
  if (I::IsExternalOneByteString(I::GetInstanceType(obj))) {
    Isolate* isolate = I::GetCurrentIsolate();
    result = static_cast<const ExternalOneByteStringResource*>(
        ReadExternalStringResource(isolate, obj));
  } else {
    result = GetExternalOneByteStringResourceSlow();
  }
#ifdef V8_ENABLE_CHECKS
  VerifyExternalStringResourceBase(result, Encoding::ONE_BYTE_ENCODING);
#endif
  return result;
}
 
String::ExternalStringResourceBase* String::GetExternalStringResourceBase(
    v8::Isolate* isolate, String::Encoding* encoding_out) const {
  using A = internal::Address;
  using I = internal::Internals;
  A obj = internal::ValueHelper::ValueAsAddress(this);
  int type = I::GetInstanceType(obj) & I::kStringRepresentationAndEncodingMask;
  *encoding_out = static_cast<Encoding>(type & I::kStringEncodingMask);
  ExternalStringResourceBase* resource;
  if (type == I::kExternalOneByteRepresentationTag ||
      type == I::kExternalTwoByteRepresentationTag) {
    resource = ReadExternalStringResource(isolate, obj);
  } else {
    resource = GetExternalStringResourceBaseSlow(encoding_out);
  }
#ifdef V8_ENABLE_CHECKS
  VerifyExternalStringResourceBase(resource, *encoding_out);
#endif
  return resource;
}
 
String::ExternalStringResourceBase* String::GetExternalStringResourceBase(
    String::Encoding* encoding_out) const {
  Isolate* isolate = internal::Internals::GetCurrentIsolate();
  return GetExternalStringResourceBase(isolate, encoding_out);
}
 
// --- Statics ---
 
V8_INLINE Local<Primitive> Undefined(Isolate* isolate) {
  using S = internal::Address;
  using I = internal::Internals;
  I::CheckInitialized(isolate);
  S* slot = I::GetRootSlot(isolate, I::kUndefinedValueRootIndex);
  return Local<Primitive>::FromSlot(slot);
}
 
V8_INLINE Local<Primitive> Null(Isolate* isolate) {
  using S = internal::Address;
  using I = internal::Internals;
  I::CheckInitialized(isolate);
  S* slot = I::GetRootSlot(isolate, I::kNullValueRootIndex);
  return Local<Primitive>::FromSlot(slot);
}
 
V8_INLINE Local<Boolean> True(Isolate* isolate) {
  using S = internal::Address;
  using I = internal::Internals;
  I::CheckInitialized(isolate);
  S* slot = I::GetRootSlot(isolate, I::kTrueValueRootIndex);
  return Local<Boolean>::FromSlot(slot);
}
 
V8_INLINE Local<Boolean> False(Isolate* isolate) {
  using S = internal::Address;
  using I = internal::Internals;
  I::CheckInitialized(isolate);
  S* slot = I::GetRootSlot(isolate, I::kFalseValueRootIndex);
  return Local<Boolean>::FromSlot(slot);
}
 
Local<Boolean> Boolean::New(Isolate* isolate, bool value) {
  return value ? True(isolate) : False(isolate);
}
 
}  // namespace v8
 
#endif  // INCLUDE_V8_PRIMITIVE_H_