Возврат и обработка нескольких значений

Обычно результатом вызова Lisp’овой функции является один Lisp’овый объект. Однако, иногда для функции удобно вычислить несколько объектов и вернуть их. Common Lisp представляет механизм для прямой обработки нескольких значений. Механизм удобнее и эффективнее, чем исполнение трюков со списками или глобальными переменными.

7.10.1 Конструкции для обработки нескольких значений

Обычно не используется несколько значений. Для возврата и обработки нескольких значений требуются операторы. Если вызывающий функцию код не требует нескольких значений, однако вызываемая функция возвращает их несколько, то для кода берётся только первое значение. Все оставшиеся значения игнорируются. Если вызываемая функция возвращает ноль значений, вызывающий код в качестве значения получает nil.

values — это главный примитив для возврата нескольких значений. Он принимает любое количество аргументов и возвращает столько же значений. Если последняя форма тела функции является values с тремя аргументами, то вызов такой функции вернёт три значения. Другие операторы также возвращают несколько значений, но они могут быть описаны в терминах values. Некоторые встроенные Common Lisp функции, такая как ﬂoor, возвращают несколько значений.

Операторы, обрабатывающие несколько значений, представлены ниже:

Они задают форму для вычисления и указывают куда поместить значения возвращаемые данной формой.

[Функция] values &rest args

Все аргументы в таком же порядке возвращаются, как значения. Например,

(defun polar (x y) (values (sqrt (+ (* x x) (* y y))) (atan y x))) (multiple-value-bind (r theta) (polar 3.0 4.0) (vector r theta)) ⇒ #(5.0 0.9272952)

Выражение (values) возвращает ноль значений. Это стандартная идиома для возврата из функции нулевого количества значений.

Иногда необходимо указать явно, что функция будет возвращать только одно значение. Например, функция

(defun foo (x y) (ﬂoor (+ x y) y))

будет возвращать два значения, потому что ﬂoor возвращает два значения. Может быть второе значение не имеет смысла в данном контексте, или есть причины не тратить время на вычисления второго значения. Функция values является стандартной идиомой для указания того, что будет возвращено только одно значение, как показано в следующем примере.

(defun foo (x y) (values (ﬂoor (+ x y) y)))

Это работает, потому что values возвращает только одно значения для каждой формы аргумента. Если форма аргумента возвращает несколько значений, то используется только первое, а остальные игнорируются.

В Common Lisp’е для вызывающего кода нет возможности различить, было ли возвращено просто одно значение или было возвращено только одно значение в с помощью values. Например значения, возвращённые выражением (+ 1 2) и (values (+ 1 2)), идентичны во всех отношениях: они оба просто равны 3.

[Константа] multiple-values-limit

Значение multiple-values-limit является положительным целым числом, которое невключительно указывает наибольшее возможное количество возвращаемых значений. Это значение зависит от реализации, но не может быть менее 20. (Разработчики рекомендуется делать это ограничение как можно большим без потери в производительности.) Смотрите lambda-parameters-limit и call-arguments-limit.

[Функция] values-list list

Все элементы списка list будут возвращены как несколько значений. Например:

(values-list (list a b c)) ≡ (values a b c)

Можно обозначить так,

