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

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