核心类型与错误

帧、时间戳、日历、操作描述符、版本、滚动窗口、数据提供方约定和结构化错误。

面向任务的使用示例请参阅使用指南。以下签名与本站其余内容在同一提交中由公共头文件生成。

class analysis_context

用于第一阶段绩效分析的惰性、持有数值的容器。

summary() 返回以下稳定键：Annual return、Cumulative returns、Annual volatility、Sharpe ratio、Sortino ratio、Calmar ratio、Max drawdown、Historical value at risk、Conditional value at risk，以及在提供基准时返回 Alpha 和 Beta。

公共函数

explicit analysis_context(dataframe returns, std::optional<dataframe> benchmark = std::nullopt, double annualization = daily_annualization)

根据收益帧和可选的基准帧构造上下文。

帧按传入原样存储；仅校验所需的 double 列，此处不进行排序或索引对齐。

参数:

returns -- Frame with a required double returns column.
benchmark -- Optional frame with a required double benchmark column; enables the Alpha and Beta summary entries.
annualization -- Annualization factor used by annualized metrics.

抛出:

input_error -- If a required column is absent, not a double column, or does not match its frame index length.

std::map<std::string, double> summary() const

返回缓存的绩效摘要。

核心键包括 Annual return、Cumulative returns、Annual volatility、Sharpe ratio、Sortino ratio、Calmar ratio、Max drawdown、Historical value at risk 和 Conditional value at risk。提供基准时结果还包含 Alpha 和 Beta。每个指标在首次使用时计算，并由后续调用复用。

返回:: Map from stable metric name to computed value.

std::size_t computation_count(std::string_view key) const

返回 key 已被计算并缓存的次数。

参数:: key -- Exact summary metric key.
返回:: Number of computations for key; 0 if it has not been computed.

class batch_fetch_error : public fincore::fincore_error 

当严格批量获取对一个或多个标的失败时抛出的错误。

负载使用类别 BatchFetchError 和代码 fincore.data.batch_fetch。消息按排序顺序列出提供方和失败的标的，扁平字段保存 provider、symbols 和 error_count。

公共函数

batch_fetch_error(std::string provider, std::map<std::string, std::string> errors, std::map<std::string, dataframe> partial_results)

创建批量获取错误。

参数:

provider -- Provider name.
errors -- Per-symbol error messages.
partial_results -- Frames fetched successfully before the failure.

inline const std::string &provider() const noexcept: 返回产生该失败的提供方。

inline const std::map<std::string, std::string> &errors() const noexcept: 返回每个标的的错误消息。

inline const std::map<std::string, dataframe> &partial_results() const noexcept: 返回成功获取的帧。

class data_provider

价格数据的原生提供方接口。

实时 SDK/网络子类为 EXTERNAL_OPTIONAL；接口、批量编排、日期校验和收益转换均为原生实现，并可在注入提供方的情况下离线测试。

公共函数

virtual ~data_provider() = default: 销毁提供方。

virtual std::string provider_name() const = 0

返回提供方的稳定名称。

返回:: Provider name used in messages and batch errors.

virtual dataframe fetch(std::string_view symbol, std::string_view start, std::string_view end, std::string_view interval = "1d", bool adjust = true) const = 0

获取一个标的的价格数据。

start 和 end 的解释方式由实现定义；此接口不校验它们。派生自 std::exception 的异常由 fetch_multiple() 按标的记录。

参数:

symbol -- Instrument identifier.
start -- Requested start of the range.
end -- Requested end of the range.
interval -- Requested interval label; defaults to "1d".
adjust -- Price adjustment flag; defaults to true.

返回:

Fetched price frame.

virtual std::map<std::string, std::string> get_info(std::string_view symbol) const = 0

返回一个标的的提供方特定元数据。

参数:: symbol -- Instrument identifier.
返回:: Key/value metadata for the symbol.

inline virtual bool batch_adjust_default() const

返回未向 fetch_multiple() 提供调整标志时所使用的调整标志。

返回:: True by default.

std::map<std::string, dataframe> fetch_multiple(const std::vector<std::string> &symbols, std::string_view start, std::string_view end, std::string_view interval = "1d", std::optional<bool> adjust = std::nullopt, bool strict = false) const

通过 fetch() 获取多个标的。

提供时调整标志为 adjust，否则使用 batch_adjust_default()。每个标的都会被尝试。非严格模式下失败的标的存为空帧并丢弃其消息；严格模式下循环仍会尝试所有标的，随后若任一失败则抛出。start 和 end 原样传给 fetch()。

