Skip to content

API Reference zh CN

Jump to bottom
weigao edited this page Jun 21, 2026 · 1 revision

API 参考

本页面提供 cfstream 的完整 API 参考。

它适合作为函数声明、参数、返回值、行为和注意事项的查询页面。

如果你想阅读教程式文档，请查看：

概览

cfstream 提供两个公开头文件：

头文件 语言 主要用途
cfs.hpp C++ 带有命名空间支持的 C++ 接口，并提供独立 C++ 文件流
cfs.h C 用于标准输入输出重定向的 C 接口

当前版本：

1.3.0

C++ API

C++ API 由以下头文件提供：

#include "cfs.hpp"

所有 C++ API 都位于 cfs 命名空间中。

namespace cfs {
    static std::ifstream cin;
    static std::ofstream cout;

    static inline const char* getversion();

    static inline void cfs(const char* input, const char* output);
    static inline void closecfs();

    static inline void cppfs(const char* input, const char* output);
    static inline void closecppfs();
}

cfs::getversion()

声明

static inline const char* cfs::getversion();

说明

返回当前 cfstream 版本。

参数

无。

返回值

类型 说明
const char* 当前 cfstream 版本字符串

对于版本 1.3.0，返回的字符串为：

1.3.0

行为

该函数不执行文件操作。

示例

#include <iostream>
#include "cfs.hpp"

int main() {
    std::cout << cfs::getversion() << '\n';
    return 0;
}

cfs::cfs()

声明

static inline void cfs::cfs(const char* input, const char* output);

说明

重定向标准输入和/或标准输出。

该函数类似于直接使用 freopen，但由 cfstream 进行封装。

参数

参数 类型 说明
input const char* 输入文件名。如果为 NULL，则不重定向输入。
output const char* 输出文件名。如果为 NULL，则不重定向输出。

在 C++11 或更高版本中，也可以使用 nullptr 代替 NULL。

返回值

无。

行为

在对应参数不为空时，该函数内部会使用：

std::freopen(input, "r", stdin);
std::freopen(output, "w", stdout);

重定向成功后，以下流或函数会受到影响：

std::cin
std::cout
scanf
printf

它们会使用重定向后的标准输入输出流。

注意事项

  • 传入 NULL 或 nullptr 表示对应的流不会被重定向。
  • 两个参数都传入 NULL 或 nullptr 是允许的，但没有实际意义。
  • 该函数不会打开 cfs::cin 或 cfs::cout。
  • 如需将标准流恢复到控制台，请使用 cfs::closecfs()。

示例

#include <iostream>
#include "cfs.hpp"

int main() {
    cfs::cfs("test.in", "test.out");

    int n;
    std::cin >> n;
    std::cout << n << '\n';

    cfs::closecfs();
    return 0;
}

cfs::closecfs()

声明

static inline void cfs::closecfs();

说明

结束由 cfs::cfs() 建立的文件重定向，并尝试将标准输入输出恢复到控制台。

参数

无。

返回值

无。

行为

该函数内部会将 stdin 和 stdout 重新定向到平台对应的控制台设备。

平台 控制台设备
Windows CON
Linux / macOS / 其他类 Unix 系统 /dev/tty

注意事项

  • 该函数不会永久关闭 std::cin 或 std::cout。
  • 它会将标准流重新定向回控制台设备。
  • 它不会影响 cfs::cin 或 cfs::cout。
  • 对于独立 C++ 文件流，请使用 cfs::closecppfs()。

示例

#include <iostream>
#include "cfs.hpp"

int main() {
    cfs::cfs("test.in", "test.out");

    int n;
    std::cin >> n;
    std::cout << n << '\n';

    cfs::closecfs();

    std::cout << "Back to console" << '\n';
    return 0;
}

cfs::cppfs()

声明

static inline void cfs::cppfs(const char* input, const char* output);

说明

打开独立的 C++ 文件流：

cfs::cin
cfs::cout

这两个文件流与标准流相互独立。

参数

