chromium/third_party/blink/renderer/bindings/core/v8/script_iterator.h

// Copyright 2016 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef THIRD_PARTY_BLINK_RENDERER_BINDINGS_CORE_V8_SCRIPT_ITERATOR_H_
#define THIRD_PARTY_BLINK_RENDERER_BINDINGS_CORE_V8_SCRIPT_ITERATOR_H_

#include "third_party/blink/renderer/bindings/core/v8/world_safe_v8_reference.h"
#include "third_party/blink/renderer/core/core_export.h"
#include "third_party/blink/renderer/platform/heap/garbage_collected.h"
#include "third_party/blink/renderer/platform/wtf/allocator/allocator.h"
#include "v8/include/v8.h"

namespace blink {

class ExceptionState;
class ExecutionContext;

// This class provides a wrapper for iterating over any ES object that
// implements the iterable and iterator protocols. Namely:
// * The object or an object in its prototype chain has an @@iterator property
//   that is a function that returns an iterator object.
// * The iterator object has a next() method that returns an object with at
//   least two properties:
//   1. done: A boolean indicating whether iteration should stop. Can be
//      omitted when false.
//   2. value: Any object. Can be omitted when |done| is true.
//
// In general, this class should be preferred over using the
// GetEsIteratorMethod() and GetEsIteratorWithMethod() functions directly.
//
// Usage:
//   v8::Local<v8::Object> es_object = ...;
//   auto script_iterator = ScriptIterator::FromIterable(
//       isolate, es_object, exception_state);
//   if (exception_state.HadException())
//     return;
//   if (!script_iterator.IsNull()) {
//     while (script_iterator.Next(execution_context, exception_state)) {
//       // When `Next()` puts an exception on the stack, it always returns
//       // false, thus breaking out of this loop.
//       DCHECK(!exception_state.HadException());
//       v8::Local<v8::Value> value =
//           script_iterator.GetValue().ToLocalChecked();
//       // Do something with `value`.
//     }
//   }
//
//   // See documentation above.
//   if (exception_state.HadException()) {
//     return;
//   }
class CORE_EXPORT ScriptIterator { … };

}  // namespace blink

#endif  // THIRD_PARTY_BLINK_RENDERER_BINDINGS_CORE_V8_SCRIPT_ITERATOR_H_