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", соответственно, идентификатором ошибки, сообщением об ошибке и индексом входных аргументов элемента, вызвавшего ошибку. Например:

function y = foo (s, x), y = NaN; endfunction
cellfun ("factorial", {-1,2}, "ErrorHandler", @foo)
⇒ [NaN 2]

Используйте 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% медленнее первого метода. См. Перегрузка операторов для списка основных функций, которые можно использовать вместо анонимных.