Module std::os::windows::ffi

Available on Windows only.

Windows-specific extensions to primitives in the std::ffi module.

Overview

For historical reasons, the Windows API uses a form of potentially ill-formed UTF-16 encoding for strings. Specifically, the 16-bit code units in Windows strings may contain isolated surrogate code points which are not paired together. The Unicode standard requires that surrogate code points (those in the range U+D800 to U+DFFF) always be paired, because in the UTF-16 encoding a surrogate code unit pair is used to encode a single character. For compatibility with code that does not enforce these pairings, Windows does not enforce them, either.

While it is not always possible to convert such a string losslessly into a valid UTF-16 string (or even UTF-8), it is often desirable to be able to round-trip such a string from and to Windows APIs losslessly. For example, some Rust code may be “bridging” some Windows APIs together, just passing WCHAR strings among those APIs without ever really looking into the strings.

If Rust code does need to look into those strings, it can convert them to valid UTF-8, possibly lossily, by substituting invalid sequences with U+FFFD REPLACEMENT CHARACTER, as is conventionally done in other Rust APIs that deal with string encodings.

OsStringExt and OsStrExt

OsString is the Rust wrapper for owned strings in the preferred representation of the operating system. On Windows, this struct gets augmented with an implementation of the OsStringExt trait, which has an OsStringExt::from_wide method. This lets you create an OsString from a &[u16] slice; presumably you get such a slice out of a WCHAR Windows API.

Similarly, OsStr is the Rust wrapper for borrowed strings from preferred representation of the operating system. On Windows, the OsStrExt trait provides the OsStrExt::encode_wide method, which outputs an EncodeWide iterator. You can collect this iterator, for example, to obtain a Vec<u16>; you can later get a pointer to this vector’s contents and feed it to Windows APIs.

These traits, along with OsString and OsStr, work in conjunction so that it is possible to round-trip strings from Windows and back, with no loss of data, even if the strings are ill-formed UTF-16.

Structs

• EncodeWide
  Generates a wide character sequence for potentially ill-formed UTF-16.

Traits

• OsStrExt
  Windows-specific extensions to OsStr.
• OsStringExt
  Windows-specific extensions to OsString.