标准工具函数子系统（CategoryStdinc）

SDL 提供了一套自研的核心 C 运行时函数实现，旨在解决跨平台开发中 C 标准库的兼容性问题：

1. 解耦运行时依赖：应用可直接使用这些函数，无需依赖特定的 C 运行时库（甚至无需任何 C 运行时）；
2. 跨平台行为一致：避免不同平台的 C 函数表现差异（如 Windows/Linux 下 snprintf() 行为不同、itoa() 仅存在于部分平台）；
3. 性能与兼容性兼顾：对于 SDL_memcpy 等高频函数，SDL 会在底层调用平台原生实现（若其更高效且稳定），既减少库体积又保证性能；
4. 扩展增强功能：补充了 C 标准未定义但实用的功能（如 SDL_crc32 校验、SDL_strlcpy 安全字符串拷贝）。

函数

1. 内存管理函数

• SDL_malloc：内存分配（替代标准 malloc，跨平台行为一致）
• SDL_calloc：分配并清零内存（替代标准 calloc）
• SDL_realloc：内存重分配（替代标准 realloc）
• SDL_free：释放内存（替代标准 free，需与 SDL 分配函数配对使用）
• SDL_aligned_alloc：按指定对齐方式分配内存（如 16 字节对齐）
• SDL_aligned_free：释放对齐分配的内存
• SDL_GetNumAllocations：获取当前 SDL 分配的内存块数量（调试内存泄漏）
• SDL_GetMemoryFunctions：获取当前使用的内存分配函数指针
• SDL_SetMemoryFunctions：自定义 SDL 的内存分配函数（如接入自定义内存池）
• SDL_GetOriginalMemoryFunctions：获取 SDL 原生的内存函数指针

2. 字符串操作函数

• SDL_strlen：计算字符串长度（替代 strlen，仅统计 ASCII 字符）
• SDL_utf8strlen：计算 UTF-8 字符串的字符数（而非字节数）
• SDL_strlcpy：安全字符串拷贝（防止缓冲区溢出，替代 strcpy）
• SDL_strlcat：安全字符串拼接（替代 strcat）
• SDL_strcmp/SDL_strncmp：字符串比较（区分大小写）
• SDL_strcasecmp/SDL_strncasecmp：字符串比较（不区分大小写）
• SDL_strchr/SDL_strrchr：查找字符在字符串中的位置
• SDL_strstr/SDL_strnstr：查找子字符串
• SDL_strdup/SDL_strndup：字符串拷贝（自动分配内存）
• SDL_strtok_r：可重入的字符串分割（替代 strtok，线程安全）
• SDL_itoa/SDL_ltoa/SDL_lltoa：整数转字符串（跨平台兼容，标准库无统一实现）
• SDL_uitoa/SDL_ultoa/SDL_ulltoa：无符号整数转字符串
• SDL_atof/SDL_atoi：字符串转数值（替代 atof/atoi）
• SDL_strtod/SDL_strtol/SDL_strtoll：字符串转数值（带错误处理）
• SDL_strtoul/SDL_strtoull：字符串转无符号数值
• SDL_asprintf/SDL_vasprintf：动态格式化字符串（自动分配内存）
• SDL_snprintf/SDL_vsnprintf：安全格式化字符串（防止缓冲区溢出）
• SDL_utf8strlcpy：UTF-8 安全字符串拷贝

3. 内存操作函数

• SDL_memcpy：内存拷贝（替代 memcpy，平台优化实现）
• SDL_memmove：内存移动（处理重叠内存区域，替代 memmove）
• SDL_memset：内存填充（替代 memset）
• SDL_memset4：按 4 字节单位填充内存（更高效）
• SDL_memcmp：内存比较（替代 memcmp）

4. 数学函数

