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_CONTAINER_H_6#define INCLUDE_V8_CONTAINER_H_7 8#include <stddef.h>9#include <stdint.h>10 11#include <functional>12 13#include "v8-local-handle.h"  // NOLINT(build/include_directory)14#include "v8-object.h"        // NOLINT(build/include_directory)15#include "v8config.h"         // NOLINT(build/include_directory)16 17namespace v8 {18 19class Context;20class Isolate;21 22/**23 * An instance of the built-in array constructor (ECMA-262, 15.4.2).24 */25class V8_EXPORT Array : public Object {26 public:27  uint32_t Length() const;28 29  /**30   * Creates a JavaScript array with the given length. If the length31   * is negative the returned array will have length 0.32   */33  static Local<Array> New(Isolate* isolate, int length = 0);34 35  /**36   * Creates a JavaScript array out of a Local<Value> array in C++37   * with a known length.38   */39  static Local<Array> New(Isolate* isolate, Local<Value>* elements,40                          size_t length);41  V8_INLINE static Array* Cast(Value* value) {42#ifdef V8_ENABLE_CHECKS43    CheckCast(value);44#endif45    return static_cast<Array*>(value);46  }47 48  /**49   * Creates a JavaScript array from a provided callback.50   *51   * \param context The v8::Context to create the array in.52   * \param length The length of the array to be created.53   * \param next_value_callback The callback that is invoked to retrieve54   *     elements for the array. The embedder can signal that the array55   *     initialization should be aborted by throwing an exception and returning56   *     an empty MaybeLocal.57   * \returns The v8::Array if all elements were constructed successfully and an58   *     empty MaybeLocal otherwise.59   */60  static MaybeLocal<Array> New(61      Local<Context> context, size_t length,62      std::function<MaybeLocal<v8::Value>()> next_value_callback);63 64  enum class CallbackResult {65    kException,66    kBreak,67    kContinue,68  };69  using IterationCallback = CallbackResult (*)(uint32_t index,70                                               Local<Value> element,71                                               void* data);72 73  /**74   * Calls {callback} for every element of this array, passing {callback_data}75   * as its {data} parameter.76   * This function will typically be faster than calling {Get()} repeatedly.77   * As a consequence of being optimized for low overhead, the provided78   * callback must adhere to the following restrictions:79   *  - It must not allocate any V8 objects and continue iterating; it may80   *    allocate (e.g. an error message/object) and then immediately terminate81   *    the iteration.82   *  - It must not modify the array being iterated.83   *  - It must not call back into V8 (unless it can guarantee that such a84   *    call does not violate the above restrictions, which is difficult).85   *  - The {Local<Value> element} must not "escape", i.e. must not be assigned86   *    to any other {Local}. Creating a {Global} from it, or updating a87   *    v8::TypecheckWitness with it, is safe.88   * These restrictions may be lifted in the future if use cases arise that89   * justify a slower but more robust implementation.90   *91   * Returns {Nothing} on exception; use a {TryCatch} to catch and handle this92   * exception.93   * When the {callback} returns {kException}, iteration is terminated94   * immediately, returning {Nothing}. By returning {kBreak}, the callback95   * can request non-exceptional early termination of the iteration.96   */97  Maybe<void> Iterate(Local<Context> context, IterationCallback callback,98                      void* callback_data);99 100 private:101  Array();102  static void CheckCast(Value* obj);103};104 105/**106 * An instance of the built-in Map constructor (ECMA-262, 6th Edition, 23.1.1).107 */108class V8_EXPORT Map : public Object {109 public:110  size_t Size() const;111  void Clear();112  V8_WARN_UNUSED_RESULT MaybeLocal<Value> Get(Local<Context> context,113                                              Local<Value> key);114  V8_WARN_UNUSED_RESULT MaybeLocal<Map> Set(Local<Context> context,115                                            Local<Value> key,116                                            Local<Value> value);117  V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,118                                        Local<Value> key);119  V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,120                                           Local<Value> key);121 122  /**123   * Returns an array of length Size() * 2, where index N is the Nth key and124   * index N + 1 is the Nth value.125   */126  Local<Array> AsArray() const;127 128  /**129   * Creates a new empty Map.130   */131  static Local<Map> New(Isolate* isolate);132 133  V8_INLINE static Map* Cast(Value* value) {134#ifdef V8_ENABLE_CHECKS135    CheckCast(value);136#endif137    return static_cast<Map*>(value);138  }139 140 private:141  Map();142  static void CheckCast(Value* obj);143};144 145/**146 * An instance of the built-in Set constructor (ECMA-262, 6th Edition, 23.2.1).147 */148class V8_EXPORT Set : public Object {149 public:150  size_t Size() const;151  void Clear();152  V8_WARN_UNUSED_RESULT MaybeLocal<Set> Add(Local<Context> context,153                                            Local<Value> key);154  V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,155                                        Local<Value> key);156  V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,157                                           Local<Value> key);158 159  /**160   * Returns an array of the keys in this Set.161   */162  Local<Array> AsArray() const;163 164  /**165   * Creates a new empty Set.166   */167  static Local<Set> New(Isolate* isolate);168 169  V8_INLINE static Set* Cast(Value* value) {170#ifdef V8_ENABLE_CHECKS171    CheckCast(value);172#endif173    return static_cast<Set*>(value);174  }175 176 private:177  Set();178  static void CheckCast(Value* obj);179};180 181}  // namespace v8182 183#endif  // INCLUDE_V8_CONTAINER_H_184