error API

Luna-Flow/linear-algebra/error は、このリポジトリのすべての検査付き API が返すエラー値 LinearAlgebraError と、その分類 LinearAlgebraErrorKind を定義します。呼び出し側は種類（または 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_* 述語で判定してください。

種類	意味	発生元
`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 は二つの種類を構造的に比較し、== の実体です。

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

二つの ArithmeticFailure は、包んでいる ArithmeticError の値が等しいときに等しくなります。

`LinearAlgebraError`

LinearAlgebraError は機械的に判定できる種類と、人が読むためのメッセージを組にしたものです。

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

両方のフィールドは他のパッケージから読み取れます。この型は Eq を実装しますが、Show も Debug も実装しないので、エラーそのものではなく err.message を表示し、inspect ではなく == や述語で比較してください。

`LinearAlgebraError::equal`

LinearAlgebraError::equal は種類とメッセージを比較し、== の実体です。

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

種類が同じでもメッセージが異なる二つのエラーは等しくありません。メッセージが重要でないときは種類を比較してください（a.kind == b.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" です。スカラーエラー自身のメッセージは種類の中に保持されます。

///|
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")
  }
}

判定メソッド

各述語は、エラーが対応する種類を持つときにちょうど 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`（メソッド形式。インターフェースからは隠されている）	`!=` 演算子