• SDL_abs：整数绝对值（替代 abs）
• SDL_fabs/SDL_fabsf：浮点数绝对值（替代 fabs/fabsf）
• SDL_sin/SDL_sinf/SDL_cos/SDL_cosf：三角函数（正弦/余弦）
• SDL_atan/SDL_atanf/SDL_atan2/SDL_atan2f：反正切函数
• SDL_acos/SDL_acosf/SDL_asin/SDL_asinf：反余弦/反正弦函数
• SDL_tan/SDL_tanf：正切函数
• SDL_sqrt/SDL_sqrtf：平方根函数
• SDL_pow/SDL_powf：幂函数
• SDL_exp/SDL_expf：指数函数
• SDL_log/SDL_logf/SDL_log10/SDL_log10f：对数函数
• SDL_floor/SDL_floorf：向下取整
• SDL_ceil/SDL_ceilf：向上取整
• SDL_round/SDL_roundf：四舍五入
• SDL_trunc/SDL_truncf：截断小数部分
• SDL_lround/SDL_lroundf：四舍五入转长整数
• SDL_fmod/SDL_fmodf：取模运算（浮点数）
• SDL_copysign/SDL_copysignf：复制符号位
• SDL_isinf/SDL_isinff：检测无穷大
• SDL_isnan/SDL_isnanf：检测非数值（NaN）
• SDL_PI_F/SDL_PI_D：圆周率常量（单/双精度）

5. 字符判断函数

• SDL_isalpha/SDL_isdigit/SDL_isalnum：字母/数字/字母数字判断
• SDL_islower/SDL_isupper：大小写字母判断
• SDL_isspace/SDL_isblank：空白字符判断
• SDL_iscntrl/SDL_isprint/SDL_isgraph：控制字符/可打印字符/图形字符判断
• SDL_ispunct：标点符号判断
• SDL_isxdigit：十六进制字符判断
• SDL_tolower/SDL_toupper：字符大小写转换

6. 排序/查找函数

• SDL_qsort/SDL_qsort_r：快速排序（qsort_r 为可重入版本，线程安全）
• SDL_bsearch/SDL_bsearch_r：二分查找（bsearch_r 为可重入版本）

7. 哈希/校验函数

• SDL_crc16/SDL_crc32：计算 CRC16/CRC32 校验值
• SDL_murmur3_32：计算 Murmur3 32 位哈希值

8. 环境变量函数

• SDL_getenv/SDL_getenv_unsafe：获取环境变量（_unsafe 版本不做安全检查）
• SDL_SetEnvironmentVariable/SDL_UnsetEnvironmentVariable：设置/删除环境变量
• SDL_GetEnvironmentVariables：获取所有环境变量列表
• SDL_CreateEnvironment/SDL_DestroyEnvironment：创建/销毁独立的环境变量上下文

9. 字符编码转换函数

• SDL_iconv_open：打开字符编码转换上下文
• SDL_iconv：执行编码转换
• SDL_iconv_close：关闭转换上下文
• SDL_iconv_string：字符串编码转换（简化接口）
• SDL_UCS4ToUTF8：UCS4 转 UTF-8 编码
• SDL_StepUTF8/SDL_StepBackUTF8：UTF-8 字符串步进/回退（遍历字符）

10. 随机数函数

• SDL_srand：设置随机数种子
• SDL_rand：生成随机整数（替代 rand）
• SDL_randf：生成 0~1 浮点数随机数
• SDL_rand_r/SDL_randf_r：可重入的随机数生成（线程安全）
• SDL_rand_bits：生成指定位数的随机数

11. 宽字符函数

• SDL_wcslen/SDL_wcscmp/SDL_wcsncmp：宽字符串长度/比较
• SDL_wcsstr/SDL_wcsnstr：宽字符串查找
• SDL_wcslcpy/SDL_wcslcat：宽字符串安全拷贝/拼接
• SDL_wcsdup：宽字符串拷贝（自动分配内存）
• SDL_wcstol：宽字符串转长整数

12. 格式化输入函数

• SDL_sscanf/SDL_vsscanf：安全格式化输入（替代 sscanf）
• SDL_swprintf/SDL_vswprintf：宽字符串格式化输出

数据类型

