prg_gdf_read()
摘要
读取 ASCII 文件的内容,并将文件内容作为字符串列表返回。
语法
prg_gdf_read (file_name)
| 参数 | 类型 | 说明 |
|---|---|---|
file_name |
char* |
要读取的文件名。 如果该参数只给出文件名(没有路径或后缀),它必须匹配模型目录中某个通用数据文件( .gdf 后缀)的名称。如果该参数以绝对路径名给出,则可以是任何 ASCII 文件(如通用数据文件或逗号分隔值文件)。 |
返回类型
Prg_List*
指向一个字符串列表的指针,列表中的每个字符串对应从指定文件读出的一行。文件的每一行都被复制到返回列表中的一个字符串中。如果文件无法打开,则返回符号常量 PRGC_NIL。
头文件
prg_file_funcs.h
示例
Prg_List*
arp_sup_table_load (file_name)
{
Prg_List* line_list_ptr;
char err_str [256]
/* Read in an address-map table from an ASCII */
/* file adhering to the format defined above. */
FIN (arp_sup_table_load (file_name))
/* Open and read the file into the list. */
line_list_ptr = prg_gdf_read (file_name);
/* Test for error in reading. */
if (line_list_ptr == PRGC_NIL)
{
sprintf (err_str, "File Name: %s", file_name);
op_sim_end ("Package: arp_sup", <...>
详情
该函数在模型目录中查找指定的 ASCII 文件,可能是:
- 通用数据文件(
.gdf后缀),当只指定文件名时 - 任何 ASCII 文件(
.gdf、.csv或其他后缀),当指定完整路径名和后缀时
该函数在读取之前打开 ASCII 文件,读取之后关闭文件,从而提供一体化的文件操作。调用该函数不会对文件产生破坏或修改的影响。文件内容以字符串列表的形式返回,文件的开头对应列表的头部,文件的结尾对应列表的尾部。列表在该函数内部创建,之后可以使用 prg_list_free() 清除。
对文件内容执行以下几项处理:
- 空行(仅由空白字符组成)不会被放入列表
- 第一列以井号 (#) 开头的注释行不会被放入列表
- 每行开头的空白字符会被去除
用途
提供了一种从文件读入 ASCII 文本信息的机制,从而避免直接使用标准 I/O 函数(如 fopen()、fread() 和 fclose())。这对于需要从文件加载表格信息(如路由表)的过程特别有用。在一次函数调用中,文件被定位并打开,内容被读出并组织成列表,不感兴趣的行被跳过,文件被关闭。返回的列表随后可以使用 prg_list_access() 或 prg_list_remove() 方便地操作。
prg_tfile_generic_data_file_read() 函数扩展了 prg_gdf_read() 的功能,还支持通用设置文件(.gsf),并允许将返回的字符串追加到指定列表。
错误
- 程序中止:Segmentation Violation(段违例)。(由于无效的 file_name 参数)
- 程序中止:内存分配失败。
- 可恢复错误:无法打开文件 (<file_name>) 进行读取
- 可恢复错误:无法为从 (<file_name>) 读取分配足够的内存。
参考
- 使用 prg_list_free() 释放该函数返回列表的内容所占内存
- 使用 prg_mem_free() 释放该函数分配的列表结构内存
- 使用 prg_list_access() 获取指向该函数返回列表中某一行的指针
- 使用 prg_list_remove() 从该函数返回列表中移除某一行(并获得指向它的指针)
- 使用 prg_str_decomp() 将文件的一行分解为一系列字段字符串