matlab.io.datastore.DsFileSet 类

命名空间: matlab.io.datastore

数据存储中文件集合的文件集对象

描述

DsFileSet 对象可帮助您管理对大型文件集合的迭代处理。可将 DsFileSet 对象和 DsFileReader 对象结合使用，来管理和读取数据存储中的文件。

构造

fs = matlab.io.datastore.DsFileSet(location) 根据指定的 location 返回文件集合的 DsFileSet 对象。

fs = matlab.io.datastore.DsFileSet(location,Name,Value) 使用一个或多个名称-值对组参量指定 DsFileSet 对象的其他参数。Name 也可以是属性名称，而 Value 是相应的值。Name 必须放在单引号 ('') 内。您可采用任意顺序指定多个名称-值对组参量，例如 Name1,Value1,...,NameN,ValueN。

输入参量

全部展开

`location` — 要包括的文件或文件夹
字符向量 | 字符向量元胞数组 | 字符串 | 结构体

要包括在文件集对象中的文件或文件夹，指定为字符向量、字符向量元胞数组、字符串或结构体。如果这些文件不在当前文件夹中，则 location 必须是完整或相对路径。指定文件夹的子文件夹中的文件不会自动包括在文件集对象中。

通常，对于 Hadoop^® 工作流来说，如果您将 location 指定为结构体，则它必须包含 FileName、Offset 和 Size 字段。此要求使您可以将 location 参量直接用于 matlab.io.datastore.HadoopLocationBased 类的 initializeDatastore 方法。有关示例，请参阅Add Support for Hadoop。

指定 location 时可以使用通配符 (*)。指定此字符会将所有匹配的文件或者匹配文件夹中的所有文件都包括在文件集对象中。

如果文件在本地不可用，则文件或文件夹的完整路径必须为统一资源定位器 (URL)，例如
hdfs://hostname:portnumber/path_to_file。

数据类型: char | cell | string | struct

名称-值参数

将可选的参量对组指定为 Name1=Value1,...,NameN=ValueN，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但参量对组的顺序无关紧要。

在 R2021a 之前，使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例: 'FileExtensions',{'.jpg','.tif'} 将具有 .jpg 或 .tif 扩展名的所有文件都包括在 FileSet 对象中。

`FileExtensions` — 文件扩展名
字符向量 | 字符向量元胞数组 | 字符串

文件扩展名，以逗号分隔的对组形式指定，该对组由 'FileExtensions' 和一个字符向量、字符向量元胞数组或字符串组成。可以使用空引号 '' 表示不带扩展名的文件。

如果未指定 'FileExtensions'，则 DsFileSet 自动包含所有文件扩展名。

示例: 'FileExtensions','.jpg'

示例: 'FileExtensions',{'.txt','.csv'}

数据类型: char | cell | string

`IncludeSubfolders` — 子文件夹包含标记
`false` (默认) | `true`

子文件夹包含标记，以逗号分隔的对组形式指定，该对组由 'IncludeSubfolders' 和 true 或 false 组成。指定 true 可包含每个文件夹中的所有文件和子文件夹，指定 false 则仅包含每个文件夹中的文件。

示例: 'IncludeSubfolders',true

数据类型: logical | double

`AlternateFileSystemRoots` — 备用文件系统根路径
字符串向量 | 元胞数组

备用文件系统根路径，以名称-值参量形式指定，其中包含 "AlternateFileSystemRoots" 和一个字符串向量或元胞数组。当您在本地计算机上创建数据存储，但需要访问和处理另一台计算机（可能是不同操作系统）上的数据时，请使用 "AlternateFileSystemRoots"。此外，如果您使用 Parallel Computing Toolbox™ 和 MATLAB^® Parallel Server™ 处理数据，而数据存储在本地计算机上并且在不同平台云或集群计算机上存储数据副本，则必须使用 "AlternateFileSystemRoots" 关联根路径。

