structured-asn1 0.4.3

//! Immutable, independently retained UTF-8 over an existing accounted buffer.

use super::{HashWork, Memory, MemoryError, OwnedVec, Work, allocator::ValidatedText};
use core::{
    borrow::Borrow,
    fmt,
    hash::{Hash, Hasher},
    ops::Deref,
    str::Utf8Error,
};

/// Why an existing byte buffer could not become immutable UTF-8 text.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextErrorKind {
    /// Work admission refused before UTF-8 validation began.
    Resource(MemoryError),
    /// Admitted validation found invalid UTF-8, relative to the original bytes.
    Utf8(Utf8Error),
}

/// Failed text construction retaining the unchanged original buffer.
///
/// Consumed work is not refunded. Storage remains charged until the recovered
/// buffer or this error is dropped; failure never copies or reallocates it.
pub struct TextError<W: Work = Memory> {
    kind: TextErrorKind,
    bytes: OwnedVec<u8, W>,
}

impl<W: Work> TextError<W> {
    /// The original resource or UTF-8 cause, without inspecting bytes.
    #[must_use]
    pub fn kind(&self) -> TextErrorKind {
        self.kind
    }

    /// Recovers the original pointer, initialized bytes, capacity and account.
    #[must_use]
    pub fn into_bytes(self) -> OwnedVec<u8, W> {
        self.bytes
    }
}

impl<W: Work> fmt::Debug for TextError<W> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("TextError")
            .field("kind", &self.kind)
            .finish_non_exhaustive()
    }
}

/// Single-owner immutable UTF-8 retaining its original capacity charge.
///
/// Construction from bytes validates once under their execution before closing
/// mutable access. Construction from a `str` copies its already validated bytes.
/// No reference count, extra allocation or unsafe thread-safety implementation
/// is introduced. The default owned [`Memory`] form is `Send + Sync`; scoped
/// forms retain their execution's actual lifetime and thread-safety bounds.
/// Views are O(1); callers fund their own hashing, equality, formatting and
/// traversal. [`HashWork`] supports paid [`super::OwnedMap`] lookups by `str`.
///
/// ```
/// use std::sync::Arc;
/// use structured_asn1::memory::{Memory, MemoryAccount, OwnedText};
/// let memory = Memory::new(Arc::new(MemoryAccount::new(1024, 1024)));
/// let mut bytes = memory.vector();
/// bytes.try_extend_from_slice("retained 🦀".as_bytes())?;
/// let text = OwnedText::from_utf8(bytes).unwrap();
/// assert_eq!(text.as_str(), "retained 🦀");
/// drop(text);
/// assert_eq!(memory.used(), 0);
/// # Ok::<(), structured_asn1::memory::MemoryError>(())
/// ```
///
/// The invariant cannot be invalidated while a string view exists:
/// ```compile_fail
/// use structured_asn1::memory::OwnedText;
/// fn invalidate(text: OwnedText) {
///     let view = text.as_str();
///     let mut bytes = text.into_bytes();
///     bytes[0] = 0xff;
///     println!("{view}");
/// }
/// ```
pub struct OwnedText<W: Work = Memory> {
    text: ValidatedText<W>,
}

impl<W: Work> OwnedText<W> {
    /// Validates and takes ownership without copying or changing capacity.
    ///
    /// Admission pays the full initialized byte length before the first byte is
    /// examined, against the vector's original local and aggregate ceilings.
    /// Both failure classes return the unchanged vector through [`TextError`].
    pub fn from_utf8(bytes: OwnedVec<u8, W>) -> Result<Self, TextError<W>> {
        ValidatedText::from_utf8(bytes)
            .map(|text| Self { text })
            .map_err(|(kind, bytes)| TextError { kind, bytes })
    }

    /// Copies valid UTF-8 using the existing accounted allocation/copy path.
    /// No validation scan is needed because the input is already a `str`.
    pub fn try_from_str(text: &str, execution: &W) -> Result<Self, MemoryError> {
        Ok(Self {
            text: ValidatedText::from_str(text, execution)?,
        })
    }

    /// The original account retaining this allocation.
    #[must_use]
    pub fn memory(&self) -> &Memory {
        self.text.bytes().memory()
    }

    /// The initialized UTF-8 byte length, without traversal.
    #[must_use]
    pub fn len(&self) -> usize {
        self.text.bytes().len()
    }

    /// Whether the text contains no bytes.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.text.bytes().is_empty()
    }

    /// Allocated byte capacity, including retained spare capacity.
    #[must_use]
    pub fn capacity(&self) -> usize {
        self.text.bytes().capacity()
    }

    /// Borrows immutable initialized bytes; callers admit subsequent traversal.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        self.text.bytes()
    }

    /// Borrows validated immutable UTF-8 in O(1), without scanning or copying.
    #[must_use]
    pub fn as_str(&self) -> &str {
        self.text.as_str()
    }

    /// Finishes construction by moving the existing buffer's account keeper.
    /// No copy, validation, allocation, work or capacity change occurs.
    #[must_use]
    pub fn into_owned(self) -> OwnedText {
        OwnedText {
            text: self.text.into_owned(),
        }
    }

    /// Recovers mutable bytes by consuming the text, ending its UTF-8 invariant.
    /// Existing borrowed views must have ended before this move is possible.
    #[must_use]
    pub fn into_bytes(self) -> OwnedVec<u8, W> {
        self.text.into_bytes()
    }
}

impl<W: Work> fmt::Debug for OwnedText<W> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.as_str().fmt(f)
    }
}

impl<W: Work> Deref for OwnedText<W> {
    type Target = str;
    fn deref(&self) -> &str {
        self.as_str()
    }
}

impl<W: Work> Borrow<str> for OwnedText<W> {
    fn borrow(&self) -> &str {
        self.as_str()
    }
}

impl<W: Work> AsRef<str> for OwnedText<W> {
    fn as_ref(&self) -> &str {
        self.as_str()
    }
}

impl<W: Work> fmt::Display for OwnedText<W> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

impl<W: Work, V: Work> PartialEq<OwnedText<V>> for OwnedText<W> {
    fn eq(&self, other: &OwnedText<V>) -> bool {
        self.as_str() == other.as_str()
    }
}

impl<W: Work> Eq for OwnedText<W> {}

impl<W: Work> Hash for OwnedText<W> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.as_str().hash(state);
    }
}

impl<W: Work> HashWork for OwnedText<W> {
    fn hash_work(&self) -> Result<u64, MemoryError> {
        (self.len() as u64)
            .checked_add(1)
            .ok_or(MemoryError::WorkExceeded)
    }
}