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 "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-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 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:
  static constexpr int kMaxLength =
      internal::kApiSystemPointerSize == 4 ? (1 << 28) - 16 : (1 << 29) - 24;
 
  enum Encoding {
    UNKNOWN_ENCODING = 0x1,
    TWO_BYTE_ENCODING = 0x0,
    ONE_BYTE_ENCODING = 0x8
  };

  int Length() const;

  V8_DEPRECATED("Use Utf8LengthV2 instead.")
  int Utf8Length(Isolate* isolate) const;

  size_t Utf8LengthV2(Isolate* isolate) const;

  bool IsOneByte() const;

  bool ContainsOnlyOneByte() const;

  enum WriteOptions {
    NO_OPTIONS = 0,
    HINT_MANY_WRITES_EXPECTED = 1,
    NO_NULL_TERMINATION = 2,
    PRESERVE_ONE_BYTE_NULL = 4,
    // Used by WriteUtf8 to replace orphan surrogate code units with the
    // unicode replacement character. Needs to be set to guarantee valid UTF-8
    // output.
    REPLACE_INVALID_UTF8 = 8
  };
 
  // 16-bit character codes.
  V8_DEPRECATED("Use WriteV2 instead.")
  int Write(Isolate* isolate, uint16_t* buffer, int start = 0, int length = -1,
            int options = NO_OPTIONS) const;
  // One byte characters.
  V8_DEPRECATED("Use WriteOneByteV2 instead.")
  int WriteOneByte(Isolate* isolate, uint8_t* buffer, int start = 0,
                   int length = -1, int options = NO_OPTIONS) const;
  // UTF-8 encoded characters.
  V8_DEPRECATED("Use WriteUtf8V2 instead.")
  int WriteUtf8(Isolate* isolate, char* buffer, int length = -1,
                int* nchars_ref = nullptr, int options = NO_OPTIONS) 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 WriteV2(Isolate* isolate, uint32_t offset, uint32_t length,
               uint16_t* buffer, int flags = WriteFlags::kNone) const;
  void WriteOneByteV2(Isolate* isolate, uint32_t offset, uint32_t length,
                      uint8_t* buffer, int flags = WriteFlags::kNone) const;

  size_t WriteUtf8V2(Isolate* isolate, char* buffer, size_t capacity,
                     int flags = WriteFlags::kNone,
                     size_t* processed_characters_return = nullptr) const;

  V8_INLINE static Local<String> Empty(Isolate* isolate);

  bool IsExternal() const;

  bool IsExternalTwoByte() const;

  bool IsExternalOneByte() const;

  Local<String> InternalizeString(Isolate* isolate);
 
  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 v8::String;
    friend class internal::StringForwardingTable;
    friend class internal::ScopedExternalStringLock;
  };

   * ExternalStringResource to manage the life cycle of the underlying
   * buffer.  Note that the string data must be immutable.
   */
  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;

  V8_INLINE ExternalStringResource* GetExternalStringResource() const;

  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,
              WriteOptions options = REPLACE_INVALID_UTF8);
    ~Utf8Value();
    char* operator*() { return str_; }
    const char* operator*() const { return str_; }
    size_t length() const { return length_; }
 
    // Disallow copying and assigning.
    Utf8Value(const Utf8Value&) = delete;
    void operator=(const Utf8Value&) = delete;
 
   private:
    char* str_;
    size_t length_;
  };

  class V8_EXPORT Value {
   public:
    V8_DEPRECATE_SOON(
        "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(ExternalStringResourceBase* v,
                                        Encoding encoding) const;
  void VerifyExternalStringResource(ExternalStringResource* val) const;
  ExternalStringResource* GetExternalStringResourceSlow() 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);
 
  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);
  V8_INLINE static Number* Cast(v8::Data* data) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(data);
#endif
    return static_cast<Number*>(data);
  }
 
 private:
  Number();
  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);
}
 
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::GetIsolateForSandbox(obj);
    A value = I::ReadExternalPointerField<internal::kExternalStringResourceTag>(
        isolate, obj, I::kStringResourceOffset);
    result = reinterpret_cast<String::ExternalStringResource*>(value);
  } else {
    result = GetExternalStringResourceSlow();
  }
#ifdef V8_ENABLE_CHECKS
  VerifyExternalStringResource(result);
#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) {
    A value = I::ReadExternalPointerField<internal::kExternalStringResourceTag>(
        isolate, obj, I::kStringResourceOffset);
    resource = reinterpret_cast<ExternalStringResourceBase*>(value);
  } 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 {
  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) {
    Isolate* isolate = I::GetIsolateForSandbox(obj);
    A value = I::ReadExternalPointerField<internal::kExternalStringResourceTag>(
        isolate, obj, I::kStringResourceOffset);
    resource = reinterpret_cast<ExternalStringResourceBase*>(value);
  } else {
    resource = GetExternalStringResourceBaseSlow(encoding_out);
  }
#ifdef V8_ENABLE_CHECKS
  VerifyExternalStringResourceBase(resource, *encoding_out);
#endif
  return resource;
}
 
// --- 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_