参数:

symbols -- Instrument identifiers to fetch.
start -- Requested start of the range.
end -- Requested end of the range.
interval -- Requested interval label; defaults to "1d".
adjust -- Optional adjustment override.
strict -- Whether to throw when any symbol fails.

抛出:

batch_fetch_error -- In strict mode when at least one fetch fails; its partial results hold the successful frames.

返回:

Map from symbol to fetched frame. In non-strict mode failed symbols map to empty frames.

std::vector<double> to_returns(const dataframe &price_data, std::string_view column = "Adj Close") const

将价格列转换为逐期简单收益率。

存在 column 时使用该列；否则方法回退到 "Close"。任一价格为 NaN 的相邻价格对被跳过。前一价格为零而当前价格非零时得到带符号的无穷大；零除以零得到 NaN 并被跳过。价格少于两个时返回空结果。

参数:

price_data -- Frame containing price data.
column -- Preferred price column; defaults to "Adj Close".

抛出:

input_error -- If the selected column is absent, is not a double column, or does not match the index length. The fallback "Close" is selected only when column is absent.

返回:

Simple returns in index order.

公共静态函数

static std::pair<timestamp, timestamp> validate_dates(std::string_view start, std::string_view end)

解析并校验 ISO-8601 UTC 日期范围。

接受的形式为 YYYY-MM-DD，可选后接 T 或空格以及 HH:MM:SS，并可选带最多九位数字的 . 小数部分。省略的时间分量默认为午夜。值按 UTC 解释；不接受末尾的时区标识。

参数:

start -- Range start.
end -- Range end; must be strictly later than start.

抛出:

fincore_error -- With category ValidationError for an unparsable date or when start is not before end.

返回:

Pair of UTC nanosecond timestamps {start, end}.

class data_snapshot

已获取市场数据的不可变、内容寻址快照。

内容摘要基于规范的 native CSV（UTC 纳秒索引加上按插入顺序排列的列）计算；它是确定性的原生来源摘要，并不表示 Python/pandas 的 CSV 字节完全相同。

公共函数

data_snapshot() = default

创建空快照。

时区默认为 "UTC"，价格调整默认为 "raw"；其余元数据和帧为空。

data_snapshot(std::string provider, std::string requested_start, std::string requested_end, std::string as_of, std::string timezone, std::string price_adjustment, std::string content_sha256, dataframe data)

根据显式元数据和数据创建快照。

值按传入原样存储；不计算摘要，也不进行一致性检查。

参数:

provider -- Provider name.
requested_start -- Requested start date.
requested_end -- Requested end date.
as_of -- Time at which the data was captured.
timezone -- Timezone label.
price_adjustment -- Price adjustment label.
content_sha256 -- Content digest text.
data -- Snapshot frame.

inline dataframe data() const

返回快照帧的防御性副本。

返回:: Copy of the stored frame; later changes to it do not affect the snapshot.

inline const dataframe &stored_data() const noexcept

返回所存帧的引用，不进行复制。

返回:: Const reference to the snapshot-owned frame.

std::map<std::string, std::string> identity_kwargs() const

返回快照的身份元数据。

该映射包含 provider、requested_start、requested_end、as_of、timezone 和 price_adjustment；不包含摘要和数据。

返回:: Map of identity metadata.

std::string to_manifest() const

返回描述快照的 JSON 清单。

该对象包含 schema_version、provider、requested_start、requested_end、as_of、timezone、price_adjustment 和 content_sha256；不包含帧数据。

返回:: JSON manifest text.

std::map<std::string, std::string> to_manifest_dict() const

以扁平字符串映射返回清单。

返回与 to_manifest() 相同的字段，其中 schema_version 以十进制字符串表示。

返回:: Map of manifest fields.

inline const std::string &provider() const noexcept: 返回提供方名称。

inline const std::string &requested_start() const noexcept: 返回请求的开始日期文本。

inline const std::string &requested_end() const noexcept: 返回请求的结束日期文本。

inline const std::string &as_of() const noexcept: 返回采集时间文本。

inline const std::string &timezone() const noexcept: 返回时区标签。

inline const std::string &price_adjustment() const noexcept: 返回价格调整标签。

inline const std::string &content_sha256() const noexcept: 返回内容摘要文本。

inline int schema_version() const noexcept

返回数据快照的 schema 版本。

返回:: data_snapshot_schema_version.

公共静态函数

