js/public/Array.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /* Array-related operations. */
   7
   8 #ifndef js_Array_h
   9 #define js_Array_h
  10
  11 #include <stddef.h>  // size_t
  12 #include <stdint.h>  // uint32_t
  13
  14 #include "jstypes.h"  // JS_PUBLIC_API
  15
  16 #include "js/RootingAPI.h"  // JS::Handle
  17 #include "js/Value.h"       // JS::Value
  18
  19 struct JS_PUBLIC_API JSContext;
  20 class JS_PUBLIC_API JSObject;
  21
  22 namespace JS {
  23
  24 class HandleValueArray;
  25
  26 /**
  27  * Create an Array from the current realm with the given contents.
  28  */
  29 extern JS_PUBLIC_API JSObject* NewArrayObject(JSContext* cx,
  30                                               const HandleValueArray& contents);
  31
  32 /**
  33  * Create an Array from the current realm with the given length and allocate
  34  * memory for all its elements.  (The elements nonetheless will not exist as
  35  * properties on the returned array until values have been assigned to them.)
  36  */
  37 extern JS_PUBLIC_API JSObject* NewArrayObject(JSContext* cx, size_t length);
  38
  39 /**
  40  * Determine whether |value| is an Array object or a wrapper around one.  (An
  41  * ES6 proxy whose target is an Array object, e.g.
  42  * |var target = [], handler = {}; Proxy.revocable(target, handler).proxy|, is
  43  * not considered to be an Array.)
  44  *
  45  * On success set |*isArray| accordingly and return true; on failure return
  46  * false.
  47  */
  48 extern JS_PUBLIC_API bool IsArrayObject(JSContext* cx, Handle<Value> value,
  49                                         bool* isArray);
  50
  51 /**
  52  * Determine whether |obj| is an Array object or a wrapper around one.  (An
  53  * ES6 proxy whose target is an Array object, e.g.
  54  * |var target = [], handler = {}; Proxy.revocable(target, handler).proxy|, is
  55  * not considered to be an Array.)
  56  *
  57  * On success set |*isArray| accordingly and return true; on failure return
  58  * false.
  59  */
  60 extern JS_PUBLIC_API bool IsArrayObject(JSContext* cx, Handle<JSObject*> obj,
  61                                         bool* isArray);
  62
  63 /**
  64  * Store |*lengthp = ToLength(obj.length)| and return true on success, else
  65  * return false.
  66  *
  67  * |ToLength| converts its input to an integer usable to index an
  68  * array-like object.
  69  *
  70  * If |obj| is an Array, this overall operation is the same as getting
  71  * |obj.length|.
  72  */
  73 extern JS_PUBLIC_API bool GetArrayLength(JSContext* cx, Handle<JSObject*> obj,
  74                                          uint32_t* lengthp);
  75
  76 /**
  77  * Perform |obj.length = length| as if in strict mode code, with a fast path for
  78  * the case where |obj| is an Array.
  79  *
  80  * This operation is exactly and only assigning to a "length" property.  In
  81  * general, it can invoke an existing "length" setter, throw if the property is
  82  * non-writable, or do anything else a property-set operation might do.
  83  */
  84 extern JS_PUBLIC_API bool SetArrayLength(JSContext* cx, Handle<JSObject*> obj,
  85                                          uint32_t length);
  86
  87 /**
  88  * The answer to a successful query as to whether an object is an Array per
  89  * ES6's internal |IsArray| operation (as exposed by |Array.isArray|).
  90  */
  91 enum class IsArrayAnswer { Array, NotArray, RevokedProxy };
  92
  93 /**
  94  * ES6 7.2.2.
  95  *
  96  * Returns false on failure, otherwise returns true and sets |*isArray|
  97  * indicating whether the object passes ECMAScript's IsArray test.  This is the
  98  * same test performed by |Array.isArray|.
  99  *
 100  * This is NOT the same as asking whether |obj| is an Array or a wrapper around
 101  * one.  If |obj| is a proxy created by |Proxy.revocable()| and has been
 102  * revoked, or if |obj| is a proxy whose target (at any number of hops) is a
 103  * revoked proxy, this method throws a TypeError and returns false.
 104  */
 105 extern JS_PUBLIC_API bool IsArray(JSContext* cx, Handle<JSObject*> obj,
 106                                   bool* isArray);
 107
 108 /**
 109  * Identical to IsArray above, but the nature of the object (if successfully
 110  * determined) is communicated via |*answer|.  In particular this method
 111  * returns true and sets |*answer = IsArrayAnswer::RevokedProxy| when called on
 112  * a revoked proxy.
 113  *
 114  * Most users will want the overload above, not this one.
 115  */
 116 extern JS_PUBLIC_API bool IsArray(JSContext* cx, Handle<JSObject*> obj,
 117                                   IsArrayAnswer* answer);
 118
 119 }  // namespace JS
 120
 121 #endif  // js_Array_h