参数 类型 说明
input const char* cfs::cin 使用的输入文件名
output const char* cfs::cout 使用的输出文件名

返回值

无。

行为

如果 cfs::cin 和 cfs::cout 都没有处于打开状态，该函数会打开：

cfs::cin.open(input);
cfs::cout.open(output);

如果 cfs::cin 或 cfs::cout 已经打开，该函数不会重新打开它们，并会向 std::cerr 输出错误信息：

Error-from-cfs Already open cppfs,please close first!

注意事项

  • cfs::cppfs() 不会重定向 std::cin 或 std::cout。
  • scanf 和 printf 不会受到影响。
  • 不要向 cfs::cppfs() 传入 NULL 或 nullptr。
  • 如果需要单边重定向，请使用 cfs::cfs()。
  • 再次调用 cfs::cppfs() 前，请先调用 cfs::closecppfs()。

示例

#include <iostream>
#include "cfs.hpp"

int main() {
    cfs::cppfs("test.in", "test.out");

    int n;
    cfs::cin >> n;
    cfs::cout << n << '\n';

    std::cout << "This goes to the console." << '\n';

    cfs::closecppfs();
    return 0;
}

cfs::closecppfs()

声明

static inline void cfs::closecppfs();

说明

关闭由 cfs::cppfs() 打开的独立 C++ 文件流。

参数

无。

返回值

无。

行为

该函数会检查文件流是否已经打开，并在需要时关闭它们：

if (cin.is_open()) cin.close();
if (cout.is_open()) cout.close();

注意事项

  • 该函数只影响 cfs::cin 和 cfs::cout。
  • 它不会影响 std::cin、std::cout、scanf 或 printf。
  • 调用 cfs::closecppfs() 后，除非再次调用 cfs::cppfs()，否则不要继续使用 cfs::cin 或 cfs::cout。

示例

#include "cfs.hpp"

int main() {
    cfs::cppfs("test.in", "test.out");

    int n;
    cfs::cin >> n;
    cfs::cout << n << '\n';

    cfs::closecppfs();
    return 0;
}

cfs::cin

声明

static std::ifstream cfs::cin;

说明

由 cfs::cppfs() 使用的输入文件流。

类型

std::ifstream

行为

调用：

cfs::cppfs("test.in", "test.out");

之后，cfs::cin 会从 test.in 读取数据。

注意事项

  • cfs::cin 独立于 std::cin。
  • 它只会被 cfs::cppfs() 打开。
  • 它会被 cfs::closecppfs() 关闭。
  • 因为它使用 static 声明，所以具有内部链接属性。

示例

int n;
cfs::cin >> n;

cfs::cout

声明

static std::ofstream cfs::cout;

说明

由 cfs::cppfs() 使用的输出文件流。

类型

std::ofstream

行为

调用：

cfs::cppfs("test.in", "test.out");

之后，cfs::cout 会写入 test.out。

注意事项

  • cfs::cout 独立于 std::cout。
  • 它只会被 cfs::cppfs() 打开。
  • 它会被 cfs::closecppfs() 关闭。
  • 因为它使用 static 声明，所以具有内部链接属性。

示例

cfs::cout << "Hello cfstream" << '\n';

C API

C API 由以下头文件提供：

#include "cfs.h"

C API 不使用命名空间。

static inline const char* cfs_getversion(void);

static inline void cfs(const char* input, const char* output);
static inline void closecfs(void);

cfs_getversion()

声明

static inline const char* cfs_getversion(void);

说明

返回当前 cfstream 版本。

参数

无。

返回值

类型 说明
const char* 当前 cfstream 版本字符串

对于版本 1.3.0，返回的字符串为：

1.3.0

行为

该函数不执行文件操作。

示例

#include "cfs.h"

int main(void) {
    printf("%s\n", cfs_getversion());
    return 0;
}

cfs()

声明

static inline void cfs(const char* input, const char* output);

说明

重定向标准输入和/或标准输出。

该函数类似于直接使用 freopen，但由 cfstream 进行封装。