static data_snapshot from_frame(const dataframe &frame, std::string provider, std::string requested_start, std::string requested_end, std::string as_of, std::string timezone = "UTC", std::string price_adjustment = "raw")

创建快照并根据 frame 计算其内容摘要。

存储 frame 的防御性副本，摘要为该副本的 dataframe_content_sha256()。

参数:

frame -- Frame to snapshot.
provider -- Provider name.
requested_start -- Requested start date.
requested_end -- Requested end date.
as_of -- Time at which the data was captured.
timezone -- Timezone label; defaults to "UTC".
price_adjustment -- Price adjustment label; defaults to "raw".

抛出:

fincore_error -- With category UnsupportedFormatError when the frame cannot be encoded as canonical CSV.

返回:

Snapshot with the computed digest and a stored copy of frame.

class fincore_error : public std::runtime_error

携带结构化 error_info 负载的异常类型。

std::runtime_error 的消息即 error_info 的消息，因此 what() 返回相同文本。

Subclassed by fincore::batch_fetch_error, fincore::research_error

公共函数

explicit fincore_error(error_info info)

从结构化负载创建异常。

参数:: info -- Error payload to store.

explicit fincore_error(std::string message)

创建使用默认 FincoreError 类别和 fincore.error 代码的异常。

参数:: message -- Human-readable error message.

inline const error_info &info() const noexcept: 返回结构化错误负载。

inline const std::string &category() const noexcept: 返回源异常类名。

inline const std::string &code() const noexcept: 返回稳定的点分错误代码。

inline const std::map<std::string, std::string> &fields() const noexcept: 返回扁平错误字段。

inline const std::map<std::string, std::string> &report() const noexcept: 返回诊断报告条目。

公共静态函数

static fincore_error from_dict(const std::map<std::string, std::string> &data)

从扁平字典形式创建异常。

参数:: data -- Flat string map accepted by error_info::from_dict().
抛出:: std::invalid_argument -- If error_type is missing or empty.
返回:: Exception carrying the parsed payload.

class input_error : public std::invalid_argument

调用方输入无效，派生自 std::invalid_argument。

该类型继承 std::invalid_argument 的构造函数。utc_timestamp() 和 make_series() 等日历与 dataframe 辅助函数在参数被拒绝时抛出该异常。

class optimization_error : public std::runtime_error

优化失败，派生自 std::runtime_error。

该类型继承 std::runtime_error 的构造函数。优化例程在求解器级失败时抛出该异常。

class rolling_engine

为一个或多个滚动指标计算尾随窗口序列。

该引擎持有收益帧和可选基准帧的副本。每个指标在由 window 个观测构成的每个完整窗口上计算；首个完整窗口之前的行不会出现在输出中。

公共函数

rolling_engine(dataframe returns, std::optional<dataframe> benchmark = std::nullopt, std::size_t window = static_cast<std::size_t>(daily_annualization), double annualization = daily_annualization)

基于收益帧和可选基准帧构造引擎。

参数:

returns -- Frame with a required double returns column.
benchmark -- Optional frame with a required double benchmark column; required only when rolling beta is requested.
window -- Number of observations per window; must be at least 2 and defaults to daily_annualization cast to std::size_t.
annualization -- Annualization factor used by annualized metrics.

抛出:

input_error -- If window is less than 2, or a required column is absent, not a double column, or does not match its frame index length.

std::map<std::string, dataframe> compute(std::span<const rolling_metric> metrics) const

为每个请求的指标返回一个尾随窗口序列。

结果将每个指标的枚举名（mean_return、volatility、sharpe、max_drawdown、beta）映射到一个帧，其单个 returns 列保存每个完整窗口最后时间戳处的指标值。Beta 输入先按其公共索引对齐，因此其序列可能更短。指标列表为空时返回空映射，可用观测少于 window 时得到空序列。

参数:: metrics -- Metrics to compute.
抛出:: input_error -- If a metric value is unknown, beta is requested without a benchmark, or a required column is invalid.
返回:: Map from metric key to a single-column series indexed by window end timestamps.

struct dependency_status

一个依赖项的可用性记录。

公共成员

std::string name: 错误消息中使用的依赖项名称。

bool available = false: 依赖项是否可用。

std::string extra: 依赖项的 extra 或功能标签。

struct error_info

原生结构化错误负载。

不复制 Python 的异常继承关系；源类名保留为 category，并带有稳定的 code、message、扁平字段和可选的诊断报告。

公共函数

std::map<std::string, std::string> to_dict() const

