File Explorer

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 be3// 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 internal25 26/**27 * The superclass of primitive values.  See ECMA-262 4.3.2.28 */29class V8_EXPORT Primitive : public Value {};30 31/**32 * A primitive boolean value (ECMA-262, 4.3.14).  Either the true33 * or false value.34 */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_CHECKS40    CheckCast(data);41#endif42    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 51/**52 * An array to hold Primitive values. This is used by the embedder to53 * pass host defined options to the ScriptOptions during compilation.54 *55 * This is passed back to the embedder as part of56 * HostImportModuleDynamicallyCallback for module loading.57 */58class V8_EXPORT PrimitiveArray : public Data {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 65  V8_INLINE static PrimitiveArray* Cast(Data* data) {66#ifdef V8_ENABLE_CHECKS67    CheckCast(data);68#endif69    return reinterpret_cast<PrimitiveArray*>(data);70  }71 72 private:73  static void CheckCast(Data* obj);74};75 76/**77 * A superclass for symbols and strings.78 */79class V8_EXPORT Name : public Primitive {80 public:81  /**82   * Returns the identity hash for this object. The current implementation83   * uses an inline property on the object to store the identity hash.84   *85   * The return value will never be 0. Also, it is not guaranteed to be86   * unique.87   */88  int GetIdentityHash();89 90  V8_INLINE static Name* Cast(Data* data) {91#ifdef V8_ENABLE_CHECKS92    CheckCast(data);93#endif94    return static_cast<Name*>(data);95  }96 97 private:98  static void CheckCast(Data* that);99};100 101/**102 * A flag describing different modes of string creation.103 *104 * Aside from performance implications there are no differences between the two105 * creation modes.106 */107enum class NewStringType {108  /**109   * Create a new string, always allocating new storage memory.110   */111  kNormal,112 113  /**114   * Acts as a hint that the string should be created in the115   * old generation heap space and be deduplicated if an identical string116   * already exists.117   */118  kInternalized119};120 121/**122 * A JavaScript string value (ECMA-262, 4.3.17).123 */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 = 0x8133  };134  /**135   * Returns the number of characters (UTF-16 code units) in this string.136   */137  int Length() const;138 139  /**140   * Returns the number of bytes in the UTF-8 encoded141   * representation of this string.142   */143  V8_DEPRECATED("Use Utf8LengthV2 instead.")144  int Utf8Length(Isolate* isolate) const;145 146  /**147   * Returns the number of bytes needed for the Utf8 encoding of this string.148   */149  size_t Utf8LengthV2(Isolate* isolate) const;150 151  /**152   * Returns whether this string is known to contain only one byte data,153   * i.e. ISO-8859-1 code points.154   * Does not read the string.155   * False negatives are possible.156   */157  bool IsOneByte() const;158 159  /**160   * Returns whether this string contain only one byte data,161   * i.e. ISO-8859-1 code points.162   * Will read the entire string in some cases.163   */164  bool ContainsOnlyOneByte() const;165 166  /**167   * Write the contents of the string to an external buffer.168   * If no arguments are given, expects the buffer to be large169   * enough to hold the entire string and NULL terminator. Copies170   * the contents of the string and the NULL terminator into the171   * buffer.172   *173   * WriteUtf8 will not write partial UTF-8 sequences, preferring to stop174   * before the end of the buffer.175   *176   * Copies up to length characters into the output buffer.177   * Only null-terminates if there is enough space in the buffer.178   *179   * \param buffer The buffer into which the string will be copied.180   * \param start The starting position within the string at which181   * copying begins.182   * \param length The number of characters to copy from the string.  For183   *    WriteUtf8 the number of bytes in the buffer.184   * \param nchars_ref The number of characters written, can be NULL.185   * \param options Various options that might affect performance of this or186   *    subsequent operations.187   * \return The number of characters copied to the buffer excluding the null188   *    terminator.  For WriteUtf8: The number of bytes copied to the buffer189   *    including the null terminator (if written).190   */191  enum WriteOptions {192    NO_OPTIONS = 0,193    HINT_MANY_WRITES_EXPECTED = 1,194    NO_NULL_TERMINATION = 2,195    PRESERVE_ONE_BYTE_NULL = 4,196    // Used by WriteUtf8 to replace orphan surrogate code units with the197    // unicode replacement character. Needs to be set to guarantee valid UTF-8198    // output.199    REPLACE_INVALID_UTF8 = 8200  };201 202  // 16-bit character codes.203  V8_DEPRECATED("Use WriteV2 instead.")204  int Write(Isolate* isolate, uint16_t* buffer, int start = 0, int length = -1,205            int options = NO_OPTIONS) const;206  // One byte characters.207  V8_DEPRECATED("Use WriteOneByteV2 instead.")208  int WriteOneByte(Isolate* isolate, uint8_t* buffer, int start = 0,209                   int length = -1, int options = NO_OPTIONS) const;210  // UTF-8 encoded characters.211  V8_DEPRECATED("Use WriteUtf8V2 instead.")212  int WriteUtf8(Isolate* isolate, char* buffer, int length = -1,213                int* nchars_ref = nullptr, int options = NO_OPTIONS) const;214 215  struct WriteFlags {216    enum {217      kNone = 0,218      // Indicates that the output string should be null-terminated. In that219      // case, the output buffer must include sufficient space for the220      // additional null character.221      kNullTerminate = 1,222      // Used by WriteUtf8 to replace orphan surrogate code units with the223      // unicode replacement character. Needs to be set to guarantee valid UTF-8224      // output.225      kReplaceInvalidUtf8 = 2226    };227  };228 229  /**230   * Write the contents of the string to an external buffer.231   *232   * Copies length characters into the output buffer starting at offset. The233   * output buffer must have sufficient space for all characters and the null234   * terminator if null termination is requested through the flags.235   *236   * \param offset The position within the string at which copying begins.237   * \param length The number of characters to copy from the string.238   * \param buffer The buffer into which the string will be copied.239   * \param flags Various flags that influence the behavior of this operation.240   */241  void WriteV2(Isolate* isolate, uint32_t offset, uint32_t length,242               uint16_t* buffer, int flags = WriteFlags::kNone) const;243  void WriteOneByteV2(Isolate* isolate, uint32_t offset, uint32_t length,244                      uint8_t* buffer, int flags = WriteFlags::kNone) const;245 246  /**247   * Encode the contents of the string as Utf8 into an external buffer.248   *249   * Encodes the characters of this string as Utf8 and writes them into the250   * output buffer until either all characters were encoded or the buffer is251   * full. Will not write partial UTF-8 sequences, preferring to stop before252   * the end of the buffer. If null termination is requested, the output buffer253   * will always be null terminated even if not all characters fit. In that254   * case, the capacity must be at least one. The required size of the output255   * buffer can be determined using Utf8Length().256   *257   * \param buffer The buffer into which the string will be written.258   * \param capacity The number of bytes available in the output buffer.259   * \param flags Various flags that influence the behavior of this operation.260   * \param processed_characters_return The number of processed characters from261   * the buffer.262   * \return The number of bytes copied to the buffer including the null263   * terminator (if written).264   */265  size_t WriteUtf8V2(Isolate* isolate, char* buffer, size_t capacity,266                     int flags = WriteFlags::kNone,267                     size_t* processed_characters_return = nullptr) const;268 269  /**270   * A zero length string.271   */272  V8_INLINE static Local<String> Empty(Isolate* isolate);273 274  /**275   * Returns true if the string is external.276   */277  bool IsExternal() const;278 279  /**280   * Returns true if the string is both external and two-byte.281   */282  bool IsExternalTwoByte() const;283 284  /**285   * Returns true if the string is both external and one-byte.286   */287  bool IsExternalOneByte() const;288 289  /**290   * Returns the internalized string. See `NewStringType::kInternalized` for291   * details on internalized strings.292   */293  Local<String> InternalizeString(Isolate* isolate);294 295  class V8_EXPORT ExternalStringResourceBase {296   public:297    virtual ~ExternalStringResourceBase() = default;298 299    /**300     * If a string is cacheable, the value returned by301     * ExternalStringResource::data() may be cached, otherwise it is not302     * expected to be stable beyond the current top-level task.303     */304    virtual bool IsCacheable() const { return true; }305 306    /**307     * Internally V8 will call this Unaccount method when the external string308     * resource should be unaccounted for. This method can be overridden in309     * subclasses to control how allocated external bytes are accounted.310     */311    virtual void Unaccount(Isolate* isolate) {}312 313    /**314     * Returns an estimate of the memory occupied by this external string, to be315     * used by V8 when producing a heap snapshot. If this function returns316     * kDefaultMemoryEstimate, then V8 will estimate the external size based on317     * the string length. This function should return only memory that is318     * uniquely owned by this resource. If the resource has shared ownership of319     * a secondary allocation, it can report that memory by implementing320     * EstimateSharedMemoryUsage.321     */322    virtual size_t EstimateMemoryUsage() const {323      return kDefaultMemoryEstimate;324    }325    static constexpr size_t kDefaultMemoryEstimate = static_cast<size_t>(-1);326 327    class V8_EXPORT SharedMemoryUsageRecorder {328     public:329      /**330       * Record that a shared allocation at the given location has the given331       * size.332       */333      virtual void RecordSharedMemoryUsage(const void* location,334                                           size_t size) = 0;335    };336 337    /**338     * Estimates memory that this string resource may share with other string339     * resources, to be used by V8 when producing a heap snapshot.340     */341    virtual void EstimateSharedMemoryUsage(342        SharedMemoryUsageRecorder* recorder) const {}343 344    // Disallow copying and assigning.345    ExternalStringResourceBase(const ExternalStringResourceBase&) = delete;346    void operator=(const ExternalStringResourceBase&) = delete;347 348   protected:349    ExternalStringResourceBase() = default;350 351    /**352     * Internally V8 will call this Dispose method when the external string353     * resource is no longer needed. The default implementation will use the354     * delete operator. This method can be overridden in subclasses to355     * control how allocated external string resources are disposed.356     */357    virtual void Dispose() { delete this; }358 359    /**360     * For a non-cacheable string, the value returned by361     * |ExternalStringResource::data()| has to be stable between |Lock()| and362     * |Unlock()|, that is the string must behave as is |IsCacheable()| returned363     * true.364     *365     * These two functions must be thread-safe, and can be called from anywhere.366     * They also must handle lock depth, in the sense that each can be called367     * several times, from different threads, and unlocking should only happen368     * when the balance of Lock() and Unlock() calls is 0.369     */370    virtual void Lock() const {}371 372    /**373     * Unlocks the string.374     */375    virtual void Unlock() const {}376 377   private:378    friend class internal::ExternalString;379    friend class v8::String;380    friend class internal::StringForwardingTable;381    friend class internal::ScopedExternalStringLock;382  };383 384  /**385   * An ExternalStringResource is a wrapper around a two-byte string386   * buffer that resides outside V8's heap. Implement an387   * ExternalStringResource to manage the life cycle of the underlying388   * buffer.  Note that the string data must be immutable.389   */390  class V8_EXPORT ExternalStringResource : public ExternalStringResourceBase {391   public:392    /**393     * Override the destructor to manage the life cycle of the underlying394     * buffer.395     */396    ~ExternalStringResource() override = default;397 398    /**399     * The string data from the underlying buffer. If the resource is cacheable400     * then data() must return the same value for all invocations.401     */402    virtual const uint16_t* data() const = 0;403 404    /**405     * The length of the string. That is, the number of two-byte characters.406     */407    virtual size_t length() const = 0;408 409    /**410     * Returns the cached data from the underlying buffer. This method can be411     * called only for cacheable resources (i.e. IsCacheable() == true) and only412     * after UpdateDataCache() was called.413     */414    const uint16_t* cached_data() const {415      CheckCachedDataInvariants();416      return cached_data_;417    }418 419    /**420     * Update {cached_data_} with the data from the underlying buffer. This can421     * be called only for cacheable resources.422     */423    void UpdateDataCache();424 425   protected:426    ExternalStringResource() = default;427 428   private:429    void CheckCachedDataInvariants() const;430 431    const uint16_t* cached_data_ = nullptr;432  };433 434  /**435   * An ExternalOneByteStringResource is a wrapper around an one-byte436   * string buffer that resides outside V8's heap. Implement an437   * ExternalOneByteStringResource to manage the life cycle of the438   * underlying buffer.  Note that the string data must be immutable439   * and that the data must be Latin-1 and not UTF-8, which would require440   * special treatment internally in the engine and do not allow efficient441   * indexing.  Use String::New or convert to 16 bit data for non-Latin1.442   */443 444  class V8_EXPORT ExternalOneByteStringResource445      : public ExternalStringResourceBase {446   public:447    /**448     * Override the destructor to manage the life cycle of the underlying449     * buffer.450     */451    ~ExternalOneByteStringResource() override = default;452 453    /**454     * The string data from the underlying buffer. If the resource is cacheable455     * then data() must return the same value for all invocations.456     */457    virtual const char* data() const = 0;458 459    /** The number of Latin-1 characters in the string.*/460    virtual size_t length() const = 0;461 462    /**463     * Returns the cached data from the underlying buffer. If the resource is464     * uncacheable or if UpdateDataCache() was not called before, it has465     * undefined behaviour.466     */467    const char* cached_data() const {468      CheckCachedDataInvariants();469      return cached_data_;470    }471 472    /**473     * Update {cached_data_} with the data from the underlying buffer. This can474     * be called only for cacheable resources.475     */476    void UpdateDataCache();477 478   protected:479    ExternalOneByteStringResource() = default;480 481   private:482    void CheckCachedDataInvariants() const;483 484    const char* cached_data_ = nullptr;485  };486 487  /**488   * If the string is an external string, return the ExternalStringResourceBase489   * regardless of the encoding, otherwise return NULL.  The encoding of the490   * string is returned in encoding_out.491   */492  V8_INLINE ExternalStringResourceBase* GetExternalStringResourceBase(493      v8::Isolate* isolate, Encoding* encoding_out) const;494  V8_INLINE ExternalStringResourceBase* GetExternalStringResourceBase(495      Encoding* encoding_out) const;496 497  /**498   * Get the ExternalStringResource for an external string.  Returns499   * NULL if IsExternal() doesn't return true.500   */501  V8_INLINE ExternalStringResource* GetExternalStringResource() const;502 503  /**504   * Get the ExternalOneByteStringResource for an external one-byte string.505   * Returns NULL if IsExternalOneByte() doesn't return true.506   */507  const ExternalOneByteStringResource* GetExternalOneByteStringResource() const;508 509  V8_INLINE static String* Cast(v8::Data* data) {510#ifdef V8_ENABLE_CHECKS511    CheckCast(data);512#endif513    return static_cast<String*>(data);514  }515 516  /**517   * Allocates a new string from a UTF-8 literal. This is equivalent to calling518   * String::NewFromUtf(isolate, "...").ToLocalChecked(), but without the check519   * overhead.520   *521   * When called on a string literal containing '\0', the inferred length is the522   * length of the input array minus 1 (for the final '\0') and not the value523   * returned by strlen.524   **/525  template <int N>526  static V8_WARN_UNUSED_RESULT Local<String> NewFromUtf8Literal(527      Isolate* isolate, const char (&literal)[N],528      NewStringType type = NewStringType::kNormal) {529    static_assert(N <= kMaxLength, "String is too long");530    return NewFromUtf8Literal(isolate, literal, type, N - 1);531  }532 533  /** Allocates a new string from UTF-8 data. Only returns an empty value when534   * length > kMaxLength. **/535  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromUtf8(536      Isolate* isolate, const char* data,537      NewStringType type = NewStringType::kNormal, int length = -1);538 539  /** Allocates a new string from Latin-1 data.  Only returns an empty value540   * when length > kMaxLength. **/541  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromOneByte(542      Isolate* isolate, const uint8_t* data,543      NewStringType type = NewStringType::kNormal, int length = -1);544 545  /** Allocates a new string from UTF-16 data. Only returns an empty value when546   * length > kMaxLength. **/547  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromTwoByte(548      Isolate* isolate, const uint16_t* data,549      NewStringType type = NewStringType::kNormal, int length = -1);550 551  /**552   * Creates a new string by concatenating the left and the right strings553   * passed in as parameters.554   */555  static Local<String> Concat(Isolate* isolate, Local<String> left,556                              Local<String> right);557 558  /**559   * Creates a new external string using the data defined in the given560   * resource. When the external string is no longer live on V8's heap the561   * resource will be disposed by calling its Dispose method. The caller of562   * this function should not otherwise delete or modify the resource. Neither563   * should the underlying buffer be deallocated or modified except through the564   * destructor of the external string resource.565   */566  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewExternalTwoByte(567      Isolate* isolate, ExternalStringResource* resource);568 569  /**570   * Associate an external string resource with this string by transforming it571   * in place so that existing references to this string in the JavaScript heap572   * will use the external string resource. The external string resource's573   * character contents need to be equivalent to this string.574   * Returns true if the string has been changed to be an external string.575   * The string is not modified if the operation fails. See NewExternal for576   * information on the lifetime of the resource.577   */578  V8_DEPRECATE_SOON("Use the version with the isolate argument instead.")579  bool MakeExternal(ExternalStringResource* resource);580 581  /**582   * Associate an external string resource with this string by transforming it583   * in place so that existing references to this string in the JavaScript heap584   * will use the external string resource. The external string resource's585   * character contents need to be equivalent to this string.586   * Returns true if the string has been changed to be an external string.587   * The string is not modified if the operation fails. See NewExternal for588   * information on the lifetime of the resource.589   */590  bool MakeExternal(Isolate* isolate, ExternalStringResource* resource);591 592  /**593   * Creates a new external string using the one-byte data defined in the given594   * resource. When the external string is no longer live on V8's heap the595   * resource will be disposed by calling its Dispose method. The caller of596   * this function should not otherwise delete or modify the resource. Neither597   * should the underlying buffer be deallocated or modified except through the598   * destructor of the external string resource.599   */600  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewExternalOneByte(601      Isolate* isolate, ExternalOneByteStringResource* resource);602 603  /**604   * Associate an external string resource with this string by transforming it605   * in place so that existing references to this string in the JavaScript heap606   * will use the external string resource. The external string resource's607   * character contents need to be equivalent to this string.608   * Returns true if the string has been changed to be an external string.609   * The string is not modified if the operation fails. See NewExternal for610   * information on the lifetime of the resource.611   */612  V8_DEPRECATE_SOON("Use the version with the isolate argument instead.")613  bool MakeExternal(ExternalOneByteStringResource* resource);614 615  /**616   * Associate an external string resource with this string by transforming it617   * in place so that existing references to this string in the JavaScript heap618   * will use the external string resource. The external string resource's619   * character contents need to be equivalent to this string.620   * Returns true if the string has been changed to be an external string.621   * The string is not modified if the operation fails. See NewExternal for622   * information on the lifetime of the resource.623   */624  bool MakeExternal(Isolate* isolate, ExternalOneByteStringResource* resource);625 626  /**627   * Returns true if this string can be made external, given the encoding for628   * the external string resource.629   */630  bool CanMakeExternal(Encoding encoding) const;631 632  /**633   * Returns true if the strings values are equal. Same as JS ==/===.634   */635  bool StringEquals(Local<String> str) const;636 637  /**638   * Converts an object to a UTF-8-encoded character array.  Useful if639   * you want to print the object.  If conversion to a string fails640   * (e.g. due to an exception in the toString() method of the object)641   * then the length() method returns 0 and the * operator returns642   * NULL.643   *644   * WARNING: This will unconditionally copy the contents of the JavaScript645   * string, and should be avoided in situations where performance is a concern.646   * Consider using WriteUtf8() instead.647   */648  class V8_EXPORT Utf8Value {649   public:650    Utf8Value(Isolate* isolate, Local<v8::Value> obj,651              WriteOptions options = REPLACE_INVALID_UTF8);652    ~Utf8Value();653    char* operator*() { return str_; }654    const char* operator*() const { return str_; }655    size_t length() const { return length_; }656 657    // Disallow copying and assigning.658    Utf8Value(const Utf8Value&) = delete;659    void operator=(const Utf8Value&) = delete;660 661   private:662    char* str_;663    size_t length_;664  };665 666  /**667   * Converts an object to a two-byte (UTF-16-encoded) string.668   *669   * If conversion to a string fails (eg. due to an exception in the toString()670   * method of the object) then the length() method returns 0 and the * operator671   * returns NULL.672   *673   * WARNING: This will unconditionally copy the contents of the JavaScript674   * string, and should be avoided in situations where performance is a concern.675   */676  class V8_EXPORT Value {677   public:678    V8_DEPRECATE_SOON(679        "Prefer using String::ValueView if you can, or string->Write to a "680        "buffer if you cannot.")681    Value(Isolate* isolate, Local<v8::Value> obj);682    ~Value();683    uint16_t* operator*() { return str_; }684    const uint16_t* operator*() const { return str_; }685    uint32_t length() const { return length_; }686 687    // Disallow copying and assigning.688    Value(const Value&) = delete;689    void operator=(const Value&) = delete;690 691   private:692    uint16_t* str_;693    uint32_t length_;694  };695 696  /**697   * Returns a view onto a string's contents.698   *699   * WARNING: This does not copy the string's contents, and will therefore be700   * invalidated if the GC can move the string while the ValueView is alive. It701   * is therefore required that no GC or allocation can happen while there is an702   * active ValueView. This requirement may be relaxed in the future.703   *704   * V8 strings are either encoded as one-byte or two-bytes per character.705   */706  class V8_EXPORT ValueView {707   public:708    ValueView(Isolate* isolate, Local<v8::String> str);709    ~ValueView();710    const uint8_t* data8() const {711#if V8_ENABLE_CHECKS712      CheckOneByte(true);713#endif714      return data8_;715    }716    const uint16_t* data16() const {717#if V8_ENABLE_CHECKS718      CheckOneByte(false);719#endif720      return data16_;721    }722    uint32_t length() const { return length_; }723    bool is_one_byte() const { return is_one_byte_; }724 725    // Disallow copying and assigning.726    ValueView(const ValueView&) = delete;727    void operator=(const ValueView&) = delete;728 729   private:730    void CheckOneByte(bool is_one_byte) const;731 732    Local<v8::String> flat_str_;733    union {734      const uint8_t* data8_;735      const uint16_t* data16_;736    };737    uint32_t length_;738    bool is_one_byte_;739    // Avoid exposing the internal DisallowGarbageCollection scope.740    alignas(internal::Internals::741                kDisallowGarbageCollectionAlign) char no_gc_debug_scope_742        [internal::Internals::kDisallowGarbageCollectionSize];743  };744 745 private:746  void VerifyExternalStringResourceBase(ExternalStringResourceBase* v,747                                        Encoding encoding) const;748  void VerifyExternalStringResource(ExternalStringResource* val) const;749  ExternalStringResource* GetExternalStringResourceSlow() const;750  ExternalStringResourceBase* GetExternalStringResourceBaseSlow(751      String::Encoding* encoding_out) const;752 753  static Local<v8::String> NewFromUtf8Literal(Isolate* isolate,754                                              const char* literal,755                                              NewStringType type, int length);756 757  static void CheckCast(v8::Data* that);758};759 760// Zero-length string specialization (templated string size includes761// terminator).762template <>763inline V8_WARN_UNUSED_RESULT Local<String> String::NewFromUtf8Literal(764    Isolate* isolate, const char (&literal)[1], NewStringType type) {765  return String::Empty(isolate);766}767 768/**769 * Interface for iterating through all external resources in the heap.770 */771class V8_EXPORT ExternalResourceVisitor {772 public:773  virtual ~ExternalResourceVisitor() = default;774  virtual void VisitExternalString(Local<String> string) {}775};776 777/**778 * A JavaScript symbol (ECMA-262 edition 6)779 */780class V8_EXPORT Symbol : public Name {781 public:782  /**783   * Returns the description string of the symbol, or undefined if none.784   */785  Local<Value> Description(Isolate* isolate) const;786 787  /**788   * Create a symbol. If description is not empty, it will be used as the789   * description.790   */791  static Local<Symbol> New(Isolate* isolate,792                           Local<String> description = Local<String>());793 794  /**795   * Access global symbol registry.796   * Note that symbols created this way are never collected, so797   * they should only be used for statically fixed properties.798   * Also, there is only one global name space for the descriptions used as799   * keys.800   * To minimize the potential for clashes, use qualified names as keys.801   */802  static Local<Symbol> For(Isolate* isolate, Local<String> description);803 804  /**805   * Retrieve a global symbol. Similar to |For|, but using a separate806   * registry that is not accessible by (and cannot clash with) JavaScript code.807   */808  static Local<Symbol> ForApi(Isolate* isolate, Local<String> description);809 810  // Well-known symbols811  static Local<Symbol> GetAsyncIterator(Isolate* isolate);812  static Local<Symbol> GetHasInstance(Isolate* isolate);813  static Local<Symbol> GetIsConcatSpreadable(Isolate* isolate);814  static Local<Symbol> GetIterator(Isolate* isolate);815  static Local<Symbol> GetMatch(Isolate* isolate);816  static Local<Symbol> GetReplace(Isolate* isolate);817  static Local<Symbol> GetSearch(Isolate* isolate);818  static Local<Symbol> GetSplit(Isolate* isolate);819  static Local<Symbol> GetToPrimitive(Isolate* isolate);820  static Local<Symbol> GetToStringTag(Isolate* isolate);821  static Local<Symbol> GetUnscopables(Isolate* isolate);822  static Local<Symbol> GetDispose(Isolate* isolate);823  static Local<Symbol> GetAsyncDispose(Isolate* isolate);824 825  V8_INLINE static Symbol* Cast(Data* data) {826#ifdef V8_ENABLE_CHECKS827    CheckCast(data);828#endif829    return static_cast<Symbol*>(data);830  }831 832 private:833  Symbol();834  static void CheckCast(Data* that);835};836 837/**838 * A JavaScript numeric value (either Number or BigInt).839 * https://tc39.es/ecma262/#sec-numeric-types840 */841class V8_EXPORT Numeric : public Primitive {842 private:843  Numeric();844  static void CheckCast(v8::Data* that);845};846 847/**848 * A JavaScript number value (ECMA-262, 4.3.20)849 */850class V8_EXPORT Number : public Numeric {851 public:852  double Value() const;853  static Local<Number> New(Isolate* isolate, double value);854  V8_INLINE static Number* Cast(v8::Data* data) {855#ifdef V8_ENABLE_CHECKS856    CheckCast(data);857#endif858    return static_cast<Number*>(data);859  }860 861 private:862  Number();863  static void CheckCast(v8::Data* that);864};865 866/**867 * A JavaScript value representing a signed integer.868 */869class V8_EXPORT Integer : public Number {870 public:871  static Local<Integer> New(Isolate* isolate, int32_t value);872  static Local<Integer> NewFromUnsigned(Isolate* isolate, uint32_t value);873  int64_t Value() const;874  V8_INLINE static Integer* Cast(v8::Data* data) {875#ifdef V8_ENABLE_CHECKS876    CheckCast(data);877#endif878    return static_cast<Integer*>(data);879  }880 881 private:882  Integer();883  static void CheckCast(v8::Data* that);884};885 886/**887 * A JavaScript value representing a 32-bit signed integer.888 */889class V8_EXPORT Int32 : public Integer {890 public:891  int32_t Value() const;892  V8_INLINE static Int32* Cast(v8::Data* data) {893#ifdef V8_ENABLE_CHECKS894    CheckCast(data);895#endif896    return static_cast<Int32*>(data);897  }898 899 private:900  Int32();901  static void CheckCast(v8::Data* that);902};903 904/**905 * A JavaScript value representing a 32-bit unsigned integer.906 */907class V8_EXPORT Uint32 : public Integer {908 public:909  uint32_t Value() const;910  V8_INLINE static Uint32* Cast(v8::Data* data) {911#ifdef V8_ENABLE_CHECKS912    CheckCast(data);913#endif914    return static_cast<Uint32*>(data);915  }916 917 private:918  Uint32();919  static void CheckCast(v8::Data* that);920};921 922/**923 * A JavaScript BigInt value (https://tc39.github.io/proposal-bigint)924 */925class V8_EXPORT BigInt : public Numeric {926 public:927  static Local<BigInt> New(Isolate* isolate, int64_t value);928  static Local<BigInt> NewFromUnsigned(Isolate* isolate, uint64_t value);929  /**930   * Creates a new BigInt object using a specified sign bit and a931   * specified list of digits/words.932   * The resulting number is calculated as:933   *934   * (-1)^sign_bit * (words[0] * (2^64)^0 + words[1] * (2^64)^1 + ...)935   */936  static MaybeLocal<BigInt> NewFromWords(Local<Context> context, int sign_bit,937                                         int word_count, const uint64_t* words);938 939  /**940   * Returns the value of this BigInt as an unsigned 64-bit integer.941   * If `lossless` is provided, it will reflect whether the return value was942   * truncated or wrapped around. In particular, it is set to `false` if this943   * BigInt is negative.944   */945  uint64_t Uint64Value(bool* lossless = nullptr) const;946 947  /**948   * Returns the value of this BigInt as a signed 64-bit integer.949   * If `lossless` is provided, it will reflect whether this BigInt was950   * truncated or not.951   */952  int64_t Int64Value(bool* lossless = nullptr) const;953 954  /**955   * Returns the number of 64-bit words needed to store the result of956   * ToWordsArray().957   */958  int WordCount() const;959 960  /**961   * Writes the contents of this BigInt to a specified memory location.962   * `sign_bit` must be provided and will be set to 1 if this BigInt is963   * negative.964   * `*word_count` has to be initialized to the length of the `words` array.965   * Upon return, it will be set to the actual number of words that would966   * be needed to store this BigInt (i.e. the return value of `WordCount()`).967   */968  void ToWordsArray(int* sign_bit, int* word_count, uint64_t* words) const;969 970  V8_INLINE static BigInt* Cast(v8::Data* data) {971#ifdef V8_ENABLE_CHECKS972    CheckCast(data);973#endif974    return static_cast<BigInt*>(data);975  }976 977 private:978  BigInt();979  static void CheckCast(v8::Data* that);980};981 982Local<String> String::Empty(Isolate* isolate) {983  using S = internal::Address;984  using I = internal::Internals;985  I::CheckInitialized(isolate);986  S* slot = I::GetRootSlot(isolate, I::kEmptyStringRootIndex);987  return Local<String>::FromSlot(slot);988}989 990String::ExternalStringResource* String::GetExternalStringResource() const {991  using A = internal::Address;992  using I = internal::Internals;993  A obj = internal::ValueHelper::ValueAsAddress(this);994 995  ExternalStringResource* result;996  if (I::IsExternalTwoByteString(I::GetInstanceType(obj))) {997    Isolate* isolate = I::GetIsolateForSandbox(obj);998    A value = I::ReadExternalPointerField<internal::kExternalStringResourceTag>(999        isolate, obj, I::kStringResourceOffset);1000    result = reinterpret_cast<String::ExternalStringResource*>(value);1001  } else {1002    result = GetExternalStringResourceSlow();1003  }1004#ifdef V8_ENABLE_CHECKS1005  VerifyExternalStringResource(result);1006#endif1007  return result;1008}1009 1010String::ExternalStringResourceBase* String::GetExternalStringResourceBase(1011    v8::Isolate* isolate, String::Encoding* encoding_out) const {1012  using A = internal::Address;1013  using I = internal::Internals;1014  A obj = internal::ValueHelper::ValueAsAddress(this);1015  int type = I::GetInstanceType(obj) & I::kStringRepresentationAndEncodingMask;1016  *encoding_out = static_cast<Encoding>(type & I::kStringEncodingMask);1017  ExternalStringResourceBase* resource;1018  if (type == I::kExternalOneByteRepresentationTag ||1019      type == I::kExternalTwoByteRepresentationTag) {1020    A value = I::ReadExternalPointerField<internal::kExternalStringResourceTag>(1021        isolate, obj, I::kStringResourceOffset);1022    resource = reinterpret_cast<ExternalStringResourceBase*>(value);1023  } else {1024    resource = GetExternalStringResourceBaseSlow(encoding_out);1025  }1026#ifdef V8_ENABLE_CHECKS1027  VerifyExternalStringResourceBase(resource, *encoding_out);1028#endif1029  return resource;1030}1031 1032String::ExternalStringResourceBase* String::GetExternalStringResourceBase(1033    String::Encoding* encoding_out) const {1034  using A = internal::Address;1035  using I = internal::Internals;1036  A obj = internal::ValueHelper::ValueAsAddress(this);1037  int type = I::GetInstanceType(obj) & I::kStringRepresentationAndEncodingMask;1038  *encoding_out = static_cast<Encoding>(type & I::kStringEncodingMask);1039  ExternalStringResourceBase* resource;1040  if (type == I::kExternalOneByteRepresentationTag ||1041      type == I::kExternalTwoByteRepresentationTag) {1042    Isolate* isolate = I::GetIsolateForSandbox(obj);1043    A value = I::ReadExternalPointerField<internal::kExternalStringResourceTag>(1044        isolate, obj, I::kStringResourceOffset);1045    resource = reinterpret_cast<ExternalStringResourceBase*>(value);1046  } else {1047    resource = GetExternalStringResourceBaseSlow(encoding_out);1048  }1049#ifdef V8_ENABLE_CHECKS1050  VerifyExternalStringResourceBase(resource, *encoding_out);1051#endif1052  return resource;1053}1054 1055// --- Statics ---1056 1057V8_INLINE Local<Primitive> Undefined(Isolate* isolate) {1058  using S = internal::Address;1059  using I = internal::Internals;1060  I::CheckInitialized(isolate);1061  S* slot = I::GetRootSlot(isolate, I::kUndefinedValueRootIndex);1062  return Local<Primitive>::FromSlot(slot);1063}1064 1065V8_INLINE Local<Primitive> Null(Isolate* isolate) {1066  using S = internal::Address;1067  using I = internal::Internals;1068  I::CheckInitialized(isolate);1069  S* slot = I::GetRootSlot(isolate, I::kNullValueRootIndex);1070  return Local<Primitive>::FromSlot(slot);1071}1072 1073V8_INLINE Local<Boolean> True(Isolate* isolate) {1074  using S = internal::Address;1075  using I = internal::Internals;1076  I::CheckInitialized(isolate);1077  S* slot = I::GetRootSlot(isolate, I::kTrueValueRootIndex);1078  return Local<Boolean>::FromSlot(slot);1079}1080 1081V8_INLINE Local<Boolean> False(Isolate* isolate) {1082  using S = internal::Address;1083  using I = internal::Internals;1084  I::CheckInitialized(isolate);1085  S* slot = I::GetRootSlot(isolate, I::kFalseValueRootIndex);1086  return Local<Boolean>::FromSlot(slot);1087}1088 1089Local<Boolean> Boolean::New(Isolate* isolate, bool value) {1090  return value ? True(isolate) : False(isolate);1091}1092 1093}  // namespace v81094 1095#endif  // INCLUDE_V8_PRIMITIVE_H_1096