• SDL_malloc_func：内存分配函数指针类型（匹配 SDL_malloc 签名）
• SDL_calloc_func：内存分配并清零函数指针类型
• SDL_realloc_func：内存重分配函数指针类型
• SDL_free_func：内存释放函数指针类型
• SDL_CompareCallback：排序/查找比较函数类型
• SDL_CompareCallback_r：可重入的比较函数类型（带用户数据）
• SDL_Environment：环境变量上下文类型
• SDL_iconv_t：字符编码转换上下文类型
• SDL_FunctionPointer：通用函数指针类型
• SDL_Time：时间类型（跨平台兼容）
• Sint8/Sint16/Sint32/Sint64：有符号整数类型（固定位宽）
• Uint8/Uint16/Uint32/Uint64：无符号整数类型（固定位宽）

结构体

• （无）

枚举

• （无）

宏

1. 类型转换宏

• SDL_static_cast：静态类型转换（替代 C++ static_cast）
• SDL_reinterpret_cast：重解释类型转换（替代 C++ reinterpret_cast）
• SDL_const_cast：常量类型转换（替代 C++ const_cast）

2. 数学/工具宏

• SDL_min/SDL_max：取最小值/最大值
• SDL_clamp：将值限制在指定范围内（clamp(value, min, max)）
• SDL_arraysize：计算数组元素个数（编译期计算，安全）
• SDL_FLT_EPSILON：浮点数精度阈值（用于判断浮点数相等）
• SDL_SIZE_MAX：size_t 类型的最大值

3. 内存初始化宏

• SDL_zero：将变量清零（SDL_zero(var)）
• SDL_zeroa：将数组清零（SDL_zeroa(array)）
• SDL_zerop：将指针指向的内存清零（SDL_zerop(ptr)）
• SDL_copyp：指针拷贝（SDL_copyp(dst, src)）
• SDL_stack_alloc：栈内存分配（临时内存，无需释放）
• SDL_stack_free：栈内存释放（配套 SDL_stack_alloc）

4. 编译期检查宏

• SDL_COMPILE_TIME_ASSERT：编译期断言（失败则编译报错）

5. 格式化输出宏

• SDL_PRIs32/SDL_PRIu32：32 位整数格式化占位符（跨平台兼容）
• SDL_PRIs64/SDL_PRIu64/SDL_PRIx64：64 位整数格式化占位符
• SDL_PRINTF_FORMAT_STRING：标记格式化字符串参数（编译器检查）
• SDL_PRINTF_VARARG_FUNC：标记可变参数格式化函数

6. 编码转换宏

• SDL_iconv_utf8_locale：UTF-8 转系统本地编码
• SDL_iconv_utf8_ucs2/SDL_iconv_utf8_ucs4：UTF-8 转 UCS2/UCS4
• SDL_iconv_wchar_utf8：宽字符转 UTF-8

7. 其他宏

• SDL_FOURCC：生成四字符码（用于标识媒体格式等）
• SDL_SINT64_C/SDL_UINT64_C：64 位常量定义（跨平台兼容）
• SDL_INVALID_UNICODE_CODEPOINT：无效 Unicode 码点常量

FreeBASIC 示例代码

' 引入 SDL 相关声明（需确保 FreeBASIC 已链接 SDL3 库）
#Include "SDL.bi"

' 补充核心函数/宏声明（FreeBASIC 绑定可能缺失）
#Define SDL_PI_F 3.14159265358979323846f
#Define SDL_min(a, b) IIf((a) < (b), (a), (b))
#Define SDL_max(a, b) IIf((a) > (b), (a), (b))
#Define SDL_clamp(x, min_val, max_val) SDL_max(SDL_min((x), (max_val)), (min_val))

' 函数声明补充
Declare Function SDL_utf8strlen CDecl (ByVal str As ZString Ptr) As Size_t
Declare Function SDL_strlcpy CDecl (ByVal dst As ZString Ptr, ByVal src As ZString Ptr, ByVal size As Size_t) As Size_t
Declare Function SDL_crc32 CDecl (ByVal crc As Uint32, ByVal data As Const Any Ptr, ByVal len As Size_t) As Uint32
Declare Sub SDL_zero CDecl (ByRef var As Any)
Declare Function SDL_randf CDecl () As Float
Declare Sub SDL_srand CDecl (ByVal seed As Uint32)