返回此错误的扁平字典形式。

结果以 fields 为基础，加上 error_type、message、非空的 code，以及每个报告条目对应的一个以 report. 为前缀的键。

返回:: Flat string map suitable for error_info::from_dict().

std::string to_json() const

返回包含 category、code、message、fields 和 report 的紧凑 JSON 对象。

字符串值按 JSON 转义。

返回:: JSON text.

公共成员

std::string category: 源异常类名，例如 ValidationError。

std::string code: 稳定的点分错误代码，例如 fincore.validation。

std::string message: 人类可读的错误消息。

std::map<std::string, std::string> fields: 扁平字符串字段，例如 param_name。

std::map<std::string, std::string> report

诊断报告条目；扁平化时加上 report.

作为前缀，由 to_dict() 添加。

公共静态函数

static error_info from_dict(const std::map<std::string, std::string> &data)

从扁平字典形式构建错误负载。

error_type 为必需项，并成为 category。非空的 code 条目会覆盖通过给 category 加上 fincore. 前缀而形成的默认代码；message 条目成为消息；以 report. 为前缀的条目成为报告条目，其余所有条目成为扁平字段。

参数:: data -- Flat string map, typically produced by to_dict().
抛出:: std::invalid_argument -- If error_type is missing or empty.
返回:: Parsed error payload.

struct operation_descriptor

稳定的原生操作描述符。

锁定版本的 Python 各领域声明了 OperationSpec，包含操作 id、相同的能力 id、领域、确定性/RNG 策略和来源。原生使用方需要相同的稳定标识，但不使用 Python 可调用对象、适配器或占位实现。因此该描述符只承载标识/元数据；实际实现仍由所属的原生内核负责。

公共函数

constexpr operation_descriptor() = default

创建空描述符。

所有视图为空，deterministic 为 true，rng_policy 为 "none"。

inline explicit constexpr operation_descriptor(const std::string_view id, const bool is_deterministic = true, const std::string_view policy = "none") noexcept

根据操作 id 创建描述符。

capability_id 设为 id。domain 和 provenance_owner 为第一个点之前的文本，id 不含点时则为整个 id；source_module 在 id 不含点时为空，恰好含一个点时等于整个 id，否则为第二个点之前的文本。

参数:

id -- Stable operation identifier.
is_deterministic -- Whether the operation is deterministic.
policy -- RNG policy label.

公共成员

std::string_view operation_id: 稳定的操作标识符。

std::string_view capability_id: 能力标识符；默认为操作 id。

std::string_view domain: 操作 id 的领域部分。

std::string_view source_module: 操作 id 的模块部分。

std::string_view provenance_owner: 来源所有者；默认为领域。

bool deterministic = {true}: 操作是否具有确定性。

std::string_view rng_policy = {"none"}: RNG 策略标签。

struct request_policy

用于外部数据访问的有界、确定性重试策略。

镜像锁定版本的 fincore.data.contracts.RequestPolicy 谓词，但不引入网络栈。

公共函数

request_policy() = default: 使用默认值创建策略。

request_policy(double connect_timeout, double read_timeout, double total_timeout, int max_attempts)

创建策略并校验其取值。

参数:

connect_timeout -- Connect timeout value.
read_timeout -- Read timeout value.
total_timeout -- Total timeout value.
max_attempts -- Maximum attempt count.

抛出:

fincore_error -- With category ValidationError when a timeout is not positive or max_attempts is less than 1.

void validate() const

校验超时和尝试次数取值。

抛出:: fincore_error -- With category ValidationError when a timeout is not positive or max_attempts is less than 1.

bool should_retry(transport_error_kind kind) const noexcept

返回 kind 类型的失败是否重试。

连接、超时和操作系统失败可重试；validation、none 和其他失败不重试。

参数:: kind -- Transport failure classification.
返回:: True for retryable kinds.

int remaining_attempts(int attempt) const noexcept

返回第 attempt 次尝试之后剩余的尝试次数。

结果为 max_attempts - attempt，并截断为零。

参数:: attempt -- One-based attempt number.
返回:: Remaining attempts, never negative.

公共成员

double connect_timeout = 10.0: 连接超时；默认为 10.0。

double read_timeout = 30.0: 读取超时；默认为 30.0。

double total_timeout = 60.0: 总超时；默认为 60.0。

int max_attempts = 3: 最大尝试次数；默认为 3。

enum class fincore::rolling_metric

由 rolling_engine 计算的尾随窗口指标。

取值：

