API 参考

入口头文件

#include <fqtools/fq.h>

模块关系

fq.h(聚合入口)
 ├── io/ → FastqReader / FastqWriter / FastqRecord / FastqBatch
 ├── processing/ → ProcessingPipelineInterface / Predicate / Mutator
 ├── statistics/ → StatisticCalculatorInterface
 ├── core/ → SequenceUtils
 ├── config/ → Configuration
 ├── error/ → FastQException 异常体系
 ├── logging/ → init / setLevel
 └── common/ → Timer / IDGenerator

IO 模块 — fq::io

FastqRecord

auto averageQuality(int qualityEncoding = 33) const -> double;
auto length() const -> size_t;
auto gcContent() const -> double;
auto nRatio() const -> double;

FastqBatch

auto records() const -> const std::vector<FastqRecord>&;
auto size() const -> size_t;
auto empty() const -> bool;
void clear();
void reserve(size_t count);

FastqBatch
├── buffer_ 连续内存块(存储原始文本)
└── records_ FastqRecord 数组(string_view 指向 buffer_)

FastqReader

fq::io::FastqReader reader("input.fastq.gz");
fq::io::FastqBatch batch;
while (reader.nextBatch(batch, 10000)) {
 for (const auto& record : batch.records()) {
 // 处理每条记录
 }
}

FastqWriter

fq::io::FastqWriter writer("output.fastq.gz");
for (const auto& record : batch.records()) {
 writer.write(record);
}

FastqBatchPool

auto pool = fq::io::createFastqBatchPool(initialSize, maxSize);
auto batch = pool->acquire(); // 从池获取
// shared_ptr 析构时自动归还

处理流水线 — fq::processing

ProcessingPipelineInterface

auto pipeline = fq::processing::createProcessingPipeline();

class ProcessingPipelineInterface {
public:
 virtual void setInputPath(const std::string& path) = 0;
 virtual void setOutputPath(const std::string& path) = 0;
 virtual void setProcessingConfig(const ProcessingConfig& config) = 0;
 virtual void addReadPredicate(std::unique_ptr<ReadPredicateInterface> predicate) = 0;
 virtual void addReadMutator(std::unique_ptr<ReadMutatorInterface> mutator) = 0;
 virtual auto run() -> ProcessingStats = 0;
};

ProcessingConfig

ProcessingStats

ReadPredicateInterface — 过滤谓词

class ReadPredicateInterface {
public:
 virtual auto evaluate(const fq::io::FastqRecord& read) const -> bool = 0;
};

ReadMutatorInterface — 读段修饰器

class ReadMutatorInterface {
public:
 virtual void process(fq::io::FastqRecord& read) = 0;
};

统计分析 — fq::statistic

StatisticCalculatorInterface

fq::statistic::StatisticOptions options;
options.inputFastqPath = "input.fastq.gz";
options.outputStatPath = "output.stat.txt";
options.threadCount = 4;
auto calculator = fq::statistic::createStatisticCalculator(options);
calculator->run();

StatisticOptions

FqStatisticResult

核心工具 — fq::core

SequenceUtils

namespace fq::core {
class SequenceUtils {
public:
 template <std::ranges::range R>
 static auto gcContent(const R& sequence) -> double;
 template <std::ranges::range R>
 static auto nRatio(const R& sequence) -> double;
 static auto reverseComplement(std::string_view sequence) -> std::string;
 static auto isValidBase(char base) -> bool;
};
}

配置管理 — fq::config

namespace fq::config {
class Configuration {
public:
 void loadFromFile(const std::string& configFile);
 void loadFromArgs(int argc, const char* argv[]);
 void loadFromEnv();
 template <typename T> auto get(const std::string& key) const -> T;
 template <typename T> auto getOr(const std::string& key, const T& def) const -> T;
 template <typename T> void set(const std::string& key, const T& value);
 auto hasKey(const std::string& key) const -> bool;
 void validate() const;
};
}

错误处理 — fq::error

异常体系

FastQException
├── IOError — 文件 I/O 错误
├── FormatError — FASTQ 格式错误
├── ConfigurationError — 配置错误
└── ValidationError — 验证错误

ErrorCategory / ErrorSeverity

enum class ErrorCategory { IO, Format, Validation, Processing, Resource, Configuration };
enum class ErrorSeverity { Info, Warning, Error, Critical };

便捷宏

FQ_THROW_CONFIG_ERROR("Required key 'input' is missing");
FQ_THROW_IO_ERROR("Failed to open file: " + path);

日志系统 — fq::logging

fq::logging::LogOptions options;
options.level = "info"; // trace/debug/info/warn/error
options.colored = true;
fq::logging::init(options);
fq::logging::info("Processing {} reads", readCount);
fq::logging::warn("Quality below threshold: {}", quality);
fq::logging::setLevel("debug");

CMake 集成

find_package(FastQTools REQUIRED)
target_link_libraries(my_app PRIVATE FastQTools::FastQTools)

完整示例

#include <fqtools/fq.h>
#include <iostream>
int main() {
 // 创建处理流水线
 auto pipeline = fq::processing::createProcessingPipeline();
 pipeline->setInputPath("input.fastq");
 pipeline->setOutputPath("output.fastq");
 // 配置
 fq::processing::ProcessingConfig config;
 config.batchSize = 10000;
 config.threadCount = 4;
 pipeline->setProcessingConfig(config);
 // 添加过滤条件
 pipeline->addReadPredicate(
 std::make_unique<fq::processing::MinQualityPredicate>(20.0, 33));
 pipeline->addReadPredicate(
 std::make_unique<fq::processing::MinLengthPredicate>(50));
 // 添加修剪器
 pipeline->addReadMutator(
 std::make_unique<fq::processing::QualityTrimmer>(
 20.0, 50, fq::processing::QualityTrimmer::TrimMode::Both, 33));
 // 执行
 auto stats = pipeline->run();
 std::cout << stats.toString() << std::endl;
 return 0;
}

相关页面