error API

Luna-Flow/linear-algebra/error 定义了 LinearAlgebraError（本仓库每个受检 API 返回的错误值）及其分类 LinearAlgebraErrorKind。调用者根据 kind（或某个 is_* 判断方法）进行分支，消息仅用于诊断。

源码：src/error/error.mbt。受检 API 为何返回该值见 error 设计。

导入

///|
import {
  "Luna-Flow/linear-algebra/error" @la_error,
}

示例使用别名 @la_error，以避免与 MoonBit 内置的 Error 相关名称冲突。

类型

`LinearAlgebraErrorKind`

LinearAlgebraErrorKind 对失败进行分类。

pub enum LinearAlgebraErrorKind {
  DimensionMismatch
  IndexOutOfBounds
  NegativeDimension
  InvalidLength
  RaggedRows
  NonSquareMatrix
  NegativeExponent
  EmptyMatrix
  SingularMatrix
  NonConvergence
  ArithmeticFailure(@arithmetic.ArithmeticError)
} derive(Eq)

该枚举是 pub 的：其他包可以读取并 match 它的值，但不能构造它们，即便是用于 kind == SingularMatrix 这样的比较也不行。请使用下文 LinearAlgebraError 的构造函数创建错误，并用 match 或 is_* 判断方法检查 kind。

种类	含义	产生方
`DimensionMismatch`	操作数形状不兼容	`@immut.Matrix::matmul`, `@mutable.Matrix::mul_vec`
`IndexOutOfBounds`	行、列或元素索引超出形状范围	`container` 适配器
`NegativeDimension`	请求的形状或长度为负	`container` 构建函数与算法
`InvalidLength`	扁平缓冲区长度错误	保留；本版本不会产生
`RaggedRows`	嵌套的各行长度不同	保留；本版本不会产生
`NonSquareMatrix`	该运算需要方阵	`trace`, `determinant`, `pow`, `inverse`, `is_invertible`, `matrix_power`
`NegativeExponent`	矩阵幂的指数为负	`pow`, `matrix_power`
`EmptyMatrix`	该运算至少需要一个元素	`mean`, `variance`, `std_dev`, `max_element`, `min_element`
`SingularMatrix`	矩阵在容差范围内奇异	`@mutable.Matrix::inverse`
`NonConvergence`	迭代未收敛	保留；本版本不会产生
`ArithmeticFailure(e)`	标量运算以 `e` 失败	保留给调用者使用；本版本不会产生

`LinearAlgebraErrorKind::equal`

LinearAlgebraErrorKind::equal 按结构比较两个 kind；它是 == 的底层实现。

pub fn LinearAlgebraErrorKind::equal(Self, Self) -> Bool

当两个 ArithmeticFailure kind 所包装的 ArithmeticError 值相等时，它们相等。

`LinearAlgebraError`

LinearAlgebraError 将适合程序判断的 kind 与适合人阅读的消息组合在一起。

pub struct LinearAlgebraError {
  kind : LinearAlgebraErrorKind
  message : String
} derive(Eq)

两个字段都可从其他包读取。该类型实现了 Eq，但没有实现 Show 和 Debug，因此请打印 err.message 而不是错误本身，并用 == 或判断方法而不是 inspect 来比较错误。

`LinearAlgebraError::equal`

LinearAlgebraError::equal 比较 kind 和消息；它是 == 的底层实现。

pub fn LinearAlgebraError::equal(Self, Self) -> Bool

kind 相同但消息不同的两个错误并不相等。消息无关紧要时，请比较 kind（a.kind == b.kind）。

构造函数

每个构造函数都用给定消息构建一种 kind 的错误。本仓库的库代码使用它们；你自己的受检辅助函数也可以使用。

`LinearAlgebraError::dimension_mismatch`

LinearAlgebraError::dimension_mismatch(message) 构建 DimensionMismatch 错误。

pub fn LinearAlgebraError::dimension_mismatch(String) -> Self

`LinearAlgebraError::index_out_of_bounds`

LinearAlgebraError::index_out_of_bounds(message) 构建 IndexOutOfBounds 错误。

pub fn LinearAlgebraError::index_out_of_bounds(String) -> Self

`LinearAlgebraError::negative_dimension`

LinearAlgebraError::negative_dimension(message) 构建 NegativeDimension 错误。

pub fn LinearAlgebraError::negative_dimension(String) -> Self

`LinearAlgebraError::invalid_length`

LinearAlgebraError::invalid_length(message) 构建 InvalidLength 错误。

pub fn LinearAlgebraError::invalid_length(String) -> Self

`LinearAlgebraError::ragged_rows`

LinearAlgebraError::ragged_rows(message) 构建 RaggedRows 错误。

pub fn LinearAlgebraError::ragged_rows(String) -> Self

`LinearAlgebraError::non_square_matrix`

LinearAlgebraError::non_square_matrix(message) 构建 NonSquareMatrix 错误。

pub fn LinearAlgebraError::non_square_matrix(String) -> Self

`LinearAlgebraError::negative_exponent`

LinearAlgebraError::negative_exponent(message) 构建 NegativeExponent 错误。

pub fn LinearAlgebraError::negative_exponent(String) -> Self

`LinearAlgebraError::empty_matrix`

LinearAlgebraError::empty_matrix(message) 构建 EmptyMatrix 错误。

pub fn LinearAlgebraError::empty_matrix(String) -> Self

`LinearAlgebraError::singular_matrix`

LinearAlgebraError::singular_matrix(message) 构建 SingularMatrix 错误。

pub fn LinearAlgebraError::singular_matrix(String) -> Self

`LinearAlgebraError::non_convergence`

LinearAlgebraError::non_convergence(message) 构建 NonConvergence 错误。

pub fn LinearAlgebraError::non_convergence(String) -> Self

`LinearAlgebraError::arithmetic_failure`

LinearAlgebraError::arithmetic_failure(error) 将标量 ArithmeticError 包装为 ArithmeticFailure 错误。

pub fn LinearAlgebraError::arithmetic_failure(@arithmetic.ArithmeticError) -> Self

消息始终为 "Arithmetic operation failed"；标量错误自身的消息保留在 kind 之中。

///|
test "constructors set kind and message" {
  let err = @la_error.LinearAlgebraError::singular_matrix("pivot vanished")
  inspect(err.message, content="pivot vanished")
  let label = match err.kind {
    SingularMatrix => "singular"
    _ => "other"
  }
  inspect(label, content="singular")
  let scalar = @lf_arith.ArithmeticError::division_by_zero("1 / 0")
  let wrapped = @la_error.LinearAlgebraError::arithmetic_failure(scalar)
  inspect(wrapped.message, content="Arithmetic operation failed")
  match wrapped.kind {
    ArithmeticFailure(inner) => inspect(inner.message, content="1 / 0")
    _ => fail("expected an arithmetic failure")
  }
}

判断方法

每个判断方法在且仅在错误具有对应 kind 时返回 true。它们让调用者无需导入该枚举即可进行分支。

`LinearAlgebraError::is_dimension_mismatch`

is_dimension_mismatch 检查是否为 DimensionMismatch。

pub fn LinearAlgebraError::is_dimension_mismatch(Self) -> Bool

`LinearAlgebraError::is_index_out_of_bounds`

is_index_out_of_bounds 检查是否为 IndexOutOfBounds。

pub fn LinearAlgebraError::is_index_out_of_bounds(Self) -> Bool

`LinearAlgebraError::is_negative_dimension`

is_negative_dimension 检查是否为 NegativeDimension。

pub fn LinearAlgebraError::is_negative_dimension(Self) -> Bool

`LinearAlgebraError::is_invalid_length`

is_invalid_length 检查是否为 InvalidLength。

pub fn LinearAlgebraError::is_invalid_length(Self) -> Bool

`LinearAlgebraError::is_ragged_rows`

is_ragged_rows 检查是否为 RaggedRows。

pub fn LinearAlgebraError::is_ragged_rows(Self) -> Bool

`LinearAlgebraError::is_non_square_matrix`

is_non_square_matrix 检查是否为 NonSquareMatrix。

pub fn LinearAlgebraError::is_non_square_matrix(Self) -> Bool

`LinearAlgebraError::is_negative_exponent`

is_negative_exponent 检查是否为 NegativeExponent。

pub fn LinearAlgebraError::is_negative_exponent(Self) -> Bool

`LinearAlgebraError::is_empty_matrix`

is_empty_matrix 检查是否为 EmptyMatrix。

pub fn LinearAlgebraError::is_empty_matrix(Self) -> Bool

`LinearAlgebraError::is_singular_matrix`

is_singular_matrix 检查是否为 SingularMatrix。

pub fn LinearAlgebraError::is_singular_matrix(Self) -> Bool

`LinearAlgebraError::is_non_convergence`

is_non_convergence 检查是否为 NonConvergence。

pub fn LinearAlgebraError::is_non_convergence(Self) -> Bool

`LinearAlgebraError::is_arithmetic_failure`

is_arithmetic_failure 检查是否为 ArithmeticFailure(_)，无论其包装的是什么错误。

pub fn LinearAlgebraError::is_arithmetic_failure(Self) -> Bool

在真实受检调用返回的错误上使用这些判断方法：

///|
test "predicates classify checked failures" {
  let rect = @mutable.Matrix::from_2d_array([[1.0, 2.0, 3.0]])
  match rect.determinant() {
    Err(e) => inspect(e.is_non_square_matrix(), content="true")
    Ok(_) => fail("a 1x3 matrix has no determinant")
  }
  let singular = @mutable.Matrix::from_2d_array([[1.0, 2.0], [2.0, 4.0]])
  match singular.inverse() {
    Err(e) => inspect(e.is_singular_matrix(), content="true")
    Ok(_) => fail("the matrix is singular")
  }
  let empty : @mutable.Matrix[Double] = @mutable.Matrix::new(0, 3, 0.0)
  match empty.mean() {
    Err(e) => inspect(e.is_empty_matrix(), content="true")
    Ok(_) => fail("an empty matrix has no mean")
  }
}

已弃用

项	替代方案
`LinearAlgebraError::not_equal`、`LinearAlgebraErrorKind::not_equal`（方法形式，已从接口中隐藏）	`!=` 运算符