v7.3.0

将MATLAB.Containers.Queue分离出接口IQueue以便其它实现修复工具箱UUID错误导致无法正常更新的问题
Ebola-Chan-bot · Apr 8, 2022 · bcf905c · bcf905c
1 parent 5f88a85
commit bcf905c
Show file tree

Hide file tree

Showing 8 changed files with 190 additions and 82 deletions.
diff --git a/+MATLAB/+Containers/IQueue.m b/+MATLAB/+Containers/IQueue.m
@@ -0,0 +1,80 @@
+classdef(Abstract)IQueue<handle
+	% 表示对象的先进先出集合。
+	% IQueue是一个对象的流水线，对象被一个接一个插入队尾，然后按照插入的顺序一个接一个从队首取出，而不支持随机插入、取出中间的对象。
+	% 可以对 IQueue 及其元素执行三个主要操作：
+	% - Enqueue 将一个元素添加到队列的末尾。
+	% - Dequeue 从队列的开头移除最旧的元素。
+	% - Peek 返回位于队列开头的最旧元素，但不会将其从队列中删除。
+	events
+		%有元素被添加到队列中时引发此事件
+		DataEnqueued
+	end
+	methods(Abstract)
+		% 移除并返回位于 IQueue 开始处的对象。
+		% 此方法类似于 Peek 方法，但 Peek 不修改 IQueue。
+		% # 语法
+		% ```
+		% obj.Dequeue
+		% %移除队首的第1个对象
+		%
+		% obj.Dequeue(Number)
+		% %从队首开始移除多个对象
+		%
+		% Elements=obj.Dequeue(___)
+		% %返回被移除的对象，可以与上述任意语法组合使用
+		% ```
+		% 输入参数：Number，要移除的对象个数。
+		% 返回值：Elements(1,:)cell，被移除的对象，按照它们在队列中从头到尾的顺序，并用元胞包装。
+		% 提示：如果Number>obj.Count，将仅取出obj.Count个对象，而不产生错误。因此您可以指定Number为Inf以取出所有对象。
+		Elements=Dequeue(obj,Number)
+		% 将对象添加到 IQueue 的结尾处。
+		% # 语法
+		% ```
+		% obj.Enqueue(Element1,Element2,…)
+		% ```
+		% 输入参数：Element，要添加到 IQueue 的对象。重复输入此参数可以依次插入多个对象。
+		Enqueue(obj,varargin)
+	end
+	%某些方法的默认实现。子类可以重写成性能更高的实现。
+	methods
+		function C=Count(obj)
+			% 获取 Queue 中包含的元素数。
+			% 返回值：(1,1)double，IQueue 中包含的元素数。
+			C=numel(obj.ToArray);
+		end
+		function Clear(obj)
+			% 从 IQueue 中移除所有对象。
+			% 注意，此方法不会立即释放集合中的对象，也不会显式delete。对于必须立即释放的元素，您必须使用Dequeue取出然后手动释放。
+			obj.Dequeue(Inf);
+		end
+		function C=Contains(obj,varargin)
+			% 确定某些元素是否在 IQueue 中。
+			% # 语法
+			% ```
+			% C=obj.Contains(Element1,Element2,…)
+			% ```
+			% 输入参数：Element，要在队列中定位的对象。重复输入此参数可以一次性确定多个对象。
+			% 返回值：C(1,:)logical，按照Element的输入顺序返回每个Element是否存在的逻辑值。
+			C=MATLAB.Ops.IsMemberN(varargin,obj.ToArray,2);
+		end
+		function P=Peek(obj)
+			% 返回位于 IQueue 开始处的对象但不将其移除。
+			% 返回值：(1,:)cell。如果队列为空，返回空元胞{}；否则返回包装着队首元素的元胞标量。
+			P=obj.ToArray;
+			if ~isempty(P)
+				P=P(1);
+			end
+		end
+		function Array=ToArray(obj)
+			% 将 IQueue 元素复制到新数组。
+			% 返回值：(1,:)cell，包含从 IQueue 复制的元素的新数组，每个元素都用元胞包装。
+			Array=obj.Dequeue(Inf);
+			obj.Enqueue(Array{:});
+		end
+		function E=IsEmpty(obj)
+			% 检查队列是否为空
+			% 返回值：(1,1)logical，若队列为空，true；否则false
+			E=isempty(obj.Peek);
+		end
+	end
+end
diff --git a/+MATLAB/+Containers/Queue.m b/+MATLAB/+Containers/Queue.m
@@ -1,10 +1,5 @@
-classdef Queue<matlab.mixin.Copyable
-	% 表示对象的先进先出集合。
-	% Queue是一个对象的流水线，对象被一个接一个插入队尾，然后按照插入的顺序一个接一个从队首取出，而不支持随机插入、取出中间的对象。
-	% 可以对 Queue 及其元素执行三个主要操作：
-	% - Enqueue 将一个元素添加到队列的末尾。
-	% - Dequeue 从队列的开头移除最旧的元素。
-	% - Peek 返回位于队列开头的最旧元素，但不会将其从队列中删除。
+classdef Queue<matlab.mixin.Copyable&MATLAB.Containers.IQueue
+	%MALTAB.Containers.IQueue的简单基本实现
 	properties(Access=private)
 		Data
 		Head=0
