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

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

: B = arrayfun (fcn, A)

: B = arrayfun (fcn, A1, A2, …)

: [B1, B2, …] = arrayfun (fcn, A, …)

: B = arrayfun (…, "UniformOutput", val)

: B = arrayfun (…, "ErrorHandler", errfcn)

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

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

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

cls = class (fcn (A(1));
B = zeros (size (A), cls);
for i = 1:numel (A)
  B(i) = fcn (A(i))
endfor

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

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

Если параметр val после дополнительного строкового входного аргумента "UniformOutput" имеет значение true (по умолчанию), именованная функция fcn должна возвращать один элемент, который затем будет объединён в возвращаемое значение типа матрицы. В противном случае, если этому параметру присвоено значение 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)
}

Если параметр errfcn после дополнительного строкового входного аргумента "ErrorHandler" является другой строкой, дескриптором функции, встроенной функцией или анонимной функцией, то errfcn задаёт функцию, вызываемую в случае ошибки, возникшей в fcn. Функция должна иметь следующий вид:

function [...] = errfcn (s, ...)

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

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.

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

Выходное значение y — разреженная матрица с той же структурой разреженности, что и входная матрица S. spfun сохраняет структуру разреженности, что отличается от простого применения функции f к разреженной матрице S при f (0) != 0.

Пример

Сохранение разреженности spfun и обычное применение функции

S = pi * speye (2,2)
S =

Compressed Column Sparse (rows = 2, cols = 2, nnz = 2 [50%])

  (1, 1) -> 3.1416
  (2, 2) -> 3.1416

y = spfun (@cos, S)
y =

Compressed Column Sparse (rows = 2, cols = 2, nnz = 2 [50%])

  (1, 1) -> -1
  (2, 2) -> -1


y = cos (S)
y =

Compressed Column Sparse (rows = 2, cols = 2, nnz = 4 [100%])

  (1, 1) -> -1
  (2, 1) -> 1
  (1, 2) -> 1
  (2, 2) -> -1

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

: A = cellfun ("fcn", C)

: A = cellfun ("size", C, k)

: A = cellfun ("isclass", C, class)

: A = cellfun (@fcn, C)

: A = cellfun (fcn, C)

: A = cellfun (fcn, C1, C2, …)

: [A1, A2, …] = cellfun (…)

: A = cellfun (…, "ErrorHandler", errfcn)

: A = cellfun (…, "UniformOutput", val)

Вычисляет функцию с именем «fcn» для элементов массива ячеек C.

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

isempty

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

islogical

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

isnumeric

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

isreal

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

length

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

ndims

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

numel

prodofsize

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

size

Возвращает размер вдоль k-го измерения.

isclass

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

Кроме того, cellfun принимает произвольную функцию fcn в виде встроенной функции, дескриптора функции или имени функции (в строке). Функция может принимать один или несколько аргументов; входные аргументы задаются как C1, C2 и т. д. Например:

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" имеет значение false, выходные значения объединяются в массив ячеек (или массивы ячеек). Например:

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

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

function [...] = errfcn (s, ...)

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

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

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

C = {...}
v = cellfun (@(x) det (x), C); # compute determinants
v = cellfun (@det, C);         # 40% faster

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

: A = structfun (fcn, S)

: A = structfun (…, "ErrorHandler", errfcn)

: A = structfun (…, "UniformOutput", val)

: [A, B, …] = structfun (…)

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

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

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

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" errfcn задаёт функцию, вызываемую в случае ошибки, возникшей в fcn. Функция имеет следующий вид:

function [...] = errfcn (se, ...)

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

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

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