enumerator mean_return: 窗口的年化算术平均值。

enumerator volatility: 窗口的年化样本波动率。

enumerator sharpe: 无风险利率为零时的年化夏普比率。

enumerator max_drawdown: 窗口内最差的峰谷回撤。

enumerator beta: 相对于已对齐基准窗口的未年化 beta。

enum class fincore::transport_error_kind

用于重试决策的传输失败分类。

取值：

enumerator none: 无传输错误。

enumerator connection: 连接级失败；可重试。

enumerator timeout: 请求超时；可重试。

enumerator operating_system: 操作系统传输失败；可重试。

enumerator validation: 请求校验失败；不重试。

enumerator other: 任何其他失败；不重试。

std::pair<dataframe, dataframe> fincore::align_on_common_index(const dataframe &left, std::string_view left_column, const dataframe &right, std::string_view right_column)

返回两个单列帧，仅保留它们共有的时间戳。

结果是在时间戳索引上的内连接。时间戳按 left 的现有顺序取自 left，值按时间戳与 right 匹配；仅出现在一个输入中的时间戳会被丢弃。

参数:

left -- Frame supplying the aligned timestamps and the left column.
left_column -- Double column to keep from left.
right -- Frame supplying the right-hand values.
right_column -- Double column to keep from right.

抛出:

input_error -- If either column is missing, is not a double column, or does not match its frame index length.

返回:

Pair of frames with identical indexes holding the left and right values for the common timestamps.

error_info fincore::alignment_error(std::string message, std::string operation_id = {}, std::string parameter = {}, std::string path = {}, std::string profile = {})

通过 contextual_error() 返回 AlignmentError 负载。

参数:

message -- Human-readable error message.
operation_id -- Operation identifier, if known.
parameter -- Parameter name, if known.
path -- Artifact path, if known.
profile -- Profile name, if known.

返回:

Alignment error payload with code fincore.contract.

std::span<const operation_descriptor> fincore::all_operations()

按领域顺序返回所有已声明的操作。

返回:: View of static storage ordered by attribution, optimization, performance, portfolio, report, risk, simulation, data, factor analysis and metrics. The view is stable for the process lifetime.

std::span<const operation_descriptor> fincore::attribution_operations()

按源顺序返回归因操作。

返回:: View of static descriptor storage; valid for the process lifetime.

std::string fincore::canonical_dataframe_csv(const dataframe &frame)

返回 frame 的规范 CSV 呈现。

第一行为 index，后接按插入顺序排列的列名；其后每行保存 UTC 纳秒索引值和各列值。double 使用与 Python 兼容的浮点格式，但 NaN 为空字段，无穷大表示为 inf 或 -inf；布尔值为 True 或 False；字符串仅在需要时加引号，内嵌引号重复一次。整数列以十进制整数表示。输出以换行结尾。

参数:: frame -- Frame to render.
抛出:: fincore_error -- With category UnsupportedFormatError when the frame cannot be encoded as canonical CSV.
返回:: CSV text.

void fincore::check_dependencies(std::span<const dependency_status> dependencies)

任一列出的依赖项不可用时抛出。

该错误为 DependencyError，其 dependency 字段按输入顺序列出所有不可用的名称，并以 ", " 连接。extra 字段为不可用依赖项中第一个非空的 extra 标签，若都未提供则省略。其消息为 Missing required dependencies: 后接这些名称。

参数:: dependencies -- Dependency records to check.
抛出:: fincore_error -- With category DependencyError when at least one entry is unavailable.

error_info fincore::contextual_error(std::string category, std::string message, std::string operation_id = {}, std::string parameter = {}, std::string path = {}, std::string profile = {})

返回带有操作上下文和代码 fincore.contract 的错误负载。

category 原样使用。可选的上下文值仅在非空时存入 fields 的 operation_id、parameter、path 和 profile 下。

参数:

category -- Source exception class name.
message -- Human-readable error message.
operation_id -- Operation identifier, if known.
parameter -- Parameter name, if known.
path -- Artifact path, if known.
profile -- Profile name, if known.

返回:

Contextual error payload.

error_info fincore::data_alignment_error(std::string message, std::optional<std::int64_t> returns_length = std::nullopt, std::optional<std::int64_t> factor_length = std::nullopt)

返回代码为 fincore.data_alignment 的 DataAlignmentError 负载。

可选的长度以十进制字符串存入 returns_length 和 factor_length。

参数:

message -- Human-readable error message.
returns_length -- Number of return observations, if known.
factor_length -- Number of factor observations, if known.