(values-list list) ≡ (apply #’values list)

но values-list может быть более ясным или эффективным.

[Специальный оператор] multiple-value-call function {form}*

multiple-value-call сначала вычисляет function для получения функции и затем вычисляет все формы forms. Все значения форм forms собираются вместе (все, а не только первые) и передаются как аргументы функции. Результат multiple-value-call является тем, что вернула функция. Например:

(+ (ﬂoor 5 3) (ﬂoor 19 4)) ≡ (+ 1 4) ⇒ 5 (multiple-value-call #’+ (ﬂoor 5 3) (ﬂoor 19 4)) ≡ (+ 1 2 4 3) ⇒ 10 (multiple-value-list form) ≡ (multiple-value-call #’list form)

[Специальный оператор] multiple-value-prog1 form {form}*

multiple-value-prog1 вычисляет первую форму form и сохраняет все значения, возвращённые данной формой. Затем она слева направо вычисляет оставшиеся формы, игнорируя их значения. Значения, возвращённые первой формой, становятся результатом всей формы multiple-value-prog1. Смотрите prog1, которая всегда возвращает одно значение.

[Макрос] multiple-value-bind ({var}*) values-form{declaration}* {form}*

Вычисляется values-form и каждое значение результата связывается соответственно с переменными указанными в первом параметре. Если переменных больше, чем возвращаемых значений, для оставшихся переменных используется значение nil. Если значений больше, чем переменных, лишние значения игнорируются. Переменные связываются со значениями только на время выполнения форм тела, которое является неявным progn. Например:

(multiple-value-bind (x) (ﬂoor 5 3) (list x)) ⇒ (1) (multiple-value-bind (x y) (ﬂoor 5 3) (list x y)) ⇒ (1 2) (multiple-value-bind (x y z) (ﬂoor 5 3) (list x y z)) ⇒ (1 2 nil)

[Макрос] multiple-value-setq variables form

Аргумент variables должен быть списком переменных. Вычисляется форма form и переменным присваиваются (не связываются) значения, возвращённые этой формой. Если переменных больше, чем значений, оставшимся переменным присваивается nil. Если значений больше, чем переменных, лишние значения игнорируются.

multiple-value-setq всегда возвращает одно значение, которое является первым из возвращённых значений формы form, или nil, если форма form вернула ноль значений.

[Макрос] nth-value n form

Формы аргументов n и form вычисляются. Значение n должно быть неотрицательным целым, и форма form должна возвращать любое количество значение. Целое число n используется, как индекс (начиная с нуля), для доступа к списку значений. Форма возвращает элемент в позиции n из списка результатов вычисления формы form. Если позиции не существует, возвращается nil.

В качестве примера, mod мог бы быть определён так:

(defun mod (number divisor) (nth-value 1 (ﬂoor number divisor)))

7.10.2 Правила управления возвратом нескольких значений

Часто случается так, что значение оператора или макроса определено как значение одного из подвыражений. Например, значение cond является значением последнего подвыражения в исполняемой ветке.

В большинстве таких случаев, если подвыражение возвращает несколько значений, тогда и оригинальная форма возвращает все эти значения. Эта передача значений, конечно, не будет иметь место, если не была выполнена специальная форма для обработки возврата нескольких значений.

Из операторов может быть неявно возвращено несколько значений в соответствие со следующими правилами:

eval возвращает несколько значений, если переданная ему форму при вычислении вернула несколько значений.
apply, funcall и multiple-value-call передают обратно несколько значений из применяемой или вызываемой функции.

progn

Оператор progn передаёт обратно несколько значений полученных при вычислении последней подформы. В другие ситуациях, называемых «неявный progn», в которых вычисляется несколько форм и результаты всех, кроме последней формы, игнорируются, также передаётся обратно несколько значений от формы. Такие ситуации включают тело лямбда-выражения, в частности в defun, defmacro и deftype. Также включаются тела конструкций eval-when, progv, let, let*, when, unless, block, multiple-value-bind и catch. И также включаются подвыражения условных конструкций case, typecase, ecase, etypecase, ccase и ctypecase.

if передаёт обратно несколько значений из любой выбранной подформы (ветки then или else).
and и or передают обратно несколько значений из последней подформы, но ни из какой другой непоследней подформы.
cond передаёт обратно несколько значений из последней подформы неявного progn выделенного подвыражения. Однако, если выделенное подвыражение является «синглтоном», будет возвращено только одно значение (не-nil значение предиката). Это верно, даже если выражение «синглтон» является последним подвыражением cond. Нельзя рассматривать последнее подвыражение (x), как будто оно (t x). Последнее подвыражение передаёт обратно несколько значений из формы x.

При нормальном завершении конструкция block передаёт обратно несколько значений из её последней подформы. Если для завершения использовалась return-from (или return), тогда return-from передаёт обратно несколько значений из своей подформы, как значения всей конструкции block. Другие конструкции, создающие неявные блоки, такие как do, dolist, dotimes, prog и prog*, также передают обратно несколько значений, заданных с помощью return-from (или return).
do передаёт обратно несколько значений из последней формы подвыражения выхода, точно также, как если бы подвыражение выхода было подвыражение cond. Подобным образом действуют dolist и dotimes. Они возвращают несколько значений из формы resultform, если она была выполнена. Эти ситуации также являются примерами явного использования return-from.

Конструкция catch возвращает несколько значений, если результат формы в throw, которая осуществляет выход из этого catch, возвращает несколько значений.

multiple-value-prog1 передаёт обратно несколько значений из его первой подформы. Однако, prog1 всегда возвращает одно значение.
unwind-protect возвращает несколько значений, если форма, которую он защищает, вернула несколько значений.
the возвращает несколько значений, если в нем содержащаяся форма возвращает несколько значений.

prog1, prog2, setq и multiple-value-setq — это формы, которые никогда не передают обратно несколько значений. Стандартный метод для явного указания возврата одного значения из формы x является запись (values x).

Наиболее важное правило насчёт нескольких значений: Не важно сколько значений возвращает форма, если форма является аргументом в вызове функции, то будет использовано только одно значение (первое).

Например, если вы записали (cons (ﬂoor x)), тогда cons всегда получить только один аргумент (что, конечно, является ошибкой), хотя и ﬂoor возвращает два значения. Для того, чтобы поместить оба значения ﬂoor в cons, можно записать что-то вроде этого: (multiple-value-call #’cons (ﬂoor x)). В обычном вызове функции, каждый форма аргумента предоставляется только один аргумент. Если такая форма возвращает ноль значение, в качестве аргумента используется nil. А если возвращает более одного значения, все они, кроме первого, игнорируются. Также и условные конструкции, например if, которые проверяют значения формы, используют только одно первое значение, остальные игнорируются. Такие конструкции будут использовать nil если форма вернула ноль значений.

7.10 Возврат и обработка нескольких значений

7.10.1 Конструкции для обработки нескольких значений

7.10.2 Правила управления возвратом нескольких значений