V8 API Reference, 7.2.502.16 (for Deno 0.2.4)
js-array.h
1 // Copyright 2017 the V8 project authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef V8_OBJECTS_JS_ARRAY_H_
6 #define V8_OBJECTS_JS_ARRAY_H_
7 
8 #include "src/objects/allocation-site.h"
9 #include "src/objects/fixed-array.h"
10 #include "src/objects/js-objects.h"
11 
12 // Has to be the last include (doesn't have include guards):
13 #include "src/objects/object-macros.h"
14 
15 namespace v8 {
16 namespace internal {
17 
18 // The JSArray describes JavaScript Arrays
19 // Such an array can be in one of two modes:
20 // - fast, backing storage is a FixedArray and length <= elements.length();
21 // Please note: push and pop can be used to grow and shrink the array.
22 // - slow, backing storage is a HashTable with numbers as keys.
23 class JSArray : public JSObject {
24  public:
25  // [length]: The length property.
26  DECL_ACCESSORS(length, Object)
27 
28  // Overload the length setter to skip write barrier when the length
29  // is set to a smi. This matches the set function on FixedArray.
30  inline void set_length(Smi length);
31 
32  static bool HasReadOnlyLength(Handle<JSArray> array);
33  static bool WouldChangeReadOnlyLength(Handle<JSArray> array, uint32_t index);
34 
35  // Initialize the array with the given capacity. The function may
36  // fail due to out-of-memory situations, but only if the requested
37  // capacity is non-zero.
38  static void Initialize(Handle<JSArray> array, int capacity, int length = 0);
39 
40  // If the JSArray has fast elements, and new_length would result in
41  // normalization, returns true.
42  bool SetLengthWouldNormalize(uint32_t new_length);
43  static inline bool SetLengthWouldNormalize(Heap* heap, uint32_t new_length);
44 
45  // Initializes the array to a certain length.
46  inline bool AllowsSetLength();
47 
48  static void SetLength(Handle<JSArray> array, uint32_t length);
49 
50  // Set the content of the array to the content of storage.
51  static inline void SetContent(Handle<JSArray> array,
52  Handle<FixedArrayBase> storage);
53 
54  // ES6 9.4.2.1
55  V8_WARN_UNUSED_RESULT static Maybe<bool> DefineOwnProperty(
56  Isolate* isolate, Handle<JSArray> o, Handle<Object> name,
57  PropertyDescriptor* desc, ShouldThrow should_throw);
58 
59  static bool AnythingToArrayLength(Isolate* isolate,
60  Handle<Object> length_object,
61  uint32_t* output);
62  V8_WARN_UNUSED_RESULT static Maybe<bool> ArraySetLength(
63  Isolate* isolate, Handle<JSArray> a, PropertyDescriptor* desc,
64  ShouldThrow should_throw);
65 
66  // Support for Array.prototype.join().
67  // Writes a fixed array of strings and separators to a single destination
68  // string. This helpers assumes the fixed array encodes separators in two
69  // ways:
70  // 1) Explicitly with a smi, whos value represents the number of repeated
71  // separators.
72  // 2) Implicitly between two consecutive strings a single separator.
73  //
74  // Here are some input/output examples given the separator string is ',':
75  //
76  // [1, 'hello', 2, 'world', 1] => ',hello,,world,'
77  // ['hello', 'world'] => 'hello,world'
78  //
79  // To avoid any allocations, this helper assumes the destination string is the
80  // exact length necessary to write the strings and separators from the fixed
81  // array.
82  // Since this is called via ExternalReferences, it uses raw Address values:
83  // - {raw_fixed_array} is a tagged FixedArray pointer.
84  // - {raw_separator} and {raw_dest} are tagged String pointers.
85  // - Returns a tagged String pointer.
86  static Address ArrayJoinConcatToSequentialString(Isolate* isolate,
87  Address raw_fixed_array,
88  intptr_t length,
89  Address raw_separator,
90  Address raw_dest);
91 
92  // Checks whether the Array has the current realm's Array.prototype as its
93  // prototype. This function is best-effort and only gives a conservative
94  // approximation, erring on the side of false, in particular with respect
95  // to Proxies and objects with a hidden prototype.
96  inline bool HasArrayPrototype(Isolate* isolate);
97 
98  DECL_CAST(JSArray)
99 
100  // Dispatched behavior.
101  DECL_PRINTER(JSArray)
102  DECL_VERIFIER(JSArray)
103 
104  // Number of element slots to pre-allocate for an empty array.
105  static const int kPreallocatedArrayElements = 4;
106 
107  // Layout description.
108 #define JS_ARRAY_FIELDS(V) \
109  V(kLengthOffset, kTaggedSize) \
110  /* Header size. */ \
111  V(kSize, 0)
112 
113  DEFINE_FIELD_OFFSET_CONSTANTS(JSObject::kHeaderSize, JS_ARRAY_FIELDS)
114 #undef JS_ARRAY_FIELDS
115 
116  static const int kLengthDescriptorIndex = 0;
117 
118  // Max. number of elements being copied in Array builtins.
119  static const int kMaxCopyElements = 100;
120 
121  // This constant is somewhat arbitrary. Any large enough value would work.
122  static const uint32_t kMaxFastArrayLength = 32 * 1024 * 1024;
123 
124  // Min. stack size for detecting an Array.prototype.join() call cycle.
125  static const uint32_t kMinJoinStackSize = 2;
126 
127  static const int kInitialMaxFastElementArray =
128  (kMaxRegularHeapObjectSize - FixedArray::kHeaderSize - kSize -
129  AllocationMemento::kSize) >>
130  kDoubleSizeLog2;
131 
132  // Valid array indices range from +0 <= i < 2^32 - 1 (kMaxUInt32).
133  static const uint32_t kMaxArrayIndex = kMaxUInt32 - 1;
134 
135  private:
136  DISALLOW_IMPLICIT_CONSTRUCTORS(JSArray);
137 };
138 
139 Handle<Object> CacheInitialJSArrayMaps(Handle<Context> native_context,
140  Handle<Map> initial_map);
141 
142 // The JSArrayIterator describes JavaScript Array Iterators Objects, as
143 // defined in ES section #sec-array-iterator-objects.
144 class JSArrayIterator : public JSObject {
145  public:
146  DECL_PRINTER(JSArrayIterator)
147  DECL_VERIFIER(JSArrayIterator)
148 
149  DECL_CAST(JSArrayIterator)
150 
151  // [iterated_object]: the [[IteratedObject]] inobject property.
152  DECL_ACCESSORS(iterated_object, Object)
153 
154  // [next_index]: The [[ArrayIteratorNextIndex]] inobject property.
155  // The next_index is always a positive integer, and it points to
156  // the next index that is to be returned by this iterator. It's
157  // possible range is fixed depending on the [[iterated_object]]:
158  //
159  // 1. For JSArray's the next_index is always in Unsigned32
160  // range, and when the iterator reaches the end it's set
161  // to kMaxUInt32 to indicate that this iterator should
162  // never produce values anymore even if the "length"
163  // property of the JSArray changes at some later point.
164  // 2. For JSTypedArray's the next_index is always in
165  // UnsignedSmall range, and when the iterator terminates
166  // it's set to Smi::kMaxValue.
167  // 3. For all other JSReceiver's it's always between 0 and
168  // kMaxSafeInteger, and the latter value is used to mark
169  // termination.
170  //
171  // It's important that for 1. and 2. the value fits into the
172  // Unsigned32 range (UnsignedSmall is a subset of Unsigned32),
173  // since we use this knowledge in the fast-path for the array
174  // iterator next calls in TurboFan (in the JSCallReducer) to
175  // keep the index in Word32 representation. This invariant is
176  // checked in JSArrayIterator::JSArrayIteratorVerify().
177  DECL_ACCESSORS(next_index, Object)
178 
179  // [kind]: the [[ArrayIterationKind]] inobject property.
180  inline IterationKind kind() const;
181  inline void set_kind(IterationKind kind);
182 
183  // Layout description.
184 #define JS_ARRAY_ITERATOR_FIELDS(V) \
185  V(kIteratedObjectOffset, kTaggedSize) \
186  V(kNextIndexOffset, kTaggedSize) \
187  V(kKindOffset, kTaggedSize) \
188  /* Header size. */ \
189  V(kSize, 0)
190 
191  DEFINE_FIELD_OFFSET_CONSTANTS(JSObject::kHeaderSize, JS_ARRAY_ITERATOR_FIELDS)
192 #undef JS_ARRAY_ITERATOR_FIELDS
193 
194  private:
195  DISALLOW_IMPLICIT_CONSTRUCTORS(JSArrayIterator);
196 };
197 
198 } // namespace internal
199 } // namespace v8
200 
201 #include "src/objects/object-macros-undef.h"
202 
203 #endif // V8_OBJECTS_JS_ARRAY_H_
Definition: v8.h:56
Definition: libplatform.h:13