Struct WtfStr 

pub struct WtfStr<E: WtfEncoding> { /* private fields */ }

A borrowed string slice of code units in encoding E (the analog of OsStr / str).

This is #[repr(transparent)] over [E::Unit], so a &WtfStr<E> can be created from a &[E::Unit] without copying. The units are the string’s content: there is no terminator here, since the always-terminated invariant is a property of the owned WtfString, not of an arbitrary borrowed slice.

Implementations

impl WtfStr<Wtf16>

pub fn to_os_string(&self) -> OsString

Decode the content into an owned OsString, losslessly.

The OsStringExt::from_wide bridge: unpaired surrogates are preserved.

pub fn encode_wide(&self) -> impl Iterator<Item = u16> + '_

Iterate the content as wide code units, zero-copy: the OsStrExt::encode_wide analog over our own slice.

impl<E: WtfEncoding> WtfStr<E>

pub fn from_units(units: &[E::Unit]) -> &WtfStr<E>

Wrap a slice of code units as a &WtfStr<E> without copying.

Examples found in repository

examples/win32_round_trip.rs (line 83)

    pub fn run() {
        let input = Wtf16String::from(r"C:\Windows\System32\..\Temp");
        println!("input : {input}");

        match full_path(&input) {
            Some(expanded) => println!("expanded: {expanded}"),
            None => println!("expanded: <GetFullPathNameW failed>"),
        }

        compare(&Wtf16String::from("alpha"), &Wtf16String::from("beta"));
        compare(&Wtf16String::from("beta"), &Wtf16String::from("alpha"));
        compare(&Wtf16String::from("same"), &Wtf16String::from("same"));

        // The counted pair works on a borrowed slice, which has no terminator
        // of its own -- the length is what makes it well-defined.
        let units: Vec<u16> = "borrowed".encode_utf16().collect();
        let borrowed = Wtf16Str::from_units(&units);
        println!(
            "borrowed slice of {} units compares equal to itself: {}",
            borrowed.len(),
            ordinal(borrowed, borrowed) == CSTR_EQUAL
        );
    }

pub fn as_units(&self) -> &[E::Unit]

The content code units (there is no terminator on a borrowed slice).

pub fn len(&self) -> usize

The number of content code units (not bytes, not code points).

Examples found in repository

examples/win32_round_trip.rs (line 86)

    pub fn run() {
        let input = Wtf16String::from(r"C:\Windows\System32\..\Temp");
        println!("input : {input}");

        match full_path(&input) {
            Some(expanded) => println!("expanded: {expanded}"),
            None => println!("expanded: <GetFullPathNameW failed>"),
        }

        compare(&Wtf16String::from("alpha"), &Wtf16String::from("beta"));
        compare(&Wtf16String::from("beta"), &Wtf16String::from("alpha"));
        compare(&Wtf16String::from("same"), &Wtf16String::from("same"));

        // The counted pair works on a borrowed slice, which has no terminator
        // of its own -- the length is what makes it well-defined.
        let units: Vec<u16> = "borrowed".encode_utf16().collect();
        let borrowed = Wtf16Str::from_units(&units);
        println!(
            "borrowed slice of {} units compares equal to itself: {}",
            borrowed.len(),
            ordinal(borrowed, borrowed) == CSTR_EQUAL
        );
    }

    /// Terminated input, then buffer-fill output -- both without converting.
    fn full_path(input: &Wtf16String) -> Option<Wtf16String> {
        // Pass 1: ask for the size. The terminator is already in the buffer, so
        // handing over an `LPCWSTR` costs nothing.
        // SAFETY: `as_terminated_ptr` is NUL-terminated and valid while
        // `input` is borrowed; a zero length asks for the required size only.
        let needed = unsafe {
            GetFullPathNameW(
                input.as_terminated_ptr(),
                0,
                core::ptr::null_mut(),
                core::ptr::null_mut(),
            )
        };
        if needed == 0 {
            return None;
        }

        // `needed` counts the terminator; our capacity is a *content* length,
        // and `with_capacity` reserves the terminator slot itself.
        let mut out = Wtf16String::with_capacity(needed as usize - 1);

        // Pass 2: let the API write straight into our buffer.
        // SAFETY: the buffer has room for `needed` units (content + the
        // reserved terminator slot), which is exactly what pass 1 asked for.
        let written = unsafe {
            GetFullPathNameW(
                input.as_terminated_ptr(),
                needed,
                out.as_mut_ptr(),
                core::ptr::null_mut(),
            )
        };
        if written == 0 || written >= needed {
            // Failed, or raced a directory change and now wants more room.
            // `out`'s invariant is still broken here, so republish an empty
            // string before dropping it (see `as_mut_ptr`'s contract).
            // SAFETY: publishing zero content units is always in bounds.
            unsafe { out.set_len_from_ffi(0) };
            return None;
        }

        // `written` excludes the terminator, which is precisely the content
        // length `set_len_from_ffi` wants -- no guessing about conventions.
        // SAFETY: the API initialized `written` units and `written < needed`,
        // so the appended terminator still fits.
        unsafe { out.set_len_from_ffi(written as usize) };
        Some(out)
    }

    /// Counted input: pointer + length, no terminator required.
    fn ordinal(a: &Wtf16Str, b: &Wtf16Str) -> i32 {
        // SAFETY: each pointer is valid for exactly its own `len()` units while
        // borrowed, which is the contract `CompareStringOrdinal` expects.
        unsafe {
            CompareStringOrdinal(
                a.as_ptr(),
                a.len() as i32,
                b.as_ptr(),
                b.len() as i32,
                0, // case-sensitive
            )
        }
    }

pub fn is_empty(&self) -> bool

Whether the string has no content units.

pub fn has_interior_nul(&self) -> bool

Whether the content contains a NUL (E::NUL) code unit.

For the Wtf16 arm, a terminated LPCWSTR view of an owned string is a valid C string only when this is false (see Wtf16String::as_terminated_ptr); counted access is always valid regardless of this encoding’s storage width.

pub fn to_string_checked(&self) -> Option<String>

Decode to a String if the content is well-formed for this encoding.

Returns None for content a strict String cannot hold (e.g. an unpaired surrogate in WTF-16); use to_string_lossy to decode with replacement instead.

pub fn to_string_lossy(&self) -> String

Decode to a String, replacing any ill-formed sequence with U+FFFD.

impl WtfStr<Wtf16>

pub fn as_ptr(&self) -> *const u16

A pointer to the content code units, for counted FFI paired with len.

The pointer is not guaranteed to be NUL-terminated (a borrowed slice carries no terminator); use it only with the matching unit count. It is valid while self is borrowed and unmodified. For a terminated LPCWSTR, start from an owned Wtf16String and use Wtf16String::as_terminated_ptr.

Examples found in repository

examples/win32_round_trip.rs (line 147)

    fn ordinal(a: &Wtf16Str, b: &Wtf16Str) -> i32 {
        // SAFETY: each pointer is valid for exactly its own `len()` units while
        // borrowed, which is the contract `CompareStringOrdinal` expects.
        unsafe {
            CompareStringOrdinal(
                a.as_ptr(),
                a.len() as i32,
                b.as_ptr(),
                b.len() as i32,
                0, // case-sensitive
            )
        }
    }

Trait Implementations

impl<E: WtfEncoding> AsRef<WtfStr<E>> for WtfString<E>

fn as_ref(&self) -> &WtfStr<E>

Converts this type into a shared reference of the (usually inferred) input type.

impl<E: WtfEncoding> AsRef<WtfStr<E>> for WtfStr<E>

fn as_ref(&self) -> &WtfStr<E>

Converts this type into a shared reference of the (usually inferred) input type.

impl<E: WtfEncoding> Borrow<WtfStr<E>> for WtfString<E>

fn borrow(&self) -> &WtfStr<E>

Immutably borrows from an owned value.

impl<E: WtfEncoding> Debug for WtfStr<E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<E: WtfEncoding> Display for WtfStr<E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<E: WtfEncoding> Eq for WtfStr<E>

impl From<&WtfStr<Wtf16>> for OsString

fn from(s: &Wtf16Str) -> Self

Converts to this type from the input type.

impl<E: WtfEncoding> Hash for WtfStr<E>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

impl<E: WtfEncoding> Ord for WtfStr<E>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

impl<E: WtfEncoding> PartialEq for WtfStr<E>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<E: WtfEncoding> PartialEq<&str> for WtfStr<E>

fn eq(&self, other: &&str) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<E: WtfEncoding> PartialEq<str> for WtfStr<E>

fn eq(&self, other: &str) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<E: WtfEncoding> PartialOrd for WtfStr<E>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<E: WtfEncoding> ToOwned for WtfStr<E>

type Owned = WtfString<E>

The resulting type after obtaining ownership.

fn to_owned(&self) -> WtfString<E>

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.