include/node/v8-container.h

0001 // Copyright 2021 the V8 project authors. All rights reserved.
0002 // Use of this source code is governed by a BSD-style license that can be
0003 // found in the LICENSE file.
0004
0005 #ifndef INCLUDE_V8_CONTAINER_H_
0006 #define INCLUDE_V8_CONTAINER_H_
0007
0008 #include <stddef.h>
0009 #include <stdint.h>
0010
0011 #include <functional>
0012
0013 #include "v8-local-handle.h"  // NOLINT(build/include_directory)
0014 #include "v8-object.h"        // NOLINT(build/include_directory)
0015 #include "v8config.h"         // NOLINT(build/include_directory)
0016
0017 namespace v8 {
0018
0019 class Context;
0020 class Isolate;
0021
0022 /**
0023  * An instance of the built-in array constructor (ECMA-262, 15.4.2).
0024  */
0025 class V8_EXPORT Array : public Object {
0026  public:
0027   uint32_t Length() const;
0028
0029   /**
0030    * Creates a JavaScript array with the given length. If the length
0031    * is negative the returned array will have length 0.
0032    */
0033   static Local<Array> New(Isolate* isolate, int length = 0);
0034
0035   /**
0036    * Creates a JavaScript array out of a Local<Value> array in C++
0037    * with a known length.
0038    */
0039   static Local<Array> New(Isolate* isolate, Local<Value>* elements,
0040                           size_t length);
0041   V8_INLINE static Array* Cast(Value* value) {
0042 #ifdef V8_ENABLE_CHECKS
0043     CheckCast(value);
0044 #endif
0045     return static_cast<Array*>(value);
0046   }
0047
0048   /**
0049    * Creates a JavaScript array from a provided callback.
0050    *
0051    * \param context The v8::Context to create the array in.
0052    * \param length The length of the array to be created.
0053    * \param next_value_callback The callback that is invoked to retrieve
0054    *     elements for the array. The embedder can signal that the array
0055    *     initialization should be aborted by throwing an exception and returning
0056    *     an empty MaybeLocal.
0057    * \returns The v8::Array if all elements were constructed successfully and an
0058    *     empty MaybeLocal otherwise.
0059    */
0060   static MaybeLocal<Array> New(
0061       Local<Context> context, size_t length,
0062       std::function<MaybeLocal<v8::Value>()> next_value_callback);
0063
0064   enum class CallbackResult {
0065     kException,
0066     kBreak,
0067     kContinue,
0068   };
0069   using IterationCallback = CallbackResult (*)(uint32_t index,
0070                                                Local<Value> element,
0071                                                void* data);
0072
0073   /**
0074    * Calls {callback} for every element of this array, passing {callback_data}
0075    * as its {data} parameter.
0076    * This function will typically be faster than calling {Get()} repeatedly.
0077    * As a consequence of being optimized for low overhead, the provided
0078    * callback must adhere to the following restrictions:
0079    *  - It must not allocate any V8 objects and continue iterating; it may
0080    *    allocate (e.g. an error message/object) and then immediately terminate
0081    *    the iteration.
0082    *  - It must not modify the array being iterated.
0083    *  - It must not call back into V8 (unless it can guarantee that such a
0084    *    call does not violate the above restrictions, which is difficult).
0085    *  - The {Local<Value> element} must not "escape", i.e. must not be assigned
0086    *    to any other {Local}. Creating a {Global} from it, or updating a
0087    *    v8::TypecheckWitness with it, is safe.
0088    * These restrictions may be lifted in the future if use cases arise that
0089    * justify a slower but more robust implementation.
0090    *
0091    * Returns {Nothing} on exception; use a {TryCatch} to catch and handle this
0092    * exception.
0093    * When the {callback} returns {kException}, iteration is terminated
0094    * immediately, returning {Nothing}. By returning {kBreak}, the callback
0095    * can request non-exceptional early termination of the iteration.
0096    */
0097   Maybe<void> Iterate(Local<Context> context, IterationCallback callback,
0098                       void* callback_data);
0099
0100  private:
0101   Array();
0102   static void CheckCast(Value* obj);
0103 };
0104
0105 /**
0106  * An instance of the built-in Map constructor (ECMA-262, 6th Edition, 23.1.1).
0107  */
0108 class V8_EXPORT Map : public Object {
0109  public:
0110   size_t Size() const;
0111   void Clear();
0112   V8_WARN_UNUSED_RESULT MaybeLocal<Value> Get(Local<Context> context,
0113                                               Local<Value> key);
0114   V8_WARN_UNUSED_RESULT MaybeLocal<Map> Set(Local<Context> context,
0115                                             Local<Value> key,
0116                                             Local<Value> value);
0117   V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,
0118                                         Local<Value> key);
0119   V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
0120                                            Local<Value> key);
0121
0122   /**
0123    * Returns an array of length Size() * 2, where index N is the Nth key and
0124    * index N + 1 is the Nth value.
0125    */
0126   Local<Array> AsArray() const;
0127
0128   /**
0129    * Creates a new empty Map.
0130    */
0131   static Local<Map> New(Isolate* isolate);
0132
0133   V8_INLINE static Map* Cast(Value* value) {
0134 #ifdef V8_ENABLE_CHECKS
0135     CheckCast(value);
0136 #endif
0137     return static_cast<Map*>(value);
0138   }
0139
0140  private:
0141   Map();
0142   static void CheckCast(Value* obj);
0143 };
0144
0145 /**
0146  * An instance of the built-in Set constructor (ECMA-262, 6th Edition, 23.2.1).
0147  */
0148 class V8_EXPORT Set : public Object {
0149  public:
0150   size_t Size() const;
0151   void Clear();
0152   V8_WARN_UNUSED_RESULT MaybeLocal<Set> Add(Local<Context> context,
0153                                             Local<Value> key);
0154   V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,
0155                                         Local<Value> key);
0156   V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
0157                                            Local<Value> key);
0158
0159   /**
0160    * Returns an array of the keys in this Set.
0161    */
0162   Local<Array> AsArray() const;
0163
0164   /**
0165    * Creates a new empty Set.
0166    */
0167   static Local<Set> New(Isolate* isolate);
0168
0169   V8_INLINE static Set* Cast(Value* value) {
0170 #ifdef V8_ENABLE_CHECKS
0171     CheckCast(value);
0172 #endif
0173     return static_cast<Set*>(value);
0174   }
0175
0176  private:
0177   Set();
0178   static void CheckCast(Value* obj);
0179 };
0180
0181 }  // namespace v8
0182
0183 #endif  // INCLUDE_V8_CONTAINER_H_