@@ -38,43 +33,16 @@
 			obj.Tail=obj.Capacity-1;
 		end
 		function C=Count(obj)
-			% 获取 Queue 中包含的元素数。
-			% 返回值：(1,1)double，Queue 中包含的元素数。
 			C=mod(obj.Tail-obj.Head,obj.Capacity);
 		end
 		function Clear(obj)
-			% 从 Queue 中移除所有对象。
-			% 注意，此方法不会立即释放集合中的对象，也不会显式delete。对于必须立即释放的元素，您必须使用Dequeue取出然后手动释放。
 			obj.Head=obj.Tail;
 			obj.Data=cell(1,obj.Capacity);
 		end
 		function C=Contains(obj,varargin)
-			% 确定某些元素是否在 Queue 中。
-			% # 语法
-			% ```
-			% C=obj.Contains(Element1,Element2,…)
-			% ```
-			% 输入参数：Element，要在队列中定位的对象。重复输入此参数可以一次性确定多个对象。
-			% 返回值：C(1,:)logical，按照Element的输入顺序返回每个Element是否存在的逻辑值。
 			C=MATLAB.Ops.IsMemberN(varargin,obj.Data(obj.TraverseIndex),2);
 		end
 		function Elements=Dequeue(obj,Number)
-			% 移除并返回位于 Queue 开始处的对象。
-			% 此方法类似于 Peek 方法，但 Peek 不修改 Queue。
-			% # 语法
-			% ```
-			% obj.Dequeue
-			% %移除队首的第1个对象
-			%
-			% obj.Dequeue(Number)
-			% %从队首开始移除多个对象
-			%
-			% Elements=obj.Dequeue(___)
-			% %返回被移除的对象，可以与上述任意语法组合使用
-			% ```
-			% 输入参数：Number，要移除的对象个数。
-			% 返回值：Elements(1,:)cell，被移除的对象，按照它们在队列中从头到尾的顺序，并用元胞包装。
-			% 提示：如果Number>obj.Count，将仅取出obj.Count个对象，而不产生错误。因此您可以指定Number为Inf以取出所有对象。
 			arguments
 				obj
 				Number=1
@@ -88,12 +56,6 @@ function Clear(obj)
 			obj.Head=NewHead;
 		end
 		function Enqueue(obj,varargin)
-			% 将对象添加到 Queue 的结尾处。
-			% # 语法
-			% ```
-			% obj.Enqueue(Element1,Element2,…)
-			% ```
-			% 输入参数：Element，要添加到 Queue 的对象。重复输入此参数可以依次插入多个对象。
 			NumAdd=numel(varargin);
 			NeedCapacity=obj.Count+NumAdd+1;
 			if NeedCapacity>obj.Capacity
@@ -114,20 +76,22 @@ function Enqueue(obj,varargin)
 				obj.Data(obj.Tail+1:NewTail)=varargin;
 			end
 			obj.Tail=NewTail;
+			if NumAdd
+				notify(obj,'DataEnqueued');
+			end
 		end
 		function Data=Peek(obj)
