File Exchange

image thumbnail

埃博拉酱的 函数助手 Function Helpers

version 4.0.0 (70.4 KB) by 埃博拉酱
埃博拉酱的MATLAB函数助手。包括各种花式批量调用函数,以及函数定义和使用时的实用工具

3 Downloads

Updated 18 Jul 2021

From GitHub

View license on GitHub

埃博拉酱的MATLAB函数助手,依赖埃博拉酱的数据操纵工具包

本项目的发布版本号遵循语义化版本规范。开发者认为这是一个优秀的规范,并向每一位开发者推荐遵守此规范。

目录

本包中所有函数均在EbolaChan.FunctionHelpers命名空间下,使用前需import。使用命名空间是一个好习惯,可以有效防止命名冲突,避免编码时不必要的代码提示干扰。

import EbolaChan.FunctionHelpers.*;
  • DimensionFun 对数组按维度执行函数,支持单一维度隐式扩展和返回数组自动拼接
  • DistributeVararginByValidation 根据验证函数将输入的Varargin分发到输出变量
  • FolderFun 取对一个文件夹下所有满足给定文件名模式的文件的绝对路径,对它们执行函数
  • ParseRepeatingFlagArguments 分析旗帜类重复参数到逻辑变量
  • RepeatingFun 重复多次调用函数,为每个重复参数生成一个返回值

DimensionFun

对数组按维度执行函数,支持单一维度隐式扩展和返回数组自动拼接

对数组进行批处理是十分常用的操作。但是arrayfun和cellfun只能进行按元素运算,不能按行、按列甚至按平面运算,而且不支持单一维度隐式扩展,如果返回值不是标量还不能自动拼接。采用本函数可以实现按任意维度运算,且支持单一维度隐式扩展,返回数组自动拼接。

%% 图像拼接-1
%本示例将一系列宽度相同的图片纵向拼接成一张长图。假设ImagePaths是一个包含了待拼接图像路径的列向量
imshow(DimensionFun(@imread,ImagePaths,"CatMode","Linear"));
%由于ImagePaths是向量,且imread返回uint8数值类型,因此以下写法也是等效的:
imshow(DimensionFun(@imread,ImagePaths,"CatMode","Linear"));
%% 图像拼接-2
%同样是拼接图象,如果ImagePaths是一个待拼接的子图路径的矩阵呢?同样可以按照这个矩阵对这些图像自动进行二维拼接!
imshow(DimensionFun(@imread,ImagePaths,"CatMode","CanCat"));
%% 异形数组拼接
A={1 [2 3]
[4 5] 6}
%此元胞数组直接使用cell2mat拼接会报错,但可以使用本函数拼接:
C=DimensionFun(@cell2mat,A);
%此示例仅用于展示DimensionFun的拼接功能,实际上可以直接使用SuperCell2Mat(A)一步到位。本函数实际上也是调用该函数实现的。
%% 序列采样-拆分打包与隐式扩展的相互作用展示
Sequence=1:10;
Start=(1:5)';
End=(6:10)';
disp(DimensionFun(@(Sequence,Start,End)Sequence(Start:End),Sequence,Start,End,"SplitDimensions",1,"CatMode","Linear"));
%输出
%     1     2     3     4     5     6
%     2     3     4     5     6     7
%     3     4     5     6     7     8
%     4     5     6     7     8     9
%     5     6     7     8     9    10
%注意,由于SplitDimensions仅为第1维,因此具有单一第1维的Sequence发生了隐式扩展,而具有单一第2维的Start和End未发生隐式扩展,而是直接打包交付给Function运算。

位置参数

Function(1,1)function_handle,必需,要执行的函数。必须接受等同于Arguments重复次数的参数

Arguments,重复,输入参数数组。输入的数组个数必须等于Function所能接受的输入值个数。所有数组各维度尺寸要么相等,要么为1,不允许各不相同的维度尺寸。不允许输入表格或其它非MATLAB标准数组,请始终先转化为MATLAB数组或元胞数组。

名称-值对组参数

以下两个参数只能选择其中一个进行指定

另一个将会自动计算得出。如果两个参数都不指定,将把第一个Arguments所有非单一维度视为SplitDimensions,其它维度作为PackDimensions。

  • PackDimensions(1,:)uint8{mustBePositive},将每个Arguments数组的指定维度打包,在其它维度(即SplitDimensions)上拆分,分别交付给Function执行
  • SplitDimensions(1,:)uint8{mustBePositive},在每个Arguments数组的指定维度上拆分,将其它维度(即PackDimensions)打包,分别交付给Function执行

注意,拆分-打包步骤在隐式扩展之前。也就是说,由于PackDimensions指定的维度被包入了同一个元胞当中,尺寸恒为1,即使不同数组间这些维度具有不同的尺寸,也不会进行隐式扩展。隐式扩展仅在SplitDimensions中进行。

以下两个参数可任意指定或不指定

CatMode(1,1)string="CanCat",返回值拼接选项,根据Function的返回值设定,必须为以下四者之一:

  • Scalar,Function的返回值为标量,将调用arrayfun完成拼接。
  • Linear,SplitDimensions为标量,且Function的返回值为类型、PackDimensions维度上尺寸均相同的数组。将调用cat完成拼接。
  • EsNlcs,Function的返回值为数值、逻辑、字符或字段相同的结构体数组,且尺寸完全相同。将调用cell2mat完成拼接。
  • CanCat,Function的返回值为数组,允许尺寸不同,但最终可以拼接成一整个大数组。将调用SuperCell2Mat完成拼接。
  • DontCat,不符合上述任何条件,或返回值为函数句柄。将不会拼接,返回元胞数组。