参数

参数 类型 说明
input const char* 输入文件名。如果为 NULL，则不重定向输入。
output const char* 输出文件名。如果为 NULL，则不重定向输出。

返回值

无。

行为

在对应参数不为 NULL 时，该函数内部会使用：

freopen(input, "r", stdin);
freopen(output, "w", stdout);

重定向成功后，以下函数会受到影响：

scanf
printf

它们会使用重定向后的标准输入输出流。

注意事项

  • 传入 NULL 表示对应的流不会被重定向。
  • C 不支持 nullptr。
  • 两个参数都传入 NULL 是允许的，但没有实际意义。
  • 如需将标准流恢复到控制台，请使用 closecfs()。

示例

#include "cfs.h"

int main(void) {
    cfs("test.in", "test.out");

    int n;
    scanf("%d", &n);
    printf("%d\n", n);

    closecfs();
    return 0;
}

closecfs()

声明

static inline void closecfs(void);

说明

结束由 cfs() 建立的文件重定向，并尝试将标准输入输出恢复到控制台。

参数

无。

返回值

无。

行为

该函数内部会将 stdin 和 stdout 重新定向到平台对应的控制台设备。

平台 控制台设备
Windows CON
Linux / macOS / 其他类 Unix 系统 /dev/tty

注意事项

  • 该函数不会永久关闭 stdin 或 stdout。
  • 它会将标准流重新定向回控制台设备。
  • 在不再需要文件重定向时，应在 cfs() 之后调用它。

示例

#include "cfs.h"

int main(void) {
    cfs("test.in", "test.out");

    int n;
    scanf("%d", &n);
    printf("%d\n", n);

    closecfs();

    printf("Back to console\n");
    return 0;
}

参数规则

接口 参数 允许 NULL 允许 nullptr 说明
cfs::cfs input 是 C++11 或更高版本 如果为空，则不重定向输入
cfs::cfs output 是 C++11 或更高版本 如果为空，则不重定向输出
cfs input 是 否 C 不支持 nullptr
cfs output 是 否 C 不支持 nullptr
cfs::cppfs input 不推荐 不推荐 请使用有效文件名
cfs::cppfs output 不推荐 不推荐 请使用有效文件名

返回值

API 返回类型 含义
cfs::getversion() const char* 当前 cfstream 版本
cfs_getversion() const char* 当前 cfstream 版本
cfs::cfs() void 无返回值
cfs::closecfs() void 无返回值
cfs::cppfs() void 无返回值
cfs::closecppfs() void 无返回值
cfs() void 无返回值
closecfs() void 无返回值

错误行为

cfs::cppfs() 已经打开

如果在 cfs::cin 或 cfs::cout 已经打开时调用 cfs::cppfs()，它会向 std::cerr 输出以下信息：

Error-from-cfs Already open cppfs,please close first!

随后函数返回，不会重新打开文件流。

C 标准过旧

如果 cfs.h 以 C 语言方式编译，并且使用的标准低于 C99，编译会停止，并显示：

cfs.h requires C99 or later.

平台行为

closecfs() 和 cfs::closecfs() 会使用平台相关的控制台设备来恢复标准流。

平台 stdin 恢复目标 stdout 恢复目标
Windows CON CON
Linux / macOS / 其他类 Unix 系统 /dev/tty /dev/tty

链接属性说明

C++ 头文件

在 cfs.hpp 中，cfs::cin 和 cfs::cout 使用 static 声明。

这会让它们具有内部链接属性。

每个包含 cfs.hpp 的翻译单元都会拥有自己独立的一份：

cfs::cin
cfs::cout

C 头文件

在 cfs.h 中，函数使用 static inline 定义。

这允许该头文件被多个 C 源文件包含，而不会产生外部链接冲突。

当 cfs.h 被 C++ 代码包含时，C 接口会被包裹在 extern "C" 中。

另请参阅

cfstream Wiki

English

中文

Back to Repository

Clone this wiki locally