Utils（工具函數）

ll/api/utils/ · 通用

概述

Utils 模塊提供了各種實用函數，包括系統信息、字符串操作、哈希、隨機數生成、文件 I/O、Base64 編碼和錯誤處理。

頭文件

頭文件	說明
`ll/api/utils/SystemUtils.h`	系統信息（操作系統、語言環境、環境變量、模塊路徑）
`ll/api/utils/StringUtils.h`	字符串分割、替換、大小寫轉換
`ll/api/utils/HashUtils.h`	哈希工具
`ll/api/utils/RandomUtils.h`	隨機數生成
`ll/api/utils/ErrorUtils.h`	錯誤提取和格式化
`ll/api/utils/StacktraceUtils.h`	堆棧跟蹤生成
`ll/api/utils/FontUtils.h`	字體枚舉
`ll/api/utils/FileUtils.h`	文件 I/O 工具
`ll/api/utils/Base64Utils.h`	Base64 編碼/解碼
`ll/api/utils/CompressUtils.h`	壓縮與解壓,支持流式和一次性兩種用法

核心函數

SystemUtils

C++

namespace ll::sys_utils {
std::string getSystemName();
std::string getSystemLocaleCode();
data::Version getSystemVersion();

void* getModuleHandle(void* addr);
std::filesystem::path getModulePath(void* addr);
std::string getModuleFileName(void* addr);

std::optional<std::string> getEnvironmentVariable(std::string_view name);
}

StringUtils

C++

namespace ll::string_utils {
std::vector<std::string> splitByPattern(std::string_view str, std::string_view pattern);
std::string& replaceAll(std::string& str, std::string_view oldVal, std::string_view newVal);
std::string& toLower(std::string& str);
std::string& toUpper(std::string& str);
std::string toCamelCase(std::string_view str);
std::string toSnakeCase(std::string_view str);
}

FileUtils

C++

namespace ll::file_utils {
std::optional<std::string> readFile(std::filesystem::path const& path);
bool writeFile(std::filesystem::path const& path, std::string_view content);
std::optional<data::Version> getVersion(std::filesystem::path const& path);
}

HashUtils

C++

namespace ll::hash_utils {
size_t doHash(auto const&... args);

struct HashCombiner {
    size_t hash = 0;
    HashCombiner& add(auto const& val);
    operator size_t() const;
};
}

RandomUtils

C++

namespace ll::random_utils {
int randomInt(int min, int max);
double randomReal(double min, double max);
}

Base64Utils

C++

namespace ll::base64_utils {
std::string encode(std::string_view data);
std::string decode(std::string_view data);
}

CompressUtils

C++

namespace ll::compress_utils {
enum class CompressFormat : int { Gzip, Zlib };
enum class CompressLevel : int { Store, Fastest, Default, Best };

std::string_view extensionOf(CompressFormat format);

Expected<std::string> compress(std::string_view data, CompressFormat = CompressFormat::Gzip,
                               CompressLevel = CompressLevel::Default);
Expected<std::string> decompress(std::string_view data, CompressFormat = CompressFormat::Gzip,
                                 size_t maxSize = 0);

Expected<> compressFile(std::filesystem::path const& src, std::filesystem::path const& dst, ...);
Expected<> decompressFile(std::filesystem::path const& src, std::filesystem::path const& dst, ...);
}

使用方法

系統信息

C++

#include "ll/api/utils/SystemUtils.h"

void printSystemInfo() {
    auto osName = ll::sys_utils::getSystemName();
    auto locale = ll::sys_utils::getSystemLocaleCode();
    auto version = ll::sys_utils::getSystemVersion();
    
    // 获取环境变量
    auto path = ll::sys_utils::getEnvironmentVariable("PATH");
}

字符串操作

C++

#include "ll/api/utils/StringUtils.h"

void stringOps() {
    std::string text = "Hello World";
    ll::string_utils::toLower(text);  // "hello world"
    
    auto parts = ll::string_utils::splitByPattern("a,b,c", ",");
    // parts == {"a", "b", "c"}
    
    std::string str = "foo bar foo";
    ll::string_utils::replaceAll(str, "foo", "baz");
    // str == "baz bar baz"
}

文件操作

C++

#include "ll/api/utils/FileUtils.h"

void fileOps() {
    auto content = ll::file_utils::readFile("config.txt");
    if (content) {
        // 使用 *content
    }
    
    ll::file_utils::writeFile("output.txt", "Hello");
}

哈希

C++

#include "ll/api/utils/HashUtils.h"

void hashExample() {
    size_t hash = ll::hash_utils::doHash("key", 123, 45.6);
    
    ll::hash_utils::HashCombiner combiner;
    combiner.add("part1").add(42).add(3.14);
    size_t combined = combiner;
}

隨機數

C++

#include "ll/api/utils/RandomUtils.h"

void randomExample() {
    int dice = ll::random_utils::randomInt(1, 6);
    double chance = ll::random_utils::randomReal(0.0, 1.0);
}

Base64

C++

#include "ll/api/utils/Base64Utils.h"

void base64Example() {
    std::string encoded = ll::base64_utils::encode("Hello");
    std::string decoded = ll::base64_utils::decode(encoded);
}

壓縮

C++

#include "ll/api/utils/CompressUtils.h"

void compressExample() {
    using namespace ll::compress_utils;

    auto packed = compress("hello hello hello");
    if (!packed) {
        return;
    }
    auto original = decompress(*packed);
}

數據較大時改用流式,這樣兩側都不會整塊駐留內存。按需多次調用 write 推入數據,最後調用一次 finish:

C++

#include "ll/api/utils/CompressUtils.h"

ll::Expected<> compressToSocket(std::string_view chunk1, std::string_view chunk2) {
    using namespace ll::compress_utils;

    Compressor codec{[&](std::string_view out) -> ll::Expected<> {
        // 每次有输出产生时都会被调用
        return sendBytes(out);
    }};
    if (auto res = codec.status(); !res) {
        return res;
    }
    if (auto res = codec.write(chunk1); !res) {
        return res;
    }
    if (auto res = codec.write(chunk2); !res) {
        return res;
    }
    return codec.finish();
}

文件到文件的場景用 compressFile 和 decompressFile,它們基於同一套機制,並且先寫入臨時文件再改名, 因此中途被打斷不會留下半個文件。

decompress 默認不限制輸出大小，只有傳入 maxSize 時才會限制。數據來源不可信時請傳入它，因為很小的輸入也可能解壓出極大的數據。