index.nct

//! Borrowed UTF-8 text observation, search, views, and materialization.
//!
//! `str` is a compiler built-in unsized type, but its public methods are
//! ordinary Nocter source. Only the narrow representation query below is a
//! trusted primitive. Allocating conveniences are isolated from borrowed
//! algorithms in `owned.nct`.

use /iter.{Iterator, ViewIter}
use /mem.TryAllocator
use /string.String
use /vec.Vec
see ./text.nct
see ./views.nct
see ./owned.nct
see ./scalar_iteration.nct
see ./casing.nct
see ./casing_tests.nct
see ./trim.nct
see ./unicode_trim.nct
see ./transform.nct
see ./transformation_tests.nct
see ./views_tests.nct

/// Borrowed UTF-8 text with storage owned elsewhere.
pub primitive type str

/// Allocation-free iterator over separator-delimited borrowed components.
pub struct SplitIter

/// Allocation-free iterator over LF- or CRLF-terminated borrowed lines.
pub struct LinesIter

/// Allocation-free iterator over Unicode scalar values.
pub struct Chars

construct SplitIter {
    /// Creates an allocation-free iterator over `text` separated by `separator`.
    pub noalloc func new(
        text: &str,
        separator: &str,
    ): Self! from text | separator
}

construct LinesIter {
    /// Creates an allocation-free iterator over the lines in `text`.
    pub noalloc func new(text: &str): Self
}

instance SplitIter {
    impl Iterator { .Item = &str }
}

instance LinesIter {
    impl Iterator { .Item = &str }
}

instance Chars {
    impl Iterator { .Item = char }
}

instance str {
    /// Compares UTF-8 encoding bytes without allocation.
    pub noalloc operator (&self == other: &Self): bool

    /// Orders UTF-8 encoding bytes lexicographically without allocation.
    pub noalloc operator (&self < other: &Self): bool

    /// Returns the UTF-8 byte length of this text.
    pub noalloc method &self.len(): usize

    /// Returns whether this text contains no UTF-8 bytes.
    pub noalloc method &self.is_empty(): bool

    /// Returns the non-owning address of the first UTF-8 byte.
    pub noalloc method &self.ptr(): *u8

    /// Returns the exact UTF-8 encoding bytes as a borrowed slice.
    pub noalloc method &self.bytes(): &[u8]

    /// Iterates over Unicode scalar values in source order without allocation.
    pub noalloc method &self.chars(): Chars from self

    /// Counts Unicode scalar values without allocation.
    pub noalloc method &self.char_count(): usize

    /// Returns whether `index` lies on a Unicode scalar boundary.
    pub noalloc method &self.is_char_boundary(index: usize): bool

    /// Returns the byte range when it is ordered, in bounds, and boundary-aligned.
    pub noalloc method &self.get_range(start: usize, end: usize): &str?

    /// Returns the first byte index of `needle` at or after `start`.
    pub noalloc method &self.find_from(needle: &str, start: usize): usize?

    /// Returns the first byte index of `needle`.
    pub noalloc method &self.find(needle: &str): usize?

    /// Splits at the first separator without allocation.
    pub noalloc method &self.split_once(separator: &str): (&str, &str)? from self

    /// Returns whether this text contains `needle`.
    pub noalloc method &self.contains(needle: &str): bool

    /// Returns whether this text begins with `prefix`.
    pub noalloc method &self.starts_with(prefix: &str): bool

    /// Returns whether this text ends with `suffix`.
    pub noalloc method &self.ends_with(suffix: &str): bool

    /// Removes `prefix` and returns the remaining borrowed view when it matches.
    pub noalloc method &self.strip_prefix(prefix: &str): &str? from self

    /// Removes `suffix` and returns the remaining borrowed view when it matches.
    pub noalloc method &self.strip_suffix(suffix: &str): &str? from self

    /// Removes ASCII whitespace from the beginning and returns a borrowed view.
    pub noalloc method &self.trim_ascii_start(): &str from self

    /// Removes ASCII whitespace from the end and returns a borrowed view.
    pub noalloc method &self.trim_ascii_end(): &str from self

    /// Removes ASCII whitespace from both ends and returns a borrowed view.
    pub noalloc method &self.trim_ascii(): &str from self

    /// Removes Unicode whitespace from the beginning and returns a borrowed view.
    pub noalloc method &self.trim_start(): &str from self

    /// Removes Unicode whitespace from the end and returns a borrowed view.
    pub noalloc method &self.trim_end(): &str from self

    /// Removes Unicode whitespace from both ends and returns a borrowed view.
    pub noalloc method &self.trim(): &str from self

    /// Converts this text with Unicode full default lowercase casing.
    pub method &self.to_lowercase(): String

    /// Converts this text with Unicode full default uppercase casing.
    pub method &self.to_uppercase(): String

    /// Converts this text to lowercase using recoverable storage from `allocator`.
    pub method &self.try_to_lowercase(
        allocator: &+TryAllocator,
    ): String! from allocator

    /// Converts this text to uppercase using recoverable storage from `allocator`.
    pub method &self.try_to_uppercase(
        allocator: &+TryAllocator,
    ): String! from allocator

    /// Splits into independently owned components using `separator`.
    pub method &self.split(separator: &str): Vec<String>!

    /// Iterates over borrowed components separated by `separator`.
    pub noalloc method &self.split_views(separator: &str): SplitIter! from self | separator

    /// Iterates over borrowed lines, recognizing LF and CRLF endings.
    pub noalloc method &self.lines(): some Iterator { .Item = &str }

    /// Iterates over the exact UTF-8 encoding bytes without allocation.
    pub noalloc method &self.bytes_iter(): ViewIter<u8>

    /// Repeats this text into independently owned storage.
    pub method &self.repeat(count: usize): String

    /// Replaces non-overlapping matches into independently owned storage.
    pub method &self.replace_all(pattern: &str, replacement: &str): String!
}