js/src/jsiter.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  * vim: set ts=8 sw=4 et tw=78:
   3  *
   4  * ***** BEGIN LICENSE BLOCK *****
   5  * Version: MPL 1.1/GPL 2.0/LGPL 2.1 *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is Mozilla Communicator client code, released
  17  * March 31, 1998.
  18  *
  19  * The Initial Developer of the Original Code is
  20  * Netscape Communications Corporation.
  21  * Portions created by the Initial Developer are Copyright (C) 1998
  22  * the Initial Developer. All Rights Reserved.
  23  *
  24  * Contributor(s):
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either of the GNU General Public License Version 2 or later (the "GPL"),
  28  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #ifndef jsiter_h___
  41 #define jsiter_h___
  42
  43 /*
  44  * JavaScript iterators.
  45  */
  46 #include "jscntxt.h"
  47 #include "jsprvtd.h"
  48 #include "jspubtd.h"
  49 #include "jsversion.h"
  50
  51 /*
  52  * NB: these flag bits are encoded into the bytecode stream in the immediate
  53  * operand of JSOP_ITER, so don't change them without advancing jsxdrapi.h's
  54  * JSXDR_BYTECODE_VERSION.
  55  */
  56 #define JSITER_ENUMERATE  0x1   /* for-in compatible hidden default iterator */
  57 #define JSITER_FOREACH    0x2   /* return [key, value] pair rather than key */
  58 #define JSITER_KEYVALUE   0x4   /* destructuring for-in wants [key, value] */
  59 #define JSITER_OWNONLY    0x8   /* iterate over obj's own properties only */
  60 #define JSITER_HIDDEN     0x10  /* also enumerate non-enumerable properties */
  61
  62 /*
  63  * For cacheable native iterators, whether the iterator is currently active.
  64  * Not serialized by XDR.
  65  */
  66 #define JSITER_ACTIVE     0x1000
  67
  68 namespace js {
  69
  70 struct NativeIterator {
  71     JSObject  *obj;
  72     void      *props_array;
  73     void      *props_cursor;
  74     void      *props_end;
  75     uint32    *shapes_array;
  76     uint32    shapes_length;
  77     uint32    shapes_key;
  78     uint32    flags;
  79     JSObject  *next;  /* Forms cx->enumerators list, garbage otherwise. */
  80
  81     bool isKeyIter() const { return (flags & JSITER_FOREACH) == 0; }
  82
  83     inline jsid *beginKey() const {
  84         JS_ASSERT(isKeyIter());
  85         return (jsid *)props_array;
  86     }
  87
  88     inline jsid *endKey() const {
  89         JS_ASSERT(isKeyIter());
  90         return (jsid *)props_end;
  91     }
  92
  93     size_t numKeys() const {
  94         return endKey() - beginKey();
  95     }
  96
  97     jsid *currentKey() const {
  98         JS_ASSERT(isKeyIter());
  99         return reinterpret_cast<jsid *>(props_cursor);
 100     }
 101
 102     void incKeyCursor() {
 103         JS_ASSERT(isKeyIter());
 104         props_cursor = reinterpret_cast<jsid *>(props_cursor) + 1;
 105     }
 106
 107     inline js::Value *beginValue() const {
 108         JS_ASSERT(!isKeyIter());
 109         return (js::Value *)props_array;
 110     }
 111
 112     inline js::Value *endValue() const {
 113         JS_ASSERT(!isKeyIter());
 114         return (js::Value *)props_end;
 115     }
 116
 117     size_t numValues() const {
 118         return endValue() - beginValue();
 119     }
 120
 121     js::Value *currentValue() const {
 122         JS_ASSERT(!isKeyIter());
 123         return reinterpret_cast<js::Value *>(props_cursor);
 124     }
 125
 126     void incValueCursor() {
 127         JS_ASSERT(!isKeyIter());
 128         props_cursor = reinterpret_cast<js::Value *>(props_cursor) + 1;
 129     }
 130
 131     static NativeIterator *allocateKeyIterator(JSContext *cx, uint32 slength,
 132                                                const js::AutoIdVector &props);
 133     static NativeIterator *allocateValueIterator(JSContext *cx,
 134                                                  const js::AutoValueVector &props);
 135     void init(JSObject *obj, uintN flags, uint32 slength, uint32 key);
 136
 137     void mark(JSTracer *trc);
 138 };
 139
 140 bool
 141 VectorToIdArray(JSContext *cx, js::AutoIdVector &props, JSIdArray **idap);
 142
 143 JS_FRIEND_API(bool)
 144 GetPropertyNames(JSContext *cx, JSObject *obj, uintN flags, js::AutoIdVector *props);
 145
 146 bool
 147 GetIterator(JSContext *cx, JSObject *obj, uintN flags, js::Value *vp);
 148
 149 bool
 150 VectorToKeyIterator(JSContext *cx, JSObject *obj, uintN flags, js::AutoIdVector &props, js::Value *vp);
 151
 152 bool
 153 VectorToValueIterator(JSContext *cx, JSObject *obj, uintN flags, js::AutoValueVector &props, js::Value *vp);
 154
 155 /*
 156  * Creates either a key or value iterator, depending on flags. For a value
 157  * iterator, performs value-lookup to convert the given list of jsids.
 158  */
 159 bool
 160 EnumeratedIdVectorToIterator(JSContext *cx, JSObject *obj, uintN flags, js::AutoIdVector &props, js::Value *vp);
 161
 162 }
 163
 164 /*
 165  * Convert the value stored in *vp to its iteration object. The flags should
 166  * contain JSITER_ENUMERATE if js_ValueToIterator is called when enumerating
 167  * for-in semantics are required, and when the caller can guarantee that the
 168  * iterator will never be exposed to scripts.
 169  */
 170 extern JS_FRIEND_API(JSBool)
 171 js_ValueToIterator(JSContext *cx, uintN flags, js::Value *vp);
 172
 173 extern JS_FRIEND_API(JSBool)
 174 js_CloseIterator(JSContext *cx, JSObject *iterObj);
 175
 176 bool
 177 js_SuppressDeletedProperty(JSContext *cx, JSObject *obj, jsid id);
 178
 179 bool
 180 js_SuppressDeletedIndexProperties(JSContext *cx, JSObject *obj, jsint begin, jsint end);
 181
 182 /*
 183  * IteratorMore() indicates whether another value is available. It might
 184  * internally call iterobj.next() and then cache the value until its
 185  * picked up by IteratorNext(). The value is cached in the current context.
 186  */
 187 extern JSBool
 188 js_IteratorMore(JSContext *cx, JSObject *iterobj, js::Value *rval);
 189
 190 extern JSBool
 191 js_IteratorNext(JSContext *cx, JSObject *iterobj, js::Value *rval);
 192
 193 extern JSBool
 194 js_ThrowStopIteration(JSContext *cx);
 195
 196 #if JS_HAS_GENERATORS
 197
 198 /*
 199  * Generator state codes.
 200  */
 201 typedef enum JSGeneratorState {
 202     JSGEN_NEWBORN,  /* not yet started */
 203     JSGEN_OPEN,     /* started by a .next() or .send(undefined) call */
 204     JSGEN_RUNNING,  /* currently executing via .next(), etc., call */
 205     JSGEN_CLOSING,  /* close method is doing asynchronous return */
 206     JSGEN_CLOSED    /* closed, cannot be started or closed again */
 207 } JSGeneratorState;
 208
 209 struct JSGenerator {
 210     JSObject            *obj;
 211     JSGeneratorState    state;
 212     JSFrameRegs         regs;
 213     JSObject            *enumerators;
 214     JSStackFrame        *floating;
 215     js::Value           floatingStack[1];
 216
 217     JSStackFrame *floatingFrame() {
 218         return floating;
 219     }
 220
 221     JSStackFrame *liveFrame() {
 222         JS_ASSERT((state == JSGEN_RUNNING || state == JSGEN_CLOSING) ==
 223                   (regs.fp != floatingFrame()));
 224         return regs.fp;
 225     }
 226 };
 227
 228 extern JSObject *
 229 js_NewGenerator(JSContext *cx);
 230
 231 /*
 232  * Generator stack frames do not have stable pointers since they get copied to
 233  * and from the generator object and the stack (see SendToGenerator). This is a
 234  * problem for Block and With objects, which need to store a pointer to the
 235  * enclosing stack frame. The solution is for Block and With objects to store
 236  * a pointer to the "floating" stack frame stored in the generator object,
 237  * since it is stable, and maintain, in the generator object, a pointer to the
 238  * "live" stack frame (either a copy on the stack or the floating frame). Thus,
 239  * Block and With objects must "normalize" to and from the floating/live frames
 240  * in the case of generators using the following functions.
 241  */
 242 inline JSStackFrame *
 243 js_FloatingFrameIfGenerator(JSContext *cx, JSStackFrame *fp)
 244 {
 245     JS_ASSERT(cx->stack().contains(fp));
 246     if (JS_UNLIKELY(fp->isGeneratorFrame()))
 247         return cx->generatorFor(fp)->floatingFrame();
 248     return fp;
 249 }
 250
 251 /* Given a floating frame, given the JSGenerator containing it. */
 252 extern JSGenerator *
 253 js_FloatingFrameToGenerator(JSStackFrame *fp);
 254
 255 inline JSStackFrame *
 256 js_LiveFrameIfGenerator(JSStackFrame *fp)
 257 {
 258     return fp->isGeneratorFrame() ? js_FloatingFrameToGenerator(fp)->liveFrame() : fp;
 259 }
 260
 261 #endif
 262
 263 extern js::Class js_GeneratorClass;
 264 extern js::Class js_IteratorClass;
 265 extern js::Class js_StopIterationClass;
 266
 267 static inline bool
 268 js_ValueIsStopIteration(const js::Value &v)
 269 {
 270     return v.isObject() && v.toObject().getClass() == &js_StopIterationClass;
 271 }
 272
 273 extern JSObject *
 274 js_InitIteratorClasses(JSContext *cx, JSObject *obj);
 275
 276 #endif /* jsiter_h___ */