-			% 返回位于 Queue 开始处的对象但不将其移除。
-			% 返回值：(1,:)cell。如果队列为空，返回空元胞{}；否则返回包装着队首元素的元胞标量。
-			if obj.Head==obj.Tail
+			if obj.Empty
 				Data={};
 			else
 				Data=obj.Data(obj.Head+1);
 			end
 		end
 		function Array=ToArray(obj)
-			% 将 Queue 元素复制到新数组。
-			% 返回值：(1,:)cell，包含从 Queue 复制的元素的新数组，每个元素都用元胞包装。
 			Array=obj.Data(obj.TraverseIndex);
 		end
+		function E=IsEmpty(obj)
+			E=obj.Head==obj.Tail;
+		end
 	end
 end
diff --git a/+MATLAB/Version.m b/+MATLAB/Version.m
@@ -1,4 +1,4 @@
 function V = Version
-V.Me='7.2.0';
+V.Me='7.3.0';
 V.Win32API=Win32API.Version;
 V.MATLAB='R2022a';
diff --git a/README.md b/README.md
@@ -10,7 +10,8 @@
 	- [+AudioVideo](#AudioVideo)
 		- [VideoPreview](#VideoPreview) 生成一张图片作为视频文件的预览
 	- [+Containers](#Containers)
-		- [@Queue](#Queue) 表示对象的先进先出集合。
+		- [@IQueue](#IQueue) 一个接口，表示对象的先进先出集合。
+		- [@Queue](#Queue) IQueue的简单基本实现
 	- [+DataFun](#DataFun)
 		- [FindGroupsN](#FindGroupsN) 内置findgroups的升级版，支持任意数组类型，并可以指定拆分维度，missing类值视为相等的有效数据
 		- [MaxSubs](#MaxSubs) 返回数组的最大值以及所在的坐标。
@@ -127,46 +128,31 @@ PreviewOption(1,1)MATLAB.AudioVideo.PreviewOptions=MATLAB.AudioVideo.PreviewOpti
 
 Preview(:,:)，预览图
 ## +Containers
-### @Queue
-表示对象的先进先出集合。
+### @IQueue
+一个接口，表示对象的先进先出集合。
 
-Queue是一个对象的流水线，对象被一个接一个插入队尾，然后按照插入的顺序一个接一个从队首取出，而不支持随机插入、取出中间的对象。可以对 Queue 及其元素执行三个主要操作：
+IQueue是一个对象的流水线，对象被一个接一个插入队尾，然后按照插入的顺序一个接一个从队首取出，而不支持随机插入、取出中间的对象。可以对 IQueue 及其元素执行三个主要操作：
 - Enqueue 将一个元素添加到队列的末尾。
 - Dequeue 从队列的开头移除最旧的元素。
 - Peek 返回位于队列开头的最旧元素，但不会将其从队列中删除。
 
-**构造函数**
-
-初始化 Queue 类的新实例。
-
-*语法*
-```MATLAB
-import MATLAB.Containers.Queue
-obj=Queue
-%初始化 Queue 类的新实例，该实例为空
-
-obj=Queue(Element1,Element2,…)
-%初始化 Queue 类的新实例，该实例从头到尾包含指定顺序的多个元素。
-```
-输入参数：Element，要放入队列的初始元素。重复输入此参数，以从头到尾排列多个元素。
-
 **成员方法**
 
 *Count*
 
-获取 Queue 中包含的元素数。
+获取 IQueue 中包含的元素数。
 
-返回值：(1,1)double，Queue 中包含的元素数。
+返回值：(1,1)double，IQueue 中包含的元素数。
 
 *Clear*
 
-从 Queue 中移除所有对象。
+从 IQueue 中移除所有对象。
 
 注意，此方法不会立即释放集合中的对象，也不会显式delete。对于必须立即释放的元素，您必须使用Dequeue取出然后手动释放。
 
 *Contains*
 
-确定某些元素是否在 Queue 中。
+确定某些元素是否在 IQueue 中。
 
 语法
 ```MATLAB
@@ -178,9 +164,9 @@ C=obj.Contains(Element1,Element2,…)
 
 *Dequeue*
 
-移除并返回位于 Queue 开始处的对象。
+移除并返回位于 IQueue 开始处的对象。
 
-此方法类似于 Peek 方法，但 Peek 不修改 Queue。
+此方法类似于 Peek 方法，但 Peek 不修改 IQueue。
 
 语法
 ``` MATLAB
@@ -201,25 +187,52 @@ Elements=obj.Dequeue(___)
 
 *Enqueue*
 
-将对象添加到 Queue 的结尾处。
+将对象添加到 IQueue 的结尾处。
 
 语法
 ```MATLAB
 obj.Enqueue(Element1,Element2,…)
 ```
-输入参数：Element，要添加到 Queue 的对象。重复输入此参数可以依次插入多个对象。
+输入参数：Element，要添加到 IQueue 的对象。重复输入此参数可以依次插入多个对象。
+
+*IsEmpty*
+
+检查队列是否为空
+
+返回值：(1,1)logical，若队列为空，true；否则false
 
 *Peek*
 
-返回位于 Queue 开始处的对象但不将其移除。
+返回位于 IQueue 开始处的对象但不将其移除。
 
 返回值：(1,:)cell。如果队列为空，返回空元胞{}；否则返回包装着队首元素的元胞标量。
 
 *ToArray*
 
-将 Queue 元素复制到新数组。
+将 IQueue 元素复制到新数组。
+
+返回值：(1,:)cell，包含从 IQueue 复制的元素的新数组，每个元素都用元胞包装。
+### @Queue
+IQueue的简单基本实现
+
+**构造函数**
+
+初始化 Queue 类的新实例。
+
+*语法*
+```MATLAB
+import MATLAB.Containers.Queue
+obj=Queue
+%初始化 Queue 类的新实例，该实例为空
+
+obj=Queue(Element1,Element2,…)
+%初始化 Queue 类的新实例，该实例从头到尾包含指定顺序的多个元素。
+```
+输入参数：Element，要放入队列的初始元素。重复输入此参数，以从头到尾排列多个元素。
+
+**成员方法**
 
-返回值：(1,:)cell，包含从 Queue 复制的元素的新数组，每个元素都用元胞包装。
+本类成员方法与IQueue接口类完全相同，请参见[@IQueue](#IQueue)文档
 ## +DataFun
 ### FindGroupsN
 内置findgroups的升级版，支持任意数组类型，并可以指定拆分维度，missing类值视为相等的有效数据

diff --git a/resources/functionSignatures.json b/resources/functionSignatures.json
@@ -85,6 +85,48 @@
 			}
 		]
 	},
+	"MATLAB.Containers.IQueue.Contains":{
+		"inputs":[
+			{
+				"name":"obj",
+				"kind":"required"
+			},
+			{
+				"name":"Element",
+				"kind":"ordered",
+				"purpose":"要在队列中查找的对象",
+				"repeating":true
+			}
+		]
+	},
+	"MATLAB.Containers.IQueue.Dequeue":{
+		"inputs":[
+			{
+				"name":"obj",
+				"kind":"required"
+			},
+			{
+				"name":"Number",
+				"kind":"ordered",
+				"type":["real","scalar"],
+				"purpose":"要移除的对象个数。"
+			}
+		]
+	},
+	"MATLAB.Containers.IQueue.Enqueue":{
+		"inputs":[
+			{
+				"name":"obj",
+				"kind":"required"
+			},
+			{
+				"name":"Element",
+				"kind":"required",
+				"purpose":"要添加到 Queue 的对象",
+				"repeating":true
+			}
+		]
+	},
 	"MATLAB.Containers.Queue":{
 		"inputs:":[
 			{
@@ -99,7 +141,7 @@
 		"inputs":[
 			{
 				"name":"obj",
-				"kind":"required",
+				"kind":"required"
 			},
 			{
 				"name":"Element",
@@ -113,7 +155,7 @@
 		"inputs":[
 			{
 				"name":"obj",
-				"kind":"required",
+				"kind":"required"
 			},
 			{
 				"name":"Number",
@@ -127,7 +169,7 @@
 		"inputs":[
 			{
 				"name":"obj",
-				"kind":"required",
+				"kind":"required"
 			},
 			{
 				"name":"Element",