zhangyiss/gctl_tutorials
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
b92f48a4f8
gctl_tutorials/doc/core/doc_str.md
Yi Zhang 3789f373ce tmp
2025-05-16 08:49:00 +08:00

7.8 KiB
Raw Blame History

GCTL核心字符串处理模块文档（gctl/lib/core/str.h）

文件概述

#include "exceptions.h"  // 异常处理依赖
#include <cmath>       // 数学函数
#include <vector>      // 向量容器
#include <sstream>     // 字符串流

本模块提供字符串与基础数据类型间的转换、字符串解析处理等核心功能，包含以下主要功能：

  • 类型与字符串的相互转换
  • 字符串模式替换与路径处理
  • 带分隔符的字符串解析
  • 特殊数值（NaN/Inf）转换
  • 随机字符串生成

核心功能模块

1. 类型转换

模板函数 type2ss

template <typename ObjValType>
void type2ss(ObjValType in_val, std::stringstream &out_ss)
  • 功能：将任意类型转换为字符串流
  • 参数：
    • in_val：输入值（支持基础数据类型）
    • out_ss：输出字符串流（需预先声明）
  • 示例： 
    std::stringstream ss;
gctl::type2ss(3.14, ss);
std::cout << ss.str(); // 输出"3.14"

模板函数 str2type

template <typename OutValType>
int str2type(std::string in_str, OutValType &out_val, char sep = ' ')
  • 功能：带分隔符的字符串到类型转换
  • 参数：
    • in_str：输入字符串
    • out_val：输出值（引用返回）
    • sep：分隔符（默认空格）
  • 返回值：
    • 0：转换成功
    • -1：转换失败
  • 注意：自动替换分隔符为空格后进行解析

2. 向量处理

数值向量转换 type2str_vector

template <typename ValueType>
void type2str_vector(const std::vector<ValueType> &in_vec,
                   std::vector<std::string> &out_vec)
  • 功能：将数值向量转换为字符串向量
  • 参数：
    • in_vec：输入数值向量
    • out_vec：输出字符串向量（自动清空原有内容）

二维向量解析 str2type_vector2d

// 基础版本
template <typename ValueType>
void str2type_vector2d(...)

// 变参模板版本
template <typename ValueType, typename... Args>
void str2type_vector2d(const std::vector<std::vector<std::string>> &vec2d,
                     std::string order_str,
                     std::vector<ValueType> &vec, Args&... rest)
  • 新特性：
    • 支持多个输出参数，按order_str顺序解析
    • 示例：order_str="0,2,1" 解析第0、2、1列到不同向量
  • 异常：统一抛出std::runtime_error

二维向量生成 type2str_vector2d

template <typename ValueType>
void type2str_vector2d(std::vector<std::vector<ValueType>> &vec2d,
                     const std::vector<std::string> &vec)

template <typename ValueType, typename... Args>
void type2str_vector2d(std::vector<std::vector<ValueType>> &vec2d,
                     const std::vector<std::string> &vec, Args&... rest)
  • 功能：批量转换多个字符串向量到数值二维向量
  • 典型应用：构建CSV格式的数据矩阵

3. 高级模板功能

变参字符串解析 parse_string_to_value

template <typename ValueType, typename... Args>
int parse_string_to_value(std::string val_str, char separator,
                        bool throw_err, ValueType &fst_val, Args&... rest)
  • 功能：解析含多个值的字符串到不同变量
  • 参数顺序：
    1. 输入字符串
    2. 分隔符
    3. 是否抛出异常
    4. 输出参数列表（至少1个）
  • 返回值：成功解析的参数个数
  • 示例： 
    int a; double b; std::string c;
parse_string_to_value("5,3.14,text", ',', true, a, b, c);

4. 字符串操作

全局替换 replace_all

int replace_all(std::string& new_str, const std::string& old_str, 
              const std::string& old_value, const std::string& new_value)
  • 功能：全量替换字符串中的子串
  • 参数：
    • new_str：替换后的新字符串（输出）
    • old_str：原始字符串
    • old_value：待替换的子串
    • new_value：新子串
  • 返回值：替换次数