要关联一组等效的根路径，请将 "AlternateFileSystemRoots" 指定为字符串向量。例如，
```
["Z:\datasets","/mynetwork/datasets"]
```
要将在数据存储方面等效的多组根路径关联起来，请将 "AlternateFileSystemRoots" 指定为包含多个行的元胞数组，其中每一行代表一组等效的根路径。将元胞数组中的每一行指定为一个字符串向量或字符向量元胞数组。例如：
- 将 "AlternateFileSystemRoots" 指定为字符串向量元胞数组。
```
{["Z:\datasets", "/mynetwork/datasets"];...
 ["Y:\datasets", "/mynetwork2/datasets","S:\datasets"]}
```
- 也可以将 "AlternateFileSystemRoots" 指定为字符向量元胞数组。
```
{{'Z:\datasets','/mynetwork/datasets'};...
 {'Y:\datasets', '/mynetwork2/datasets','S:\datasets'}}
```

"AlternateFileSystemRoots" 的值必须满足以下条件：

包含一行或多行，每一行指定一组等效的根路径。
每一行指定多个根路径，每个根路径必须至少包含两个字符。
根路径是唯一的，并且不是彼此的子文件夹。
包含至少一个指向文件位置的根路径条目。

有关详细信息，请参阅Set Up Datastore for Processing on Different Machines or Clusters。

示例: ["Z:\datasets","/mynetwork/datasets"]

数据类型: string | cell

属性

全部展开

`NumFiles` — 文件数
数值标量

此属性为只读。

文件集对象中的文件数，指定为数值标量。

示例: fs.NumFiles

数据类型: double

`FileSplitSize` — 拆分大小
`'file'` (默认) | 数值标量

此属性为只读。

拆分大小，指定为 'file' 或数值标量。

赋给 FileSplitSize 的值决定 nextfile 方法的输出。

如果 FileSplitSize 为 'file'，则 nextfile 方法返回一个表，其中包含 FileName、FileSize、Offset 和 SplitSize。SplitSize 的值设置为等于 FileSize。
如果 FileSplitSize 为数值标量 n，则 nextfile 方法返回 FileName、FileSize、Offset 和 SplitSize。SplitSize 的值设置为等于 FileSplitSize。此信息用于读取文件的 n 个字节。对 nextfile 方法的后续调用将返回信息以帮助读取同一文件接下来的 n 个字节，直到该文件末尾。

示例: 'FileSplitSize',20

数据类型: double | char

方法

`hasfile`	确定文件集对象中是否还有更多文件
`maxpartitions`	最大分区数
`nextfile`	下一个文件或文件块的信息
`partition`	划分文件集对象
`subset`	创建数据存储或 FileSet 的子集
`reset`	重置文件集对象
`resolve`	文件集对象中所有文件的信息

示例

全部折叠

获取文件集合的文件信息

创建一个文件集对象，一次获取一个文件的信息，或者获取文件集对象中所有文件的信息。

为 demos 文件夹中的所有 .mat 文件创建一个文件集对象。

folder = fullfile(matlabroot,'toolbox','matlab','demos');
fs = matlab.io.datastore.DsFileSet(folder,...
                 'IncludeSubfolders',true,...
                 'FileExtensions','.mat');

获取文件集对象中的第一个和第二个文件的信息。

fTable1 = nextfile(fs) ; % first file 
fTable2 = nextfile(fs) ; % second file

通过一次获取一个文件的信息并将信息收集到一个表中，从而获取所有文件的信息。

ft = cell(fs.NumFiles,1); % using cell for efficiency
i = 1;
reset(fs); % reset to the beginning of the fileset
while hasfile(fs)                 
    ft{i} = nextfile(fs);
    i = i + 1;
end
allFiles = vertcat(ft{:});

或者，同时获取所有文件的信息。

allfiles = resolve(fs);

提示

如果您使用 DsFileSet 对象作为自定义数据存储的属性，则需要实现 copyElement 方法。实现 copyElement 方法可以创建数据存储对象的深拷贝。有关详细信息，请参阅Customize Copy Operation。有关 copyElement 方法的示例实现，请参阅Develop Custom Datastore。