返回:

Data-alignment error payload.

std::span<const operation_descriptor> fincore::data_operations()

按源顺序返回数据操作。

返回:: View of static descriptor storage; valid for the process lifetime.

std::string fincore::dataframe_content_sha256(const dataframe &frame)

返回 canonical_dataframe_csv() 的小写十六进制 SHA-256。

参数:: frame -- Frame to digest.
抛出:: fincore_error -- With category UnsupportedFormatError when the frame cannot be encoded as canonical CSV.
返回:: 64-character lowercase hexadecimal digest.

error_info fincore::dependency_error(std::string message, std::string dependency = {}, std::string extra = {})

返回代码为 fincore.dependency 的 DependencyError 负载。

dependency 和 extra 仅在非空时存入 fields。

参数:

message -- Human-readable error message.
dependency -- Missing dependency name, if known.
extra -- Extra or feature label associated with the dependency.

返回:

Dependency error payload.

double fincore::ensure_not_nan(double value, std::string_view param_name, std::optional<double> replace_with = std::nullopt)

返回 value；当 value 为 NaN 时返回 replace_with。

参数:

value -- Value to check.
param_name -- Parameter name used in the error message and field.
replace_with -- Replacement used instead of throwing, if supplied.

抛出:

fincore_error -- When value is NaN and replace_with is absent; the payload is a ValidationError for param_name.

返回:

value when it is not NaN, otherwise the supplied replacement.

std::span<const operation_descriptor> fincore::factor_analysis_operations()

按源顺序返回因子分析操作。

返回:: View of static descriptor storage; valid for the process lifetime.

template<typename Function> decltype(auto) fincore::handle_numerical_error(std::string_view operation, Function &&function)

运行数值内核，并将原生数值异常转换为 NumericalError。

已有的 fincore_error 异常原样透传。std::domain_error、std::overflow_error、std::underflow_error、std::invalid_argument 及其他 std::runtime_error 异常会以 numerical_error() 生成的 fincore_error 负载重新抛出，并带上所提供的 operation 标签。内核结果原样返回。

模板参数:

Function -- Callable type invoked with no arguments.

参数:

operation -- Numeric operation label stored in the error payload.
function -- Kernel to invoke.

抛出:

fincore_error -- For the converted native exceptions.

返回:

Whatever function() returns.

error_info fincore::input_contract_error(std::string message, std::string operation_id = {}, std::string parameter = {}, std::string path = {}, std::string profile = {})

通过 contextual_error() 返回 InputContractError 负载。

参数:

message -- Human-readable error message.
operation_id -- Operation identifier, if known.
parameter -- Parameter name, if known.
path -- Artifact path, if known.
profile -- Profile name, if known.

返回:

Input-contract error payload with code fincore.contract.

error_info fincore::insufficient_data_error(std::string message, std::optional<std::int64_t> required_length = std::nullopt, std::optional<std::int64_t> actual_length = std::nullopt)

返回代码为 fincore.insufficient_data 的 InsufficientDataError 负载。

可选的长度以十进制字符串存入 required_length 和 actual_length。

参数:

message -- Human-readable error message.
required_length -- Minimum required observation count, if known.
actual_length -- Observed count, if known.

返回:

Insufficient-data error payload.

error_info fincore::invalid_period_error(std::string period)

返回针对 period 的 InvalidPeriodError 负载。

该负载使用代码 fincore.invalid_period，列出可接受的周期（daily、weekly、monthly、quarterly、yearly），并将 period 和 valid_periods 存入 fields。

参数:: period -- Rejected period label.
返回:: Invalid-period error payload.

error_info fincore::make_error(std::string category, std::string code, std::string message, std::map<std::string, std::string> fields = {}, std::map<std::string, std::string> report = {})

返回由所提供的组成部分构建的结构化错误负载。

不进行任何校验或规范化；fields 和 report 按给定内容存储。

参数:

category -- Source exception class name.
code -- Stable dotted error code.
message -- Human-readable error message.
fields -- Flat string fields.
report -- Diagnostic report entries.

返回:

Error payload with the supplied values.

error_info fincore::make_operation_resolution_error(std::string operation_id)

返回针对未知操作标识符的运行时诊断错误。

该负载使用类别 RuntimeDiagnosticError、代码 fincore.runtime.operation_resolution、运行时类别 resolution_failure、由 unknown operation_id: 后接标识符构成的消息，以及指向操作目录的修复建议。

