Enum LayoutError 

#[non_exhaustive]
pub enum LayoutError {
    NonContiguous {
        operation: String,
        layout_type: String,
    },
    DimensionMismatch {
        expected_dims: String,
        actual_dims: String,
        operation: String,
    },
    BorrowedDataMutation {
        operation: String,
        reason: String,
    },
    IncompatibleFormat {
        operation: String,
        reason: String,
    },
    ChannelCountUnsupported {
        operation: String,
        required: ChannelRequirement,
        actual: u32,
        help: String,
    },
    ShapeError {
        operation: String,
        source: ShapeError,
    },
    InvalidOperation(String, String),
}

Errors related to memory layout, array structure, and data organization.

Purpose

Covers failures related to array contiguity, dimension mismatches, borrowed data mutation attempts, channel-count preconditions, and other structural issues that arise from the ndarray-backed storage of audio samples.

Intended Usage

Return these errors when an operation’s structural preconditions are not met — for example, when a mono-only function receives multi-channel input (use ChannelCountUnsupported), or when an in-place operation is attempted on borrowed (non-owned) data.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

NonContiguous

Array data is not contiguous in memory when contiguous layout is required.

Fields

operation: String

The operation that requires contiguous layout.

layout_type: String

Description of the actual layout (e.g., “strided”, “non-standard order”).

DimensionMismatch

Array dimensions don’t match expected values for the operation.

Fields

expected_dims: String

Description of expected dimensions.

actual_dims: String

Description of actual dimensions.

operation: String

The operation that has dimension requirements.

BorrowedDataMutation

Attempted to modify borrowed audio data that should be immutable.

Fields

operation: String

The operation that attempted to modify borrowed data.

reason: String

Explanation of why modification is not allowed.

IncompatibleFormat

Data size or format is incompatible with the operation requirements.

Fields

operation: String

The operation with format requirements.

reason: String

Detailed explanation of the format incompatibility.

ChannelCountUnsupported

An operation requires a specific channel count that the input does not have.

This is the structured home for the recurring “X is only supported for mono audio” precondition. Callers can match on required/actual rather than parsing prose.

Fields

operation: String

The operation with the channel-count precondition.

required: ChannelRequirement

The channel layout the operation requires.

actual: u32

The number of channels actually supplied.

help: String

Actionable recovery hint (depends on required).

ShapeError

A shape-related error occurred during array operations.

Carries the originating ndarray::ShapeError as a source so the full cause chain is preserved rather than flattened to a string.

Fields

operation: String

The operation that encountered the shape error.

source: ShapeError

The underlying ndarray shape error.

InvalidOperation(String, String)

Error indicating an invalid operation on audio data.

Occurs when attempting an operation that violates preconditions that are not better expressed by the more specific variants above.

Implementations

impl LayoutError

pub fn shape_error<O>(operation: O, source: ShapeError) -> Self

where O: ToString,

Creates a LayoutError::ShapeError preserving the originating error.

Arguments

• operation — Name of the operation that encountered the shape error.
• source — The underlying ndarray::ShapeError.

Returns

A LayoutError::ShapeError carrying source as its cause.

pub fn channel_count_unsupported<O>( operation: O, required: ChannelRequirement, actual: u32, ) -> Self

where O: ToString,

Creates a LayoutError::ChannelCountUnsupported error.

This is the canonical home for channel-count preconditions such as the recurring “only supported for mono audio” failure.

Arguments

• operation — Name of the operation with the precondition.
• required — The channel layout the operation requires.
• actual — The number of channels actually supplied.

Returns

A LayoutError::ChannelCountUnsupported variant with a help hint derived from required.

Examples

use audio_samples::{ChannelRequirement, LayoutError};

let err = LayoutError::channel_count_unsupported("stft", ChannelRequirement::Mono, 2);
assert!(matches!(err, LayoutError::ChannelCountUnsupported { .. }));

pub fn invalid_operation<S>(operation: S, reason: S) -> Self

where S: ToString,

Creates a LayoutError::InvalidOperation error.

Use this when a valid operation is called in a context where it cannot proceed and no more specific variant applies.

Arguments

• operation — Name of the operation that was called in an invalid context.
• reason — Human-readable explanation of why the operation cannot proceed.

Returns

LayoutError::InvalidOperation(operation.to_string(), reason.to_string()).

Examples

use audio_samples::LayoutError;

let err = LayoutError::invalid_operation("stft", "requires mono audio");
assert!(matches!(err, LayoutError::InvalidOperation(_, _)));

pub fn borrowed_mutation<O, R>(operation: O, reason: R) -> Self

where O: ToString, R: ToString,

Creates a LayoutError::BorrowedDataMutation error.

Use this when an in-place or mutating operation is attempted on audio data that is held via an immutable borrow and therefore cannot be modified.

Arguments

• operation — Name of the operation that attempted to modify borrowed data.
• reason — Human-readable explanation of why modification is not allowed.

Returns

A LayoutError::BorrowedDataMutation variant.

Examples

use audio_samples::LayoutError;

let err = LayoutError::borrowed_mutation("normalize_in_place", "audio data is borrowed");
assert!(matches!(err, LayoutError::BorrowedDataMutation { .. }));

pub fn dimension_mismatch<E, A, O>(expected: E, actual: A, operation: O) -> Self

where E: ToString, A: ToString, O: ToString,

Creates a LayoutError::DimensionMismatch error.

Use this when an array or buffer has the wrong number of dimensions or an unexpected shape for the operation being performed.

Arguments

• expected — Description of the expected dimensions (e.g. "(1, 1024)").
• actual — Description of the actual dimensions received (e.g. "(2, 1024)").
• operation — Name of the operation that has the dimension requirement.

Returns

A LayoutError::DimensionMismatch variant.

Examples

use audio_samples::LayoutError;

let err = LayoutError::dimension_mismatch("(1, 1024)", "(2, 1024)", "mono_fft");
assert!(matches!(err, LayoutError::DimensionMismatch { .. }));

Trait Implementations

impl Clone for LayoutError

fn clone(&self) -> LayoutError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LayoutError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Diagnostic for LayoutError

fn code(&self) -> Option<Box<dyn Display + '_>>

Unique diagnostic code that can be used to look up more information about this Diagnostic. Ideally also globally unique, and documented in the toplevel crate’s documentation for easy searching. Rust path format (foo::bar::baz) is recommended, but more classic codes like E0123 or enums will work just fine.

fn help(&self) -> Option<Box<dyn Display + '_>>

Additional help text related to this Diagnostic. Do you have any advice for the poor soul who’s just run into this issue?

fn url(&self) -> Option<Box<dyn Display + '_>>

URL to visit for a more detailed explanation/help about this Diagnostic.

fn severity(&self) -> Option<Severity>

Diagnostic severity. This may be used by ReportHandlers to change the display format of this diagnostic.

fn source_code(&self) -> Option<&dyn SourceCode>

Source code to apply this Diagnostic’s Diagnostic::labels to.

fn labels(&self) -> Option<Box<dyn Iterator<Item = LabeledSpan> + '_>>

Labels to apply to this Diagnostic’s Diagnostic::source_code

fn related<'a>( &'a self, ) -> Option<Box<dyn Iterator<Item = &'a dyn Diagnostic> + 'a>>

Additional related Diagnostics.

fn diagnostic_source(&self) -> Option<&dyn Diagnostic>

The cause of the error.

impl Display for LayoutError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for LayoutError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<LayoutError> for AudioSampleError

fn from(source: LayoutError) -> Self

Converts to this type from the input type.