Struct WtfString 

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

An owned, growable string of code units in encoding E (the analog of OsString / String).

The backing buffer always carries a trailing E::NUL beyond the logical content, so content access (via Deref to WtfStr) excludes the terminator while a width-specific FFI surface can still reach it with no extra allocation – for the Wtf16 arm this is a terminated pointer for wide (*W) Win32 APIs (see Wtf16String::as_terminated_ptr). Content may itself contain interior NULs (parity with OsString); see WtfStr::has_interior_nul.

Implementations

impl WtfString<Wtf16>

pub fn from_os_str(s: &OsStr) -> Self

Encode an OsStr into owned WTF-16, converting once at the boundary.

Lossless: unpaired surrogates survive, so from_os_str(x).to_os_string() == x. This is the owning analog of collecting OsStrExt::encode_wide.

pub fn from_wide(units: &[u16]) -> Self

Build from already-wide code units: the OsStringExt::from_wide analog.

Identical to from_units, named for drop-in familiarity when replacing an OsString::from_wide call site.

impl<E: WtfEncoding> WtfString<E>

pub fn new() -> Self

Create an empty string (a buffer holding only the terminator).

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

Create an owned string from content code units, appending the terminator.

pub fn into_string(self) -> Result<String, Self>

Consume the string and decode it to a String if its content is well-formed for this encoding, otherwise return the original unchanged.

The native-u16 analog of OsString::into_string.

pub fn push<S: AsRef<WtfStr<E>>>(&mut self, s: S)

Append s’s code units after the current content, re-establishing the terminator (the OsString::push analog).

There is deliberately no truncate/pop/indexed edit: like OsString, the content is opaque code units that may be ill-formed (D-4/D-15), so an arbitrary byte/unit-offset edit could split a multi-unit sequence into content with no way to detect the damage afterward (D-16).

pub fn push_str(&mut self, s: &str)

Encode s and append it, re-establishing the terminator: the str-ergonomic sibling of push, for callers without an existing WtfStr<E> to hand.

pub fn clear(&mut self)

Truncate to empty, re-establishing the terminator (the OsString::clear analog).

pub fn capacity(&self) -> usize

The number of content code units this string can hold without reallocating (excluding the always-reserved terminator slot); the OsString::capacity analog.

pub fn reserve(&mut self, additional: usize)

Reserve capacity for at least additional more content code units without reallocating; the OsString::reserve analog.

pub fn reserve_exact(&mut self, additional: usize)

Reserve capacity for exactly additional more content code units (modulo allocator granularity); the OsString::reserve_exact analog.

pub fn shrink_to_fit(&mut self)

Shrink the backing buffer’s capacity to fit its current content (plus the terminator); the OsString::shrink_to_fit analog.

pub fn shrink_to(&mut self, min_capacity: usize)

Shrink the backing buffer’s capacity to hold at least min_capacity content code units (plus the terminator), never growing it; the OsString::shrink_to analog.

impl WtfString<Wtf16>

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

A NUL-terminated *const u16 (LPCWSTR/PCWSTR) over the whole buffer.

The always-present terminator makes this allocation-free (D-7). It is a valid C string only when has_interior_nul is false; otherwise a reader stops at the first interior NUL. The pointer is valid while self is borrowed and unmodified.

Examples found in repository

examples/win32_round_trip.rs (line 99)

    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)
    }

pub fn with_capacity(units: usize) -> Self

An empty string with room for units content code units to be filled in place via as_mut_ptr plus set_len_from_ffi.

The reserved capacity also covers the always-present terminator, so a later set_len_from_ffi of up to units content units re-establishes the invariant without reallocating (D-9).

Examples found in repository

examples/win32_round_trip.rs (line 111)

    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)
    }

pub fn as_mut_ptr(&mut self) -> *mut u16

A mutable pointer to the start of the buffer, for a foreign buffer-fill.

with_capacity(n) reserves n + 1 units: room for n content units plus the terminator slot. A foreign API may fill up to n content units, and one more if it writes its own terminator into the reserved slot (n + 1 units total). Either way, pass only the content length to set_len_from_ffi, which publishes that length and re-establishes the terminator.

Writing through this pointer overwrites the buffer – including element 0, which is the sole terminator of a fresh with_capacity – so it breaks the always-terminated invariant until set_len_from_ffi restores it. Between the write and that call the value must not be observed through any other method (as_terminated_ptr, Deref content access, Clone, Debug, PartialEq, …): they could read a non-terminated or partially written buffer. This holds on failure paths too – if the foreign call fails, restore the invariant with set_len_from_ffi(0) (the empty string) or drop the value before any other use. The pointer is valid while self is borrowed and not reallocated.

Examples found in repository

examples/win32_round_trip.rs (line 120)

    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)
    }

pub unsafe fn set_len_from_ffi(&mut self, content_units: usize)

Publish content_units content code units written into the buffer from as_mut_ptr, then append the terminator.

content_units counts content only and never includes a terminator. The written units are taken verbatim – they may themselves end in NUL, since interior NULs are permitted (see has_interior_nul) – and exactly one terminator is appended. A foreign API that reports a count including the terminator it wrote must subtract one and pass the content length; this method never inspects the buffer to guess the convention, so a genuine trailing content NUL is never mistaken for the terminator.

Safety

The caller must guarantee that:

• the first content_units code units at as_mut_ptr are initialized u16 values, and
• content_units does not exceed the count requested via with_capacity, so the appended terminator fits without reallocating a buffer whose pointer the caller may still hold.

Examples found in repository

examples/win32_round_trip.rs (line 129)

    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)
    }

pub unsafe fn from_wide_ptr(ptr: *const u16, len: usize) -> Self

Copy len content code units from a foreign *const u16 into a new owned string, appending the terminator.

For callee-allocated Win32 output: the bytes are copied, so the caller keeps ownership of (and remains responsible for freeing) the source buffer. The copy is lossless — arbitrary WTF-16, including unpaired surrogates, is preserved (D-4/D-9).

Safety

This copies the range through core::slice::from_raw_parts and shares its preconditions. When len > 0 the caller must guarantee that:

• ptr is non-null and properly aligned for u16;
• ptr is valid for reads of len consecutive, initialized u16 values, all contained within a single allocated object;
• the total size len * size_of::<u16>() is no larger than isize::MAX, and adding it to ptr does not wrap the address space; and
• that region stays unmutated for the duration of the call.

When len == 0 the pointer is not dereferenced, so it may be null or dangling. No reference to ptr is retained past the call. len is a count of code units, not bytes, and excludes any terminator the callee may have written (pass the content length).

Methods from Deref<Target = WtfStr<E>>

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.

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> Borrow<WtfStr<E>> for WtfString<E>

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

Immutably borrows from an owned value.

impl<E: WtfEncoding> Clone for WtfString<E>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

impl<E: WtfEncoding> Default for WtfString<E>

fn default() -> Self

Returns the “default value” for a type.

impl<E: WtfEncoding> Deref for WtfString<E>

type Target = WtfStr<E>

The resulting type after dereferencing.

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

Dereferences the value.

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

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

Formats the value using the given formatter.

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

impl From<&WtfString<Wtf16>> for OsString

fn from(s: &Wtf16String) -> Self

Converts to this type from the input type.

impl<E: WtfEncoding> From<&str> for WtfString<E>

fn from(s: &str) -> Self

Converts to this type from the input type.

impl<E: WtfEncoding> From<String> for WtfString<E>

fn from(s: String) -> Self

Converts to this type from the input type.

impl From<WtfString<Wtf16>> for OsString

fn from(s: Wtf16String) -> Self

Converts to this type from the input type.

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

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

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

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

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

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

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

Equality operator ==.

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

Inequality operator !=.

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

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

Equality operator ==.

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

Inequality operator !=.

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

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

Equality operator ==.

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

Inequality operator !=.

impl<E: WtfEncoding> PartialOrd for WtfString<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.