' ==================== 示例 1：安全字符串操作 ====================
Sub StringOperationsExample()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "【安全字符串操作示例】")

    ' 1. SDL_strlcpy 安全拷贝（防止缓冲区溢出）
    Dim As ZString * 10 dstBuffer
    Dim As ZString Ptr src = StrPtr("Hello SDL!")

    ' 拷贝最多 9 个字符 + 终止符，返回原字符串长度
    Dim As Size_t len = SDL_strlcpy(@dstBuffer, src, sizeof(dstBuffer))
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "原字符串：%s，长度：%d", src, len)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "拷贝结果：%s（缓冲区大小：%d）", dstBuffer, sizeof(dstBuffer))

    ' 2. UTF-8 字符串长度计算
    Dim As ZString Ptr utf8Str = StrPtr("SDL 中文示例")
    Dim As Size_t byteLen = SDL_strlen(utf8Str)       ' 字节数
    Dim As Size_t charLen = SDL_utf8strlen(utf8Str)   ' 字符数
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "UTF-8 字符串：%s", utf8Str)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "字节长度：%d，字符长度：%d", byteLen, charLen)

    ' 3. 整数转字符串（跨平台兼容）
    Dim As ZString * 32 numStr
    SDL_itoa(-12345, @numStr, 10)  ' 十进制
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "整数转字符串：%s", numStr)
    SDL_uitoa(65535, @numStr, 16)  ' 十六进制
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "无符号整数转十六进制：%s", numStr)
End Sub

' ==================== 示例 2：内存操作与校验 ====================
Sub MemoryOperationsExample()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "【内存操作与校验示例】")

    ' 1. 内存分配与初始化
    Dim As Integer Ptr arr = SDL_calloc(5, sizeof(Integer))
    If (arr = NULL) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "内存分配失败")
        Exit Sub
    End If

    ' 填充数据
    For i As Integer = 0 To 4
        arr[i] = i * 10
    Next

    ' 2. 内存拷贝
    Dim As Integer Ptr arrCopy = SDL_malloc(5 * sizeof(Integer))
    SDL_memcpy(arrCopy, arr, 5 * sizeof(Integer))

    ' 打印拷贝结果
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "内存拷贝结果：")
    For i As Integer = 0 To 4
        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "  arrCopy[%d] = %d", i, arrCopy[i])
    Next

    ' 3. CRC32 校验
    Dim As Uint32 crc = SDL_crc32(0, arr, 5 * sizeof(Integer))
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "数据 CRC32 校验值：0x%08X", crc)

    ' 4. 内存释放
    SDL_free(arr)
    SDL_free(arrCopy)

    ' 5. 内存清零
    Type TestStruct
        a As Integer
        b As Float
        c As ZString * 20
    End Type
    Dim As TestStruct ts
    SDL_zero(ts)  ' 清零整个结构体
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "结构体清零后：a=%d, b=%.2f", ts.a, ts.b)
End Sub

' ==================== 示例 3：数学与随机数 ====================
Sub MathAndRandomExample()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "【数学与随机数示例】")

    ' 1. 数学函数
    Dim As Float angle = SDL_PI_F / 4  ' 45 度
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "sin(45°) = %.4f", SDL_sinf(angle))
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "cos(45°) = %.4f", SDL_cosf(angle))
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "sqrt(2) = %.4f", SDL_sqrtf(2.0f))

    ' 2. 数值限制（clamp）
    Dim As Integer val = 150
    Dim As Integer clamped = SDL_clamp(val, 0, 100)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "clamp(150, 0, 100) = %d", clamped)

    ' 3. 随机数
    SDL_srand(SDL_GetTicks())  ' 以时间为种子
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "随机整数：%d", SDL_rand() Mod 100)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "随机浮点数（0~1）：%.4f", SDL_randf())
End Sub

