NativeString

Owns immutable native process text units with explicit fallible text conversion. Native-byte and UTF-16 constructors preserve non-Unicode native values while rejecting NUL. TryCreate uses the selected target's UTF-8 encoder. Construction copies fallibly; movement transfers backing, and TryClone explicitly copies it. No cwd lookup, native text normalization or filesystem operation occurs. Borrowed View/text views expire on owner movement/destruction. Concurrent reads of a published unmoved owner are safe under ordinary backing/lifetime rules.

Module std.text

import std.text;

Public declaration contracts and authored examples. A page can document several related symbols. Implementation bodies are excluded.

NativeString

pub final class NativeString

Example

module example.native_strings;
from std.text import NativeString, NativeStringView;
fn Main() -> i32 {
    var Text = {
        // Scoped writable carriers end immediately after explicit payload transfer.
        var TextCreation = NativeString.TryCreate("--label=λ");
        switch TextCreation {
            case .Ok { Value = Value: mut NativeString& } => break move(Value);
            case .Err => return 1;
        }
    };
    if Text.IsEmpty || Text.TryViewUtf8().Unwrap() != "--label=λ" { return 2; }
    var Copy = {
        var CopyCreation = Text.TryClone();
        switch CopyCreation {
            case .Ok { Value = Value: mut NativeString& } => break move(Value);
            case .Err => return 3;
        }
    };
    var Moved = move(Text);
    if !Text.IsEmpty || Copy.TryViewUtf8().Unwrap() != Moved.TryViewUtf8().Unwrap() { return 4; }
    let Bytes: byte[2] = [0xFF_byte, 0x61_byte];
    var Native = {
        var NativeCreation = NativeString.TryFromNativeBytes(Bytes);
        switch NativeCreation {
            case .Ok { Value = Value: mut NativeString& } => break move(Value);
            case .Err => return 5;
        }
    };
    if Native.TryViewUtf8() is .Some { Value = _ } { return 6; }
    switch Native.TryToString() {
        case .Err { Error = PatternPayload5071 } if (PatternPayload5071 is .InvalidUtf8) => {}
        default => return 7;
    }
    let Wide: u16[2] = [0xD83D_u16, 0xDE42_u16];
    var Unicode = {
        var UnicodeCreation = NativeString.TryFromNativeUtf16(Wide);
        switch UnicodeCreation {
            case .Ok { Value = Value: mut NativeString& } => break move(Value);
            case .Err => return 8;
        }
    };
    var UnicodeText = switch Unicode.TryToString() { case .Ok { Value = Value } => break Value; case .Err => return 9; };
    if UnicodeText.View != "\u{1F642}" { return 10; }
    let Unpaired: u16[1] = [0xD800_u16];
    var Preserved = {
        var PreservedCreation = NativeString.TryFromNativeUtf16(Unpaired);
        switch PreservedCreation {
            case .Ok { Value = Value: mut NativeString& } => break move(Value);
            case .Err => return 11;
        }
    };
    switch Preserved.TryToString() {
        case .Err { Error = PatternPayload5072 } if (PatternPayload5072 is .InvalidUtf16) => {}
        default => return 12;
    }
    if !Copy.View.EqualsOrdinal(Moved.View) || Copy.View.EqualsOrdinal(Preserved.View) { return 14; }
    let Bmp: u16[2] = [0x03BB_u16, 0x4E2D_u16];
    var BmpNative = {
        var BmpNativeCreation = NativeString.TryFromNativeUtf16(Bmp);
        switch BmpNativeCreation {
            case .Ok { Value = Value: mut NativeString& } => break move(Value);
            case .Err => return 15;
        }
    };
    var BmpText = switch BmpNative.TryToString() { case .Ok { Value = Value } => break Value; case .Err => return 16; };
    if BmpText.View != "λ中" { return 17; }
    let Maximum: u16[2] = [0xDBFF_u16, 0xDFFF_u16];
    var MaximumNative = {
        var MaximumNativeCreation = NativeString.TryFromNativeUtf16(Maximum);
        switch MaximumNativeCreation {
            case .Ok { Value = Value: mut NativeString& } => break move(Value);
            case .Err => return 18;
        }
    };
    var MaximumText = switch MaximumNative.TryToString() { case .Ok { Value = Value } => break Value; case .Err => return 19; };
    if MaximumText.View != "\u{10FFFF}" { return 20; }
    let LoneLow: u16[1] = [0xDC00_u16];
    var LoneLowNative = {
        var LoneLowNativeCreation = NativeString.TryFromNativeUtf16(LoneLow);
        switch LoneLowNativeCreation {
            case .Ok { Value = Value: mut NativeString& } => break move(Value);
            case .Err => return 21;
        }
    };
    switch LoneLowNative.TryToString() {
        case .Err { Error = PatternPayload5073 } if (PatternPayload5073 is .InvalidUtf16) => {}
        default => return 22;
    }
    let Zero: byte[1] = [0_byte];
    switch NativeStringView.TryFromNativeBytes(Zero) {
        case .Err { Error = PatternPayload5074 } if (PatternPayload5074 is .EmbeddedNul) => {}
        default => return 13;
    }
    return 0;
}

NativeString.init

pub init()

Creates allocation-free empty native-byte owner.

NativeString.init

pub init(Source: readonly Self&) = delete;

Rejects implicit allocation/copy. Source: Existing native string.

NativeString.init

pub init(Source: mut Self&&)

Transfers native backing without conversion/allocation. Source: NativeString left empty.

NativeString.operator

pub fn operator =(Source: readonly Self&) -> void = delete;

Rejects implicit allocating copy. Source: Existing native string. Return: No runtime result; this assignment is deleted and cannot be invoked.

NativeString.operator

pub fn operator =(Source: mut Self&&) -> void

Replaces backing by ownership transfer, invalidating previous views. Source: NativeString left empty; vector transport handles self-move. Return: No value after replacing encoded backing; previous borrowed views are invalidated.

NativeString.Encoding

pub Encoding: NativeStringEncoding;

Observes the exact native unit kind.

NativeString.UnitLength

pub UnitLength: usize;

Counts active native units, not Unicode scalars.

NativeString.IsEmpty

pub IsEmpty: bool;

Observes empty native representation.

NativeString.View

pub View: NativeStringView;

Borrows immutable native units without allocating or retaining owner. Return: View expiring on this owner's move/destruction.

NativeString.TryCreate

pub static fn TryCreate(Text: str) -> Result<Self, NativeStringError>

Encodes valid UTF-8 for the selected target without filesystem lookup. Text: Borrowed valid UTF-8 copied into native units; NUL rejected. Return: Owned native string or portable representation/allocation failure.

NativeString.TryFromNativeBytes

pub static fn TryFromNativeBytes(Units: readonly byte[]) -> Result<Self, NativeStringError>

Copies exact non-NUL byte units, preserving non-UTF-8 names. Units: Borrowed input copied without normalization. Return: Owned native string or portable NUL/storage failure.

NativeString.TryFromNativeUtf16

pub static fn TryFromNativeUtf16(Units: readonly u16[]) -> Result<Self, NativeStringError>

Copies exact non-NUL UTF-16 units, preserving unpaired surrogates. Units: Borrowed native units copied without text validation. Return: Owned native string or portable NUL/storage failure.

NativeString.TryClone

pub readonly fn TryClone() -> Result<Self, NativeStringError>

Explicitly copies native backing without text conversion. Return: Independent owner or portable allocation failure; source unchanged. Warning: May allocate and performs linear copying.

NativeString.TryViewUtf8

pub readonly fn TryViewUtf8() -> str?

Validates a borrowed UTF-8 view of native bytes. Return: Borrowed text, or none for invalid UTF-8/UTF-16 representation.

NativeString.TryToString

pub readonly fn TryToString() -> Result<String, NativeStringError>

Converts native units to owned UTF-8 text fallibly. Return: Owned String or exact Unicode/storage failure; native string unchanged. Warning: May allocate.