路径补全 patch_string

std::string patch_string(std::string in_str, std::string patch_str)
  • 功能：智能补全路径字符串
  • 示例： 
    auto path = gctl::patch_string("/data", "/"); // 返回"/data/"
  • 逻辑：检查末尾是否已包含目标字符串，若否则追加

4. 特殊数值处理

安全双精度转换 str2double

double str2double(std::string instr)
  • 功能：转换字符串到double，支持：
    • Fortran风格的科学计数法（如"1.23D+04"）
    • NaN/Infinity的特殊处理
  • 实现：自动替换'D'为'E'后使用标准库转换

5. 实用工具函数

流转换函数 str2ss

void str2ss(std::string in_str, std::stringstream &out_ss, std::string delimiter = "")
  • 功能：将字符串转换为预处理后的字符串流
  • 参数：
    • delimiter：将指定分隔符替换为空格
    • out_ss：输出流（自动清空原有内容）
  • 应用场景：处理CSV等格式数据

随机字符串生成

void random_char(unsigned int length, char* out);
void random_str(unsigned int length, std::string &out_str);
  • 字符范围：a-z, A-Z, 0-9
  • 安全特性：线程安全的随机数生成
  • 典型应用：生成临时文件名或验证码
  • 示例： 
    std::string random;
gctl::random_str(8, random); // 可能得到"aB3x9K7f"

通用字符串解析 parse_string_to_vector

template <typename ValueType>
int parse_string_to_vector(std::string val_str, char separator,
                         std::vector<ValueType> &out_vec)
  • 增强特性：
    • 自动去除元素首尾空白
    • 支持保留带空格的字符串（当ValueType为std::string时）
  • 示例： 
    std::vector<std::string> parts;
parse_string_to_vector("name=John Doe; age=30", ';', parts);
// 得到 ["name=John Doe", "age=30"]

6. 异常处理规范

统一异常类型

  • 所有解析函数均可能抛出 gctl::runtime_error
  • 错误信息包含：
    • 具体失败位置（函数名）
    • 原始输入内容片段
    • 失败原因（类型不匹配/格式错误等）

错误处理示例

try {
    std::vector<double> values;
    gctl::str2type_vector({"1", "2.5", "abc"}, values);
} catch (const gctl::runtime_error& e) {
    std::cerr << "解析错误: " << e.what();
    // 输出：解析错误: [gctl::str2type_vector] Failed to parse: abc
}

### 7. 高级解析功能
#### 带引号解析 `parse_string_with_quotes`
```cpp
void parse_string_with_quotes(std::string in_str, std::vector<std::string> &str_vec)
  • 增强特性：
    • 支持嵌套引号（使用"转义）
    • 自动去除外层引号
  • 示例： 
    输入: `cmd "complex \"name\"" 123`
输出: ["cmd", "complex "name"", "123"]

void parse_string_with_quotes(std::string in_str, std::vector<std::string> &str_vec)
  • 功能：解析含空格和引号的字符串
  • 示例： 
    输入: `cmd "file name.txt" 100`
输出: ["cmd", "file name.txt", "100"]
  • 规则：
    1. 双引号内的内容视为单个元素
    2. 自动去除元素首尾空白

使用示例

类型转换示例

std::vector<std::string> str_vec{"1", "2.5", "3"};
std::vector<int> int_vec;
gctl::str2type_vector(str_vec, int_vec); // 得到[1,2,3]

配置文件解析

std::string config = "max_threads=4, timeout=30s";
int threads;
std::string timeout;
gctl::parse_string_to_value(config, '=', true, threads, timeout);

注意事项

  1. 异常处理：关键函数（如str2type_vector）会抛出gctl::runtime_error
  2. 线程安全：函数内部使用局部变量，可安全用于多线程环境
  3. 性能建议：批量处理建议使用vector版本函数
  4. 编码要求：输入字符串建议使用UTF-8编码