summaryrefslogtreecommitdiffstats
path: root/js/public/Array.h
diff options
context:
space:
mode:
Diffstat (limited to 'js/public/Array.h')
-rw-r--r--js/public/Array.h120
1 files changed, 120 insertions, 0 deletions
diff --git a/js/public/Array.h b/js/public/Array.h
new file mode 100644
index 0000000000..f019090167
--- /dev/null
+++ b/js/public/Array.h
@@ -0,0 +1,120 @@
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+/* Array-related operations. */
+
+#ifndef js_Array_h
+#define js_Array_h
+
+#include <stddef.h> // size_t
+#include <stdint.h> // uint32_t
+
+#include "jstypes.h" // JS_PUBLIC_API
+
+#include "js/TypeDecls.h"
+
+namespace JS {
+
+class HandleValueArray;
+
+/**
+ * Create an Array from the current realm with the given contents.
+ */
+extern JS_PUBLIC_API JSObject* NewArrayObject(JSContext* cx,
+ const HandleValueArray& contents);
+
+/**
+ * Create an Array from the current realm with the given length and allocate
+ * memory for all its elements. (The elements nonetheless will not exist as
+ * properties on the returned array until values have been assigned to them.)
+ */
+extern JS_PUBLIC_API JSObject* NewArrayObject(JSContext* cx, size_t length);
+
+/**
+ * Determine whether |value| is an Array object or a wrapper around one. (An
+ * ES6 proxy whose target is an Array object, e.g.
+ * |var target = [], handler = {}; Proxy.revocable(target, handler).proxy|, is
+ * not considered to be an Array.)
+ *
+ * On success set |*isArray| accordingly and return true; on failure return
+ * false.
+ */
+extern JS_PUBLIC_API bool IsArrayObject(JSContext* cx, Handle<Value> value,
+ bool* isArray);
+
+/**
+ * Determine whether |obj| is an Array object or a wrapper around one. (An
+ * ES6 proxy whose target is an Array object, e.g.
+ * |var target = [], handler = {}; Proxy.revocable(target, handler).proxy|, is
+ * not considered to be an Array.)
+ *
+ * On success set |*isArray| accordingly and return true; on failure return
+ * false.
+ */
+extern JS_PUBLIC_API bool IsArrayObject(JSContext* cx, Handle<JSObject*> obj,
+ bool* isArray);
+
+/**
+ * Store |*lengthp = ToLength(obj.length)| and return true on success, else
+ * return false.
+ *
+ * If the length does not fit in |uint32_t|, an exception is reported and false
+ * is returned.
+ *
+ * |ToLength| converts its input to an integer usable to index an
+ * array-like object.
+ *
+ * If |obj| is an Array, this overall operation is the same as getting
+ * |obj.length|.
+ */
+extern JS_PUBLIC_API bool GetArrayLength(JSContext* cx, Handle<JSObject*> obj,
+ uint32_t* lengthp);
+
+/**
+ * Perform |obj.length = length| as if in strict mode code, with a fast path for
+ * the case where |obj| is an Array.
+ *
+ * This operation is exactly and only assigning to a "length" property. In
+ * general, it can invoke an existing "length" setter, throw if the property is
+ * non-writable, or do anything else a property-set operation might do.
+ */
+extern JS_PUBLIC_API bool SetArrayLength(JSContext* cx, Handle<JSObject*> obj,
+ uint32_t length);
+
+/**
+ * The answer to a successful query as to whether an object is an Array per
+ * ES6's internal |IsArray| operation (as exposed by |Array.isArray|).
+ */
+enum class IsArrayAnswer { Array, NotArray, RevokedProxy };
+
+/**
+ * ES6 7.2.2.
+ *
+ * Returns false on failure, otherwise returns true and sets |*isArray|
+ * indicating whether the object passes ECMAScript's IsArray test. This is the
+ * same test performed by |Array.isArray|.
+ *
+ * This is NOT the same as asking whether |obj| is an Array or a wrapper around
+ * one. If |obj| is a proxy created by |Proxy.revocable()| and has been
+ * revoked, or if |obj| is a proxy whose target (at any number of hops) is a
+ * revoked proxy, this method throws a TypeError and returns false.
+ */
+extern JS_PUBLIC_API bool IsArray(JSContext* cx, Handle<JSObject*> obj,
+ bool* isArray);
+
+/**
+ * Identical to IsArray above, but the nature of the object (if successfully
+ * determined) is communicated via |*answer|. In particular this method
+ * returns true and sets |*answer = IsArrayAnswer::RevokedProxy| when called on
+ * a revoked proxy.
+ *
+ * Most users will want the overload above, not this one.
+ */
+extern JS_PUBLIC_API bool IsArray(JSContext* cx, Handle<JSObject*> obj,
+ IsArrayAnswer* answer);
+
+} // namespace JS
+
+#endif // js_Array_h