index.nct

//! Common owning string type.
//!
//! `str` is the compiler built-in unsized UTF-8 data type. `&str` is the
//! non-owning UTF-8 string slice type and the type of string literals. String is
//! the owning string type. Its storage details are intentionally not exposed
//! outside `std/string`.
//!
//! Public construction and mutation belong to `construct String` and
//! `instance String`; borrowed observation belongs to `instance str`. Their
//! implementation helpers remain private. Empty strings,
//! copying from `&str`, capacity reservation, growth, UTF-8 view construction,
//! byte-slice view construction, and release are implemented in Nocter code
//! through restricted runtime pointer primitives.

use /mem.TryAllocator
see ./construction.nct
see ./mutation.nct
see ./suffix.nct
see ./suffix_tests.nct
see ./storage.nct
see ./utf8.nct

/// An owning, growable well-formed UTF-8 string.
pub struct String

construct String {
    /// Copies a static string view into owned storage in the current allocation context.
    pub literal ""(text: &str): Self

    /// Constructs an empty String without binding storage.
    pub noalloc func empty(): Self

    /// Constructs an empty String with at least the requested byte capacity.
    pub func with_capacity(requested_capacity: usize): Self

    /// Constructs an empty String using recoverable storage from `allocator`.
    pub func try_with_capacity(
        allocator: &+TryAllocator,
        requested_capacity: usize,
    ): Self!

    /// Copies borrowed UTF-8 text into owned storage.
    pub func copy(value: &str): Self

    /// Concatenates borrowed UTF-8 parts into one owned string.
    pub func concat(...parts: &str): Self

    /// Copies borrowed UTF-8 text using recoverable storage from `allocator`.
    pub func try_copy(allocator: &+TryAllocator, value: &str): Self! from allocator

    /// Validates and copies UTF-8 bytes into current-context storage.
    pub func from_utf8(candidate: &[u8]): Self!

    /// Validates and copies UTF-8 bytes using recoverable storage from `allocator`.
    pub func try_from_utf8(
        allocator: &+TryAllocator,
        candidate: &[u8],
    ): Self! from allocator
}

/// Returns whether `candidate` is a well-formed UTF-8 byte sequence.
pub noalloc func is_valid_utf8(candidate: &[u8]): bool

instance String {
    /// Exposes the initialized UTF-8 prefix without transferring ownership.
    pub noalloc coerce &self as &str

    /// Returns the byte capacity available without growth.
    pub noalloc method &self.capacity(): usize

    /// Ensures capacity for at least `additional` more UTF-8 bytes.
    pub method &+self.reserve(additional: usize): void

    /// Ensures additional byte capacity with recoverable allocation failure.
    pub method &+self.try_reserve(additional: usize): void!

    /// Removes all text while retaining reusable storage.
    pub noalloc method &+self.clear(): void

    /// Appends borrowed UTF-8 text.
    pub method &+self.push_str(value: &str): void

    /// Appends borrowed UTF-8 text with recoverable allocation failure.
    pub method &+self.try_push_str(value: &str): void!

    /// Appends one Unicode scalar value.
    pub method &+self.push(value: char): void

    /// Appends one Unicode scalar value with recoverable allocation failure.
    pub method &+self.try_push(value: char): void!

    /// Validates and appends UTF-8 bytes with recoverable allocation failure.
    pub method &+self.try_push_utf8(value: &[u8]): void!

    /// Removes and returns the final Unicode scalar, if present.
    pub noalloc method &+self.pop(): char?

    /// Retains the prefix ending at `byte_len` when it is a Unicode scalar boundary.
    pub noalloc method &+self.truncate(byte_len: usize): void!
}