Generator.prototype.return()

Метод return() экземпляров Generator действует так, как будто оператор return вставлен в тело генератора в текущей приостановленной позиции, что завершает генератор и позволяет ему выполнять любые задачи очистки при объединении с блоком try...finally.

Синтаксис

generatorInstance.return()
generatorInstance.return(value)

Параметры

value Необязательный

Возвращаемое значение.

Возвращаемое значение

Объект Object с двумя свойствами:

done

Булево значение:

• true, если поток управления функцией-генератором достиг конца.
• false, если поток управления функцией-генератором не достиг конца и может генерировать новые значения. Это может произойти только в том случае, если выражение return перехвачено в блоке try...finally и есть другие выражения yield в блоке finally.

value

Значение, переданное в качестве аргумента, или, если выражение yield обернуто в блок try...finally, значение, переданное/возвращенное из блока finally.

Исключения

TypeError

Выбрасывается, если генератор уже выполняется.

Описание

Метод return() при вызове может рассматриваться так, как будто в теле генератора в текущей приостановленной позиции вставлен оператор return value;, где value — это значение, переданное методу return(). Следовательно, в обычном потоке вызов return(value) вернет { done: true, value: value }. Однако, если выражение yield обернуто в блок try...finally, поток управления не выходит из тела функции, а вместо этого переходит к блоку finally. В этом случае возвращаемое значение может отличаться, а done может быть даже false, если в блоке yield есть дополнительные выражения finally.

Примеры

Использование return()

Следующий пример показывает генератор и метод return.

function* gen() {
  yield 1;
  yield 2;
  yield 3;
}

const g = gen();

g.next(); // { value: 1, done: false }
g.return("foo"); // { value: "foo", done: true }
g.next(); // { value: undefined, done: true }

Если return(value) вызывается для генератора, который уже находится в состоянии "завершен", генератор останется в состоянии "завершен".

Если аргумент не предоставлен, свойство value возвращаемого объекта будет undefined. Если аргумент предоставлен, он станет значением свойства value возвращаемого объекта, если только выражение yield не обернуто в блок try...finally.

function* gen() {
  yield 1;
  yield 2;
  yield 3;
}

const g = gen();
g.next(); // { value: 1, done: false }
g.next(); // { value: 2, done: false }
g.next(); // { value: 3, done: false }
g.next(); // { value: undefined, done: true }
g.return(); // { value: undefined, done: true }
g.return(1); // { value: 1, done: true }

Использование return() с try...finally

Тот факт, что был вызван метод return, может быть известен самому генератору только в том случае, если выражение yield обернуто в блок try...finally.

Когда метод return вызывается для генератора, который приостановлен в блоке try, выполнение в генераторе продолжается в блоке finally — поскольку блок finally операторов try...finally всегда выполняется.

function* gen() {
  yield 1;
  try {
    yield 2;
    yield 3;
  } finally {
    yield "cleanup";
  }
}

const g1 = gen();
g1.next(); // { value: 1, done: false }

// Execution is suspended before the try...finally.
g1.return("early return"); // { value: 'early return', done: true }

const g2 = gen();
g2.next(); // { value: 1, done: false }
g2.next(); // { value: 2, done: false }

// Execution is suspended within the try...finally.
g2.return("early return"); // { value: 'cleanup', done: false }

// The completion value is preserved
g2.next(); // { value: 'early return', done: true }

// Generator is in the completed state
g2.return("not so early return"); // { value: 'not so early return', done: true }

Возвращаемое значение блока finally также может стать value результата, возвращенного из вызова return.

function* gen() {
  try {
    yield 1;
  } finally {
    return "cleanup";
  }
}

const generator = gen();
generator.next(); // { value: 1, done: false }
generator.return("early return"); // { value: 'cleanup', done: true }

Спецификации

Совместимость с браузерами

См. также

• function*