<?php

declare(strict_types=1);

namespace Drupal\flowdrop_stategraph\Exception;

use Drupal\flowdrop\Exception\FlowDropException;

/**
 * Exception thrown when iterator is exhausted but more items expected.
 *
 * This exception is thrown when:
 * - Attempting to advance past the end of the iterator.
 * - Trying to get current item when iterator is exhausted.
 *
 * @api
 */
class IteratorExhaustedException extends FlowDropException {

  /**
   * Constructs a new IteratorExhaustedException.
   *
   * @param int $totalItems
   *   Total number of items in the iterator.
   * @param int $currentIndex
   *   Current index position.
   * @param string $message
   *   Optional custom message.
   * @param \Throwable|null $previous
   *   Previous exception for chaining.
   */
  public function __construct(
    public readonly int $totalItems,
    public readonly int $currentIndex,
    string $message = "",
    ?\Throwable $previous = NULL,
  ) {
    if ($message === "") {
      $message = sprintf(
        "Iterator exhausted: attempted to access index %d but only %d items available.",
        $currentIndex,
        $totalItems
      );
    }

    parent::__construct($message, 0, $previous);
  }

}
