csv.hpp：CSV 读取接口与数据容器

CSV 允许值、必填键与默认值。

这个文件做什么

CsvTable 保存表头、数据行和文件路径；按列名取值后，可转换成数值或布尔值。这个层只负责文本读取，物种和反应含义由模型层检查。对应实现是 fun_G02_mcc_csv.cpp。

主要类型与入口

CsvRow, CsvTable; parse_csv_line, read_csv_table, csv_real, csv_real_or, csv_int, csv_bool, trim, to_lower, fnv1a64_hex

上面列出的是入口名称，具体参数以源码声明为准。

Tip

  • ABI (Application Binary Interface) defines how compiled code passes arguments and results. A handle refers to a library-owned object; use API functions rather than inspecting its internals.

CSV allowed values, required keys and defaults.

What this file does

CsvTable stores a header, rows and source path. Named fields can be converted to numbers or booleans. This layer handles text; model validation handles physical meaning. Implemented in fun_G02_mcc_csv.cpp.

Main types and entry points

CsvRow, CsvTable; parse_csv_line, read_csv_table, csv_real, csv_real_or, csv_int, csv_bool, trim, to_lower, fnv1a64_hex

The names above are an interface index; consult the source declarations for exact parameters.

源码 / Source

csv.hpp

 1// SPDX-License-Identifier: Apache-2.0
 2//
 3// 阅读指引：这是最底层的文本读取工具，不负责判断反应是否符合物理。
 4// read_csv_table 读取字符串表格，csv_real/csv_int 等再做数值转换。
 5
 6//
 7// Strict CSV reader for the G02_MCC_network model package.
 8//
 9// Grammar:
10//   * comma separated fields;
11//   * a field may be wrapped in double quotes; a literal double quote inside a
12//     quoted field is written as "" (two double quotes);
13//   * fields may not contain newlines (a line is a record);
14//   * blank lines and whole-line comments starting with '#' (after optional
15//     leading whitespace) are ignored;
16//   * every record must have exactly the same number of fields as the header.
17//
18// Every parse failure reports "<file>:<line>: <message>".
19#pragma once
20
21#include "common.hpp"
22
23#include <cstddef>
24#include <filesystem>
25#include <string>
26#include <string_view>
27#include <unordered_map>
28#include <vector>
29
30namespace algoplasma {
31namespace mcc {
32
33// 保留原文件行号，出错时能指向用户需要修改的那一行。
34struct CsvRow {
35    std::vector<std::string> fields;
36    std::size_t line{0};
37};
38
39// 按列名访问数据，避免调用方把“第几列”写死。表头索引在首次查询时建立。
40class CsvTable {
41public:
42    std::filesystem::path path;
43    std::vector<std::string> header;
44    std::vector<CsvRow> rows;
45
46    [[nodiscard]] bool has_column(std::string_view name) const noexcept;
47    [[nodiscard]] std::size_t column(std::string_view name) const; // throws Error
48    [[nodiscard]] std::string value(const CsvRow& row, std::string_view name) const;
49    // 缺列或空字段时使用 fallback；普通 value 不会自行补默认值。
50    [[nodiscard]] std::string value_or(const CsvRow& row, std::string_view name,
51                                       std::string fallback) const;
52
53private:
54    void build_index() const;
55    mutable std::unordered_map<std::string, std::size_t> index_;
56    mutable bool indexed_{false};
57};
58
59// Parse a single CSV record. `context` is used verbatim in error messages.
60[[nodiscard]] std::vector<std::string> parse_csv_line(std::string_view line,
61                                                      const std::string& context);
62
63[[nodiscard]] CsvTable read_csv_table(const std::filesystem::path& path);
64
65// Typed field readers. Errors include "<file>:<line>: column '<name>' ...".
66// 必填实数必须完整转换且有限；带 _or 的函数才允许缺列/留空用默认值。
67// 单位、正负范围和物理意义由上层 model/compile 检查。
68[[nodiscard]] Real csv_real(const CsvTable& table, const CsvRow& row, std::string_view name);
69[[nodiscard]] Real csv_real_or(const CsvTable& table, const CsvRow& row, std::string_view name,
70                               Real fallback);
71[[nodiscard]] long long csv_int(const CsvTable& table, const CsvRow& row, std::string_view name);
72[[nodiscard]] bool csv_bool(const CsvTable& table, const CsvRow& row, std::string_view name);
73
74[[nodiscard]] std::string to_lower(std::string value);
75[[nodiscard]] std::string trim(std::string value);
76
77// FNV-1a 64-bit checksum, rendered as 16 lowercase hex digits. The model package
78// uses it for optional integrity entries in manifest.csv. This is an integrity
79// check, not a cryptographic signature.
80[[nodiscard]] std::string fnv1a64_hex(const std::filesystem::path& path);
81
82} // namespace mcc
83} // namespace algoplasma

文件归属 / File location

G_Collision/G02_MCC_network/csv.hpp

Model