参数:: operation_id -- Unknown operation identifier.
返回:: Runtime diagnostic payload for the resolution failure.

dataframe fincore::make_series(std::vector<timestamp> index, std::string_view column_name, std::vector<double> values)

返回由索引和 double 值构建的单列帧。

列加载时不填充 NaN，因此索引和列大小保持与输入大小相等。

参数:

index -- Timestamps for the rows, in the caller's order.
column_name -- Name of the double column; must not be empty.
values -- Values parallel to index.

抛出:

input_error -- If column_name is empty or the two input vectors have different sizes.

返回:

Frame whose index is index and whose only column is column_name.

std::span<const operation_descriptor> fincore::metrics_operations()

按源顺序返回指标操作。

返回:: View of static descriptor storage; valid for the process lifetime.

error_info fincore::missing_data_error(std::string message, std::string missing_field = {})

返回代码为 fincore.missing_data 的 MissingDataError 负载。

missing_field 仅在非空时存入 fields。

参数:

message -- Human-readable error message.
missing_field -- Name of the missing field, if known.

返回:

Missing-data error payload.

error_info fincore::numerical_convergence_error(std::string message, std::string operation_id = {}, std::string parameter = {}, std::string path = {}, std::string profile = {})

通过 contextual_error() 返回 NumericalConvergenceError 负载。

参数:

message -- Human-readable error message.
operation_id -- Operation identifier, if known.
parameter -- Parameter name, if known.
path -- Artifact path, if known.
profile -- Profile name, if known.

返回:

Numerical-convergence error payload with code fincore.contract.

error_info fincore::numerical_error(std::string message, std::string operation = {})

返回代码为 fincore.numerical 的 NumericalError 负载。

operation 仅在非空时存入 fields。

参数:

message -- Human-readable error message.
operation -- Numeric operation label, if known.

返回:

Numerical error payload.

std::span<const operation_descriptor> fincore::optimization_operations()

按源顺序返回优化操作。

返回:: View of static descriptor storage; valid for the process lifetime.

std::span<const operation_descriptor> fincore::performance_operations()

按源顺序返回绩效操作。

返回:: View of static descriptor storage; valid for the process lifetime.

std::span<const operation_descriptor> fincore::portfolio_operations()

按源顺序返回投资组合操作。

返回:: View of static descriptor storage; valid for the process lifetime.

std::span<const operation_descriptor> fincore::report_operations()

按源顺序返回报告操作。

返回:: View of static descriptor storage; valid for the process lifetime.

std::span<const double> fincore::require_double_column(const dataframe &frame, std::string_view column_name)

返回 frame 中指定名称的 double 列的视图。

参数:

frame -- Frame to inspect.
column_name -- Name of the required double column.

抛出:

input_error -- If column_name is empty, the column is absent, the column is not of type double, or its size differs from the index size.

返回:

View over the column values; it references the frame's storage.

error_info fincore::resource_lifecycle_error(std::string message, std::string operation_id = {}, std::string parameter = {}, std::string path = {}, std::string profile = {})

通过 contextual_error() 返回 ResourceLifecycleError 负载。

参数:

message -- Human-readable error message.
operation_id -- Operation identifier, if known.
parameter -- Parameter name, if known.
path -- Artifact path, if known.
profile -- Profile name, if known.

返回:

Resource-lifecycle error payload with code fincore.contract.

error_info fincore::result_contract_error(std::string message, std::string operation_id = {}, std::string parameter = {}, std::string path = {}, std::string profile = {})

通过 contextual_error() 返回 ResultContractError 负载。

参数:

message -- Human-readable error message.
operation_id -- Operation identifier, if known.
parameter -- Parameter name, if known.
path -- Artifact path, if known.
profile -- Profile name, if known.

返回:

Result-contract error payload with code fincore.contract.

std::span<const operation_descriptor> fincore::risk_operations()

按源顺序返回风险操作。

返回:: View of static descriptor storage; valid for the process lifetime.

error_info fincore::runtime_diagnostic_error(std::string message, std::string runtime_category, std::string operation_id = {}, std::string capability_id = {}, std::map<std::string, std::string> details = {}, std::string remediation = {})

返回代码为 fincore.runtime.diagnostic 的 RuntimeDiagnosticError 负载。

runtime_category 始终存入 fields；operation_id、capability_id 和 remediation 仅在非空时存入。details 成为诊断报告。

参数:

message -- Human-readable error message.
runtime_category -- Runtime classification, such as resolution_failure.
operation_id -- Operation identifier, if known.
capability_id -- Capability identifier, if known.
details -- Diagnostic report entries.
remediation -- Suggested remediation text, if known.

返回:

Runtime diagnostic payload.

double fincore::safe_divide(double numerator, double denominator, double default_value = std::numeric_limits<double>::quiet_NaN())

返回 numerator / denominator；当分母为零时返回 default_value。

参数:

numerator -- Dividend.
denominator -- Divisor; zero selects default_value.
default_value -- Value returned for a zero denominator; defaults to NaN.

返回:

Quotient, or default_value for a zero denominator.

double fincore::safe_sqrt(double value, double default_value = std::numeric_limits<double>::quiet_NaN())

返回 value 的平方根；当 value 为负时返回 default_value。

参数:

value -- Input value.
default_value -- Value returned for a negative input; defaults to NaN.

返回:

Square root, or default_value when value < 0.

std::span<const operation_descriptor> fincore::simulation_operations()

按源顺序返回模拟操作。

返回:: View of static descriptor storage; valid for the process lifetime.

error_info fincore::unsupported_format_error(std::string message, std::string format = {})

返回代码为 fincore.unsupported_format 的 UnsupportedFormatError 负载。

format 仅在非空时存入 fields。

参数:

message -- Human-readable error message.
format -- Rejected format label, if known.

返回:

Unsupported-format error payload.

timestamp fincore::utc_timestamp(int year, unsigned month = 1, unsigned day = 1, unsigned hour = 0, unsigned minute = 0, unsigned second = 0, unsigned nanosecond = 0)

返回日历日期和时间的 UTC Unix 纪元时间戳。

各分量按 UTC 解释。月和日默认为 1 月 1 日，时间分量默认为午夜。亚秒精度以纳秒承载。

参数:

year -- Calendar year supported by std::chrono::year.
month -- Month in [1, 12]; defaults to January.
day -- Day of month in [1, 31]; defaults to 1.
hour -- Hour in [0, 23]; defaults to 0.
minute -- Minute in [0, 59]; defaults to 0.
second -- Second in [0, 59]; defaults to 0.
nanosecond -- Nanosecond in [0, 999999999]; defaults to 0.

抛出:

input_error -- If a component is out of range, the calendar date does not exist, or the timestamp is outside the representable int64 range.

返回:

Signed nanoseconds since 1970-01-01T00:00:00Z.

int fincore::utc_year(timestamp value) noexcept

返回包含 value 的 UTC 日历年。

参数:: value -- Signed nanosecond timestamp since the Unix epoch.
返回:: UTC calendar year, including years before 1970.

error_info fincore::validation_error(std::string message, std::string param_name = {}, std::string value = {})

返回代码为 fincore.validation 的 ValidationError 负载。

param_name 和 value 仅在非空时存入 fields。

参数:

message -- Human-readable error message.
param_name -- Offending parameter name, if known.
value -- Rejected value rendered as text, if known.

返回:

Validation error payload.

std::string_view fincore::version() noexcept

以便于持有的视图返回锁定的 oracle 版本。

返回:: View of pinned_version_string, valid for the process lifetime.

using fincore::dataframe = hmdf::StdDataFrame<timestamp>: 以时间戳为索引的列式帧，由 hmdf::StdDataFrame 支撑。

using fincore::timestamp = std::int64_t: 自 Unix 纪元起以 UTC 纳秒表示的有符号时间戳。

constexpr int fincore::data_snapshot_schema_version = 1: 写入数据快照清单的 schema 版本。

constexpr int fincore::pinned_version_major = 0

锁定的 Python oracle 身份（fincore.version，位于 3e9ef205ef2023f92e89fddd1052d46b16429c64）。

锁定的主版本号。

constexpr int fincore::pinned_version_minor = 5: 锁定的次版本号。

constexpr int fincore::pinned_version_patch = 2: 锁定的修订版本号。

constexpr const char *fincore::pinned_version_string = "0.5.2.dev0": 锁定的 oracle 版本文本。

constexpr int fincore::version_major = 0

保留自当前 C4 基线的原生库版本。

锁定的 Python oracle 版本在下方单独暴露，以便已安装使用方的元数据检查可以与冻结的 Python 锁定版本比较，而无需假装原生 ABI 版本发生了变化。原生主版本号。

constexpr int fincore::version_minor = 1: 原生次版本号。

constexpr int fincore::version_patch = 0: 原生修订版本号。

constexpr const char *fincore::version_string = "0.1.0": 原生版本。