' ==================== 示例 4：环境变量操作 ====================
Sub EnvVarExample()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "【环境变量操作示例】")

    ' 1. 设置环境变量
    SDL_SetEnvironmentVariable(StrPtr("SDL_TEST_VAR"), StrPtr("Hello SDL Env"))

    ' 2. 获取环境变量
    Dim As ZString Ptr envVal = SDL_getenv(StrPtr("SDL_TEST_VAR"))
    If (envVal <> NULL) Then
        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "获取环境变量 SDL_TEST_VAR：%s", envVal)
    End If

    ' 3. 删除环境变量
    SDL_UnsetEnvironmentVariable(StrPtr("SDL_TEST_VAR"))
    envVal = SDL_getenv(StrPtr("SDL_TEST_VAR"))
    If (envVal = NULL) Then
        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "环境变量 SDL_TEST_VAR 已删除")
    End If
End Sub

' ==================== 主程序 ====================
Sub Main()
    ' 初始化 SDL（Stdinc 子系统无需特定初始化）
    If (SDL_Init(0) < 0) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL 初始化失败：%s", SDL_GetError())
        Exit Sub
    End If

    ' 运行示例
    StringOperationsExample()
    MemoryOperationsExample()
    MathAndRandomExample()
    EnvVarExample()

    ' 清理 SDL
    SDL_Quit()

    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "程序正常退出")
End Sub

' 运行主程序
Main()

核心知识点补充

1. 核心设计理念：

   • SDL_stdinc 的核心目标是「跨平台一致性」，而非「替代标准库」；
   • 对于底层实现稳定的函数（如 memcpy），SDL 会直接调用平台原生版本，保证性能；
   • 对于行为不一致/缺失的函数（如 itoa/snprintf），SDL 提供自研实现，保证跨平台表现相同。

2. 内存管理最佳实践：

   • SDL 内存函数（SDL_malloc/SDL_free 等）必须配对使用，不可混用标准库 free；
   • SDL_calloc 会自动清零内存，优先用于需要初始化的场景；
   • SDL_GetNumAllocations 可用于调试内存泄漏（记录分配/释放的数量差）；
   • 自定义内存函数需在 SDL 初始化前通过 SDL_SetMemoryFunctions 设置。

3. 字符串安全要点：

   • 优先使用 SDL_strlcpy/SDL_strlcat 替代 strcpy/strcat，避免缓冲区溢出；
   • SDL_utf8strlen 是 UTF-8 字符串的「字符数」统计，SDL_strlen 是「字节数」统计；
   • SDL_asprintf 会自动分配内存，使用后必须调用 SDL_free 释放。

4. 跨平台兼容注意：

   • 64 位整数格式化需使用 SDL_PRId64/SDL_PRIu64 等宏，避免 %lld/%llu 的平台差异；
   • 整数类型优先使用 Sint32/Uint32 等固定位宽类型，而非 int/long；
   • 随机数函数 SDL_rand 比标准 rand 更稳定，且 SDL_rand_r 保证线程安全。

总结

1. 核心优势：

   • 解耦 C 运行时依赖，降低跨平台编译复杂度；
   • 统一函数行为，避免不同平台的标准库实现差异；
   • 补充安全/增强功能（如 SDL_strlcpy/SDL_crc32），提升代码健壮性；
   • 底层优化实现，兼顾性能与兼容性。

2. 使用建议：

   • 新项目优先使用 SDL_stdinc 函数替代标准库函数，减少跨平台问题；
   • 内存分配/释放必须使用 SDL 配套函数（SDL_malloc ↔ SDL_free）；
   • UTF-8 字符串操作使用 SDL_utf8* 系列函数，避免多字节字符处理错误；
   • 编译期使用 SDL_COMPILE_TIME_ASSERT 检查类型大小、常量等，提前发现问题。

3. 关键点回顾：

   • SDL_stdinc 是 SDL 的基础工具集，提供跨平台一致的 C 运行时函数；
   • SDL_strlcpy/SDL_snprintf 等函数解决了标准库字符串操作的安全问题；
   • 内存函数、数学函数、随机数函数均做了跨平台兼容和性能优化；
   • 固定位宽类型（Sint32/Uint64）和格式化宏（SDL_PRIs64）是跨平台开发的关键。