# Module std::os::windows::ffi

1.0.0 · source ·
Available on Windows only.
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

- 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`.