19.3 Применение функций

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

arrayfun (func, A)

x = arrayfun (func, A)

x = arrayfun (func, A, b, …)

[x, y, …] = arrayfun (func, A, …)

arrayfun (…, "UniformOutput", val)

arrayfun (…, "ErrorHandler", errfunc)

Выполнить функцию над каждым элементом массива.

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

Первый входной аргумент func может быть строкой, функцией-обработчиком, встроенной функцией или анонимной функцией. Входной аргумент A может быть логическим массивом, числовым массивом, строковым массивом, массивом структур или массивом ячеек. Вызовом функции arrayfun каждый элемент A передается в функцию func индивидуально.

Функция также может принимать более двух входных аргументов, которые передаются в качестве третьего входного аргумента b, четвертого входного аргумента c и т. д. Если предоставлено более одного входного массива, все входные аргументы должны иметь одинаковые размеры, например:

arrayfun (@atan2, [1, 0], [0, 1])
     ⇒ [ 1.57080   0.00000 ]

Если параметр val после дополнительного строкового входного аргумента "UniformOutput" установлен true (по умолчанию), то функция func должна возвращать один элемент, который затем будет соединён в результирующее значение и будет иметь тип матрицы. В противном случае, если этот параметр установлен в false, выходы объединяются в массив ячеек. Например:

arrayfun (@(x,y) x:y, "abc", "def", "UniformOutput", false)
⇒
   {
     [1,1] = abcd
     [1,2] = bcde
     [1,3] = cdef
   }

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

[A, B, C] = arrayfun (@find, [10; 0], "UniformOutput", false)
⇒
A =
{
   [1,1] =  1
   [2,1] = [](0x0)
}
B =
{
   [1,1] =  1
   [2,1] = [](0x0)
}
C =
{
   [1,1] =  10
   [2,1] = [](0x0)
}

Если параметр errfunc после дополнительного строкового входного аргумента "ErrorHandler" является другой строкой, функцией-обработчиком, встроенной функцией или анонимной функцией, то errfunc определяет функцию для вызова в случае возникновения ошибки в func. Определение функции должно иметь вид

function […] = errfunc (s, …)

где есть дополнительный входной аргумент для errfunc относительно func, заданный s. Это структура с элементами "identifier", "message", и "index", представляющими соответственно идентификатор ошибки, сообщение об ошибке и индекс элементов массива, вызвавших ошибку. Размер выходного аргумента errfunc должен быть таким же, как размер выходного аргумента func, иначе возникает реальная ошибка. Например:

function y = ferr (s, x), y = "MyString"; endfunction
arrayfun (@str2num, [1234],
          "UniformOutput", false, "ErrorHandler", @ferr)
⇒
   {
     [1,1] = MyString
   }

См. также: spfun, cellfun, structfun.

y = spfun (f, S)

Вычислить f(S) для ненулевых значений S.

Это приводит к разреженной матрице с той же структурой, что и S. Функцию f можно передать в виде строки, функции-обработчика или встроенной функции.

См. также: arrayfun, cellfun, structfun.

cellfun (name, C)

cellfun ("size", C, k)

cellfun ("isclass", C, class)

cellfun (func, C)

cellfun (func, C, D)

[a, …] = cellfun (…)

cellfun (…, "ErrorHandler", errfunc)

cellfun (…, "UniformOutput", val)

Вычислить функцию с именем name над элементами массива ячеек C.

Элементы из C передаются в функцию индивидуально. Функция name может быть одной из функций

isempty

Возвращает 1 для пустых элементов.

islogical

Возвращает 1 для логических элементов.

isnumeric

Возвращает 1 для числовых элементов.

isreal

Возвращает 1 для вещественных элементов.

length

Возвращает вектор длин элементов ячеек.

ndims

Возвращает количество измерений каждого элемента.

numel

prodofsize

Возвращает количество элементов, содержащихся в каждом элементе ячейки. Число является произведением измерений объекта в каждом элементе ячейки.

size

Возвращает размер по k-му измерению.

isclass

Возвращает 1 для элементов класса class.