无论何种情况,都可以设为DontCat;其它选项都必须满足特定条件(对Function的每个返回值)。此外若Function的任何一个返回值是函数句柄,都只能选择DontCat。对于任何可拼接的情况,选择CanCat都能完成拼接,但性能最低。如果您确定您的函数返回值可以满足更苛刻的条件,应尽量优先选择Scalar>Linear>EsNlcs>CanCat。

Warning(1,1)logical=true,如果输入参数只有一个且为空,Function将不会被调用,因而无法获知返回值的数据类型,可能会与输入参数不为空的情况出现不一致的情形。该参数指定这种情况下是否要显示警告。

返回值

返回值为由Function的返回值按其所对应的参数在数组中的位置拼接成的数组。如果Function具有多个返回值,则每个返回值各自拼接成数组,作为本函数的多个返回值。根据CatMode不同:

  • Scalar,返回数组,尺寸与每个Arguments在SplitDimensions上隐式扩展后的尺寸相同,PackDimensions上尺寸为1
  • Linear | EsNlcs | CanCat,返回数组,该数组由返回值在SplitDimensions维度上的拼接得到
  • DontCat,返回元胞数组,尺寸与每个Arguments在SplitDimensions上隐式扩展后的尺寸相同,元胞里是对应位置的Arguments输入Function产生的返回值。PackDimensions上尺寸为1。

DistributeVararginByValidation

根据验证函数将输入的Varargin分发到输出变量

%%示例脚本
[A,B,C]=Sample(7,{4},"d")
%返回A="d",B=7,C={4}
[A,B,C]=Sample
%返回A="a",B=1,C={}
%%
function [A,B,C]=Sample(varargin)
%本函数需要将varargin解析为A, B, C三个参数,分别是字符串、数值和元胞,默认值分别为"a", 1, {}。但是允许调用方按照任意顺序输入这三个参数。
[A,B,C]=DistributeVararginByValidation(varargin,@isstring,@()"a",@isnumeric,@()1,@iscell,@(){});
%无论调用方使用何种顺序输入这三个参数,都将得到正确的A, B, C。如果调用方未提供某些参数,也将赋予默认值。
end

使用本函数让开发者能够允许调用方以任意顺序、可缺省地输入一系列类型不同的参数,分配到正确的变量中。

必需参数

Varargin(1,:)cell,调用方提供的varargin参数

重复参数

ValidationFun(1,1)function_handle,接受单一输入、输出逻辑标量的函数句柄,作为验证该参数的函数。若调用方提供的参数输入该函数返回true,则应用该参数;无论是返回false还是出错,都会将参数否决掉。

DefaultFun(1,1)function_handle,接受无输入、单一输出的函数句柄,用于取得该参数的默认值。如果缺少通过验证的某参数,将调用该函数取得默认值;如果有通过验证的参数,该函数将不会被调用。

返回值

varargout,按照重复参数重复的顺序排列输出实际得到的各个参数

FolderFun

取对一个文件夹下所有满足给定文件名模式的文件的绝对路径,对它们执行函数

%显示当前文件夹下所有文件
FolderFun(@disp);
%显示用户选取的文件夹下所有.mlx文件
All=FolderFun(@deal,uigetdir,Filename="*.mlx")

位置参数

Function(1,1)function_handle,必需,要执行的函数句柄。必须接受1个文件路径作为输入参数。 Directory(1,1)string="",可选,要遍历的文件夹路径,默认当前文件夹。如果不指定或设为空字符串,交给Function的路径参数将是相对于当前目录的相对路径;否则将是绝对路径。

名称值参数

Filename(1,1)string="*",要筛选出的文件名模式,默认所有文件

UniformOutput(1,1)logical=true,是否将输出值直接拼接成向量。若false,则将每个输出值套上一层元胞以后再拼接成向量。如果Function返回的不是标量,必须设为false。

返回值

每个文件路径执行函数后的返回值列向量。如果Function有多个返回值,则返回同样多个列向量,每个元素对应位置都是对一个文件调用Function产生的返回值。根据UniformOutput的设定,这些元素有可能还会套在一层元胞里。

ParseRepeatingFlagArguments

分析旗帜类重复参数到逻辑变量

function TiffBatchRegister(Flags)
arguments(Repeating)
	Flags(1,1)string{mustBeMember(Flags,["Silent","Sequential"])}
end
[Silent,Sequential]=ParseRepeatingFlagArguments([Flags{:}],["Silent","Sequential"]);
%得到这两个旗帜是否被调用方指定的逻辑值

输入参数

InputFlags(1,:)string,调用方传来的,待分析的旗帜类重复参数

ValidFlags(1,:)string,函数规定的有效旗帜

返回值

varargout(1,1)logical,数目与ValidFlags相同,返回每个有效旗帜是否存在(被调用方指定)的逻辑值

RepeatingFun

重复多次调用函数,为每个重复参数生成一个返回值

[One,Two,Three]=RepeatingFun(@zeros,1,2,3)
%{
One =

     0


Two =

     0     0
     0     0


Three =

     0     0     0
     0     0     0
     0     0     0
%}

输入参数

Function(1,1)function_handle,必需,要调用的函数句柄

Arguments,重复,每次调用的输入参数

返回值

varargout,每个重复输入的参数按顺序生成的返回值

Cite As

埃博拉酱 (2021). 埃博拉酱的 函数助手 Function Helpers (https://github.com/Silver-Fang/EbolaChansFunctionHelpers/releases/tag/v4.0.0), GitHub. Retrieved .

MATLAB Release Compatibility
Created with R2021a
Compatible with R2021a and later releases
Platform Compatibility
Windows macOS Linux
Tags Add Tags

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!

+EbolaChan/+FunctionHelpers/private

To view or report issues in this GitHub add-on, visit the GitHub Repository.
To view or report issues in this GitHub add-on, visit the GitHub Repository.