Expand description
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§
- Generates a wide character sequence for potentially ill-formed UTF-16.