Кроме того, cellfun принимает произвольную функцию func в виде встроенной функции, функции-обработчика или имени функции (в строковом виде). Функция может принимать один или несколько аргументов, входные аргументы задаются C, D и т. д. Аналогично, функция может возвращать один или несколько выходных аргументов. Например:

cellfun ("atan2", {1, 0}, {0, 1})
     ⇒ [ 1.57080   0.00000 ]

Количество выходных аргументов cellfun соответствует количеству выходных аргументов функции. Выходы функции собираются в выходные аргументы cellfun следующим образом:

function [a, b] = twoouts (x)
  a = x;
  b = x*x;
endfunction
[aa, bb] = cellfun (@twoouts, {1, 2, 3})
     ⇒
        aa =
           1 2 3
        bb =
           1 4 9

Обратите внимание, что по умолчанию выходной(ые) аргумент(ы) являются массивами того же размера, что и входные аргументы. Входные аргументы, которые являются одиночными (1x1) ячейками, будут автоматически расширены до размера других аргументов.

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

cellfun ("tolower", {"Foo", "Bar", "FooBar"},
         "UniformOutput", false)
⇒ {"foo", "bar", "foobar"}

При заданном параметре "ErrorHandler", errfunc определяет функцию для вызова в случае возникновения ошибки в func. Форма функции:

function […] = errfunc (s, …)

где имеется дополнительный входной аргумент для errfunc относительно func, заданный s. Это структура с элементами "identifier", "message", и "index", представляющими соответственно идентификатор ошибки, сообщение об ошибке и индекс входных аргументов элемента, вызвавшего ошибку. Для примера использования обработчика ошибок см. cellfun.

Используйте cellfun разумно. Функция cellfun является полезным инструментом для избегания циклов. Она часто используется с анонимными функциями-обработчиками; однако вызов анонимной функции влечёт за собой издержки, сопоставимые с издержками вызова функции m-файла. Передача обработчика встроенной функции быстрее, поскольку интерпретатор не участвует во внутреннем цикле. Например:

a = {…}
v = cellfun (@(x) det (x), a); # compute determinants
v = cellfun (@det, a); # faster

См. также: arrayfun, structfun, spfun.

structfun (func, S)

[A, …] = structfun (…)

structfun (…, "ErrorHandler", errfunc)

structfun (…, "UniformOutput", val)

Вычислить функцию с именем name над полями структуры S. Поля S передаются функции func индивидуально.

structfun принимает произвольную функцию func в виде встроенной функции, функции-обработчика или имени функции (в строковом виде). В случае строкового аргумента функция должна принимать один аргумент с именем x и возвращать строковое значение. Если функция возвращает более одного аргумента, они возвращаются как отдельные выходные переменные.

Если параметр "UniformOutput" установлен в true (по умолчанию), то функция должна возвращать один элемент, который будет конкатенирован в результирующее значение. Если "UniformOutput" ложно, выходы помещаются в структуру с теми же именами полей, что и входная структура.

s.name1 = "John Smith";
s.name2 = "Jill Jones";
structfun (@(x) regexp (x, '(\w+)$', "matches"){1}, s,
           "UniformOutput", false)
  ⇒ scalar structure containing the fields:
       name1 = Smith
       name2 = Jones

При заданном параметре "ErrorHandler", errfunc определяет функцию для вызова в случае возникновения ошибки в func. Форма функции:

function […] = errfunc (se, …)

где есть дополнительный входной аргумент для errfunc относительно func, заданный se. Это структура с элементами "identifier", "message" и "index", представляющими соответственно идентификатор ошибки, сообщение об ошибке и индекс входных аргументов элемента, вызвавшего ошибку. Пример использования обработчика ошибок см. в cellfun.

См. также: cellfun, arrayfun, spfun.

В соответствии с предыдущими рекомендациями, старайтесь использовать встроенные функции Octave, когда это возможно, для лучшей производительности. Это рекомендация, особенно для четырёх функций выше. Например, при сложении двух массивов по элементам можно использовать обработчик встроенной функции сложения @plus или определить анонимную функцию @(x,y) x + y. Но анонимная функция на 60% медленнее первого метода. См. Перегрузка операторов для списка базовых функций, которые можно использовать вместо анонимных.