data_bucket 0.7.11

DataBucket is container for WorkTable's data
Documentation
//! What this crate can refuse on.
use alloc::string::String;
use core::fmt::{Display, Formatter, Result as FmtResult};

use crate::page::PageId;

/// The result of anything in this crate that can fail.
pub type Result<T> = core::result::Result<T, Error>;

/// A refusal, with the numbers that justify it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Error {
    /// The runtime never interprets another page format as the current one.
    UnsupportedVersion { found: u32, expected: u32 },
    /// A write's length does not match the link it was given.
    LinkLengthMismatch {
        /// The length the link reserves.
        expected: u32,
        /// The length the caller supplied.
        found: usize,
    },
    /// A link's range runs past the end of the page it points into.
    LinkOutOfBounds {
        /// Where the link starts.
        offset: u32,
        /// How far it runs.
        length: u32,
        /// How much the page holds.
        capacity: usize,
    },
    /// A page's contents do not fit the page.
    PageOverflow {
        /// The page whose write is over budget.
        page: PageId,
        /// Bytes the write needs.
        needed: usize,
        /// Bytes available.
        capacity: usize,
    },
    /// Bytes that should have been a structure were not one.
    Corrupt {
        /// What failed to parse.
        what: &'static str,
    },
    /// A value would not archive.
    Encode,
    /// The file would not answer.
    Io {
        /// What kind of failure the file reported.
        kind: nagoya::io::ErrorKind,
    },
    /// A change-data event arrived that this page cannot apply.
    UnapplicableEvent,
    /// An unclassified failure.
    Message(String),
}

impl Display for Error {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
        match self {
            Self::UnsupportedVersion { found, expected } => write!(
                formatter,
                "unsupported page format v{found}; this build requires v{expected}; recreate the store or convert it with an explicit migration tool"
            ),
            Self::LinkLengthMismatch { expected, found } => write!(
                formatter,
                "a {found} byte write does not match its {expected} byte link"
            ),
            Self::LinkOutOfBounds {
                offset,
                length,
                capacity,
            } => write!(
                formatter,
                "a link at {offset} running {length} bytes leaves a {capacity} byte page"
            ),
            Self::PageOverflow {
                page,
                needed,
                capacity,
            } => write!(
                formatter,
                "page {page:?} needs {needed} bytes of a {capacity} byte page"
            ),
            Self::Corrupt { what } => write!(formatter, "torn or corrupt {what}"),
            Self::Encode => write!(formatter, "a value would not archive"),
            Self::Io { kind } => write!(formatter, "the file failed: {kind:?}"),
            Self::UnapplicableEvent => write!(
                formatter,
                "events of `SplitNode`, `CreateNode` or `RemoveNode` cannot be applied to a page"
            ),
            Self::Message(m) => write!(formatter, "{m}"),
        }
    }
}

impl core::error::Error for Error {}

impl From<nagoya::io::Error> for Error {
    fn from(error: nagoya::io::Error) -> Self {
        Self::Io { kind: error.kind() }
    }
}

impl From<rkyv::rancor::Error> for Error {
    fn from(_: rkyv::rancor::Error) -> Self {
        Self::Encode
    }
}

impl From<crate::page::PageOverflowError> for Error {
    fn from(error: crate::page::PageOverflowError) -> Self {
        Self::PageOverflow {
            page: error.page_id,
            needed: error.data_length,
            capacity: error.capacity,
        }
    }
}