C语言CommonFunction有哪些常用函数？

这个术语并不是 C 语言标准中的一个官方分类，但它通常指的是那些在多个项目、多个模块中被广泛复用、具有通用功能的函数集合，创建和维护一个通用的函数库是优秀 C 语言编程实践的核心之一，它能极大地提高开发效率、保证代码质量并降低维护成本。

下面我将从几个方面来解释通用函数：

1. 为什么需要通用函数？
2. 通用函数通常包含哪些内容？
3. 如何组织和创建通用函数库？
4. 一个简单的通用函数库示例
5. 进阶实践

为什么需要通用函数？

• 代码复用: 避免在多个文件中重复编写相同的代码逻辑，一个安全的字符串拷贝函数，应该在整个项目中统一使用，而不是每个人都自己实现一个。
• 提高效率: 开发者无需“重新发明轮子”，可以直接调用经过验证的通用函数，专注于业务逻辑的开发。
• 保证一致性: 当通用函数被统一使用时，可以确保所有模块在处理相同任务时行为一致，统一的日志格式、统一的错误处理方式。
• 降低维护成本: 如果需要修复一个通用函数中的 bug 或优化其性能，只需要修改一处，所有调用该函数的地方都会受益，反之，如果代码散落在各处，修复将是一场噩梦。
• 增强可读性: 使用具有明确意义的函数名（如 SafeStrcpy）可以使代码更易读，比直接使用复杂的 strncpy 并处理其返回值要清晰得多。

通用函数通常包含哪些内容？

一个通用的函数库通常包含以下几类功能：

a. 内存操作

这类函数是对标准库 memory.h (或 string.h) 中函数的封装或增强，提供更安全的版本。

• 安全的内存拷贝: SafeMemcpy(dest, src, size)，确保目标缓冲区足够大，防止缓冲区溢出。
• 安全的内存设置: SafeMemset(dest, value, size)，同样用于防止越界。
• 内存分配检查: Malloc(size)，封装 malloc，在分配失败时直接退出程序或返回错误码，避免 NULL 指针的麻烦。

b. 字符串操作

这类函数是对标准库 string.h 中函数的封装或增强。

• 安全的字符串拷贝: SafeStrcpy(dest, src, dest_size)，比 strcpy 安全，因为它会限制拷贝长度，防止溢出。strncpy 并不完全安全，因为它不会自动在末尾添加 '\0'。
• 安全的字符串连接: SafeStrcat(dest, src, dest_size)，防止连接后的字符串超出目标缓冲区大小。
• 字符串比较: ICompareStr(str1, str2)，实现不区分大小写的字符串比较。
• 字符串去除空白: TrimStr(str)，去除字符串首尾的空白字符（空格、制表符、换行符等）。

c. 输入/输出 操作

• 安全的文件读取: ReadFileSafely(filename, buffer, buffer_size)，封装文件打开、读取、关闭操作，并进行错误检查。
• 格式化输出到文件: FprintfLog(file, format, ...)，一个带有错误检查的 fprintf 封装。

d. 通用工具函数

• 错误处理: LogError(message, ...)，一个统一的日志打印函数，可以包含时间戳、错误码等信息，并输出到标准错误或日志文件。
• 数字转字符串: IntToString(int num, char *str)，将整数转换为字符串。
• 字符串转数字: StringToInt(const char *str)，将字符串转换为整数，并进行错误检查。
• 延迟/休眠: Msleep(int milliseconds)，跨平台的毫秒级延迟函数（在 Windows 上用 Sleep，在 Linux 上用 nanosleep）。

如何组织和创建通用函数库？

通用函数库会以 静态库 或 动态库 的形式提供。

步骤 1：创建源文件和头文件

假设我们创建一个名为 commonlib 的通用库。

• commonlib.h (头文件): 声明所有通用函数，这是库的“接口”。
• commonlib.c (源文件): 实现所有通用函数。

步骤 2：编写代码

在 commonlib.h 中声明函数，在 commonlib.c 中实现。

步骤 3：编译成库

使用 C 编译器（如 GCC）将 .c 文件编译成库文件。

• 静态库: 以 .a (Linux) 或 .lib (Windows) 为后缀。

  # 生成目标文件
  gcc -c commonlib.c -o commonlib.o
  # 创建静态库
  ar rcs libcommonlib.a commonlib.o

• 动态库: 以 .so (Linux) 或 .dll (Windows) 为后缀。

  # 生成动态库
  gcc -shared -fPIC -o libcommonlib.so commonlib.c

步骤 4：在项目中使用库

在其他 C 项目中，通过包含头文件和链接库来使用这些函数。

#include "commonlib.h" // 包含头文件
int main() {
    char dest[20];
    const char *src = "Hello, Common Library!";
    SafeStrcpy(dest, src, sizeof(dest));
    printf("Copied string: %s\n", dest);
    LogError("This is an error message.");
    return 0;
}

编译时需要链接库：

gcc main.c -L. -lcommonlib -o my_program

• -L.: 告诉编译器在当前目录下查找库文件。
• -lcommonlib: 告诉编译器链接名为 libcommonlib 的库（会自动加上 lib 前缀和适当的后缀）。

一个简单的通用函数库示例

下面是一个简单的 commonlib 实现，包含一个安全的字符串拷贝和一个日志函数。

commonlib.h

#ifndef COMMONLIB_H
#define COMMONLIB_H
#include <stdio.h>
#include <stdarg.h>
#include <string.h>
#include <time.h>
#include <errno.h>
/**
 * @brief 安全的字符串拷贝函数
 * @param dest 目标缓冲区
 * @param src 源字符串
 * @param dest_size 目标缓冲区的总大小
 * @return void
 */
void SafeStrcpy(char *dest, const char *src, size_t dest_size);
/**
 * @brief 带时间戳的日志打印函数
 * @param format 格式化字符串
 * @param ... 可变参数
 * @return void
 */
void LogError(const char *format, ...);
#endif // COMMONLIB_H

commonlib.c

#include "commonlib.h"
#include <stdio.h>
void SafeStrcpy(char *dest, const char *src, size_t dest_size) {
    if (dest == NULL || src == NULL || dest_size == 0) {
        return; // 无效参数，直接返回
    }
    // strnpy 会拷贝最多 dest_size - 1 个字符，并在末尾添加 '\0'
    strncpy(dest, src, dest_size - 1);
    // 确保字符串以 '\0' 
    dest[dest_size - 1] = '\0';
}
void LogError(const char *format, ...) {
    time_t now;
    time(&now);
    char *time_str = ctime(&now);
    // ctime 返回的字符串包含换行符，我们去掉它
    time_str[strlen(time_str) - 1] = '\0';
    va_list args;
    va_start(args, format);
    fprintf(stderr, "[ERROR][%s] ", time_str);
    vfprintf(stderr, format, args);
    fprintf(stderr, " (errno: %d - %s)\n", errno, strerror(errno));
    va_end(args);
}

main.c (使用示例)

#include "commonlib.h"
#include <stdio.h>
int main() {
    char buffer[10];
    // 这个调用是安全的，不会溢出
    SafeStrcpy(buffer, "Hello", sizeof(buffer));
    printf("Buffer 1: %s\n", buffer); // 输出: Buffer 1: Hello
    // 这个调用会截断字符串，但保证安全
    SafeStrcpy(buffer, "This is a very long string", sizeof(buffer));
    printf("Buffer 2: %s\n", buffer); // 输出: Buffer 2: This is a
    // 模拟一个错误
    FILE *fp = fopen("non_existent_file.txt", "r");
    if (fp == NULL) {
        LogError("Failed to open file.");
    }
    return 0;
}

进阶实践

• 使用构建工具: 对于大型项目，手动编译库非常繁琐，应使用 Makefile、CMake 或 Autotools 等构建工具来自动化编译和链接过程。
• 跨平台封装: 对于像 Msleep 这样的函数，可以使用宏或条件编译来区分不同操作系统，提供统一的接口。

  // commonlib.h
  #ifdef _WIN32
      #include <windows.h>
      #define Msleep(ms) Sleep(ms)
  #else
      #include <unistd.h>
      #define Msleep(ms) usleep((ms) * 1000)
  #endif

• 单元测试: 为通用函数库编写单元测试（例如使用 assert 宏或专门的测试框架如 Check），确保每个函数在各种边界条件下都能正确工作。
• 遵循编码规范: 为通用函数库制定并遵循统一的命名规范、注释风格和代码风格，使其易于阅读和维护。

"Common Function" 是 C 语言工程化思想的体现，通过构建自己的通用函数库，可以逐步沉淀项目经验，打造出更健壮、更高效、更易于维护的软件系统。