widestring

Widestring is a Rust library that provides a complete family of wide-character string types for working with UTF-16 and UTF-32 data, the encodings most commonly required when interoperating with the Windows API and other C foreign-function interfaces. It mirrors the standard library’s String/str and CString/CStr split, offering owned and borrowed variants for both defined-encoding UTF strings and encoding-agnostic FFI strings.

The crate gives you Utf16String/Utf32String for guaranteed-valid UTF data, U16String/U32String for raw pass-through wide data, and U16CString/U32CString for nul-terminated C-style strings, each with a matching slice type and compile-time literal macros. It is no_std-friendly with optional alloc and std features.

What You Get

• Utf16String and Utf32String types that losslessly convert to and from the standard String
• U16String/U32String encoding-agnostic types for raw pass-through of FFI wide data
• U16CString/U32CString nul-terminated C-style wide strings for C FFI
• Matching borrowed slice types (U16Str, Utf16Str, U16CStr, and more) for every owned type
• Compile-time literal macros (u16str!, u32cstr!, and siblings) that build wide strings as consts
• no_std support with optional alloc and std feature gates

Common Use Cases

• Passing string arguments to Windows API functions that expect UTF-16 wide strings
• Building and reading nul-terminated wide strings for C library FFI
• Re-encoding between UTF-16 and UTF-32 while preserving malformed-encoding data
• Embedding wide string literals in code without manually encoding code units

Under The Hood

Architecture - The crate is organized by concern into paired owned/borrowed modules: ustr.rs/ustring.rs for raw U16Str/U16String, ucstr.rs/ucstring.rs for C-style nul-terminated types, and utfstr.rs/utfstring.rs for the defined-encoding UTF types, with iter.rs, error.rs, and macros.rs providing iteration, typed errors, and compile-time literal generation. lib.rs documents the type matrix and re-exports the public surface. Tech Stack - Pure Rust with zero runtime dependencies, edition 2021, minimum Rust 1.58. Encoding variants are gated behind std, alloc, and debugger_visualizer Cargo features so the crate compiles in no_std environments. Code Quality - Roughly 13,800 lines of well-documented source with extensive rustdoc, doctests embedded throughout the module documentation, and dedicated debugger-visualizer test coverage; raw types are carefully specified to tolerate malformed encoding rather than panic. API Design - The public API deliberately mirrors the standard library’s String/str and CString/CStr conventions, so method names and conversion traits are immediately familiar; the compile-time literal macros remove boilerplate for fixed wide strings.