std/os/windows/ffi.rs
1//! Windows-specific extensions to primitives in the [`std::ffi`] module.
2//!
3//! # Overview
4//!
5//! For historical reasons, the Windows API uses a form of potentially
6//! ill-formed UTF-16 encoding for strings. Specifically, the 16-bit
7//! code units in Windows strings may contain [isolated surrogate code
8//! points which are not paired together][ill-formed-utf-16]. The
9//! Unicode standard requires that surrogate code points (those in the
10//! range U+D800 to U+DFFF) always be *paired*, because in the UTF-16
11//! encoding a *surrogate code unit pair* is used to encode a single
12//! character. For compatibility with code that does not enforce
13//! these pairings, Windows does not enforce them, either.
14//!
15//! While it is not always possible to convert such a string losslessly into
16//! a valid UTF-16 string (or even UTF-8), it is often desirable to be
17//! able to round-trip such a string from and to Windows APIs
18//! losslessly. For example, some Rust code may be "bridging" some
19//! Windows APIs together, just passing `WCHAR` strings among those
20//! APIs without ever really looking into the strings.
21//!
22//! If Rust code *does* need to look into those strings, it can
23//! convert them to valid UTF-8, possibly lossily, by substituting
24//! invalid sequences with [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD], as is
25//! conventionally done in other Rust APIs that deal with string
26//! encodings.
27//!
28//! # `OsStringExt` and `OsStrExt`
29//!
30//! [`OsString`] is the Rust wrapper for owned strings in the
31//! preferred representation of the operating system. On Windows,
32//! this struct gets augmented with an implementation of the
33//! [`OsStringExt`] trait, which has an [`OsStringExt::from_wide`] method. This
34//! lets you create an [`OsString`] from a `&[u16]` slice; presumably
35//! you get such a slice out of a `WCHAR` Windows API.
36//!
37//! Similarly, [`OsStr`] is the Rust wrapper for borrowed strings from
38//! preferred representation of the operating system. On Windows, the
39//! [`OsStrExt`] trait provides the [`OsStrExt::encode_wide`] method, which
40//! outputs an [`EncodeWide`] iterator. You can [`collect`] this
41//! iterator, for example, to obtain a `Vec<u16>`; you can later get a
42//! pointer to this vector's contents and feed it to Windows APIs.
43//!
44//! These traits, along with [`OsString`] and [`OsStr`], work in
45//! conjunction so that it is possible to **round-trip** strings from
46//! Windows and back, with no loss of data, even if the strings are
47//! ill-formed UTF-16.
48//!
49//! [ill-formed-utf-16]: https://simonsapin.github.io/wtf-8/#ill-formed-utf-16
50//! [`collect`]: crate::iter::Iterator::collect
51//! [U+FFFD]: char::REPLACEMENT_CHARACTER
52//! [`std::ffi`]: crate::ffi
53
54#![stable(feature = "rust1", since = "1.0.0")]
55
56use alloc::wtf8::Wtf8Buf;
57
58use crate::ffi::{OsStr, OsString};
59use crate::fmt;
60use crate::iter::FusedIterator;
61use crate::macros::rustdoc_skip_body;
62use crate::sys::os_str::Buf;
63use crate::sys::{AsInner, FromInner};
64
65/// Windows-specific extensions to [`OsString`].
66#[stable(feature = "rust1", since = "1.0.0")]
67pub impl(self) trait OsStringExt {
68 /// Creates an `OsString` from a potentially ill-formed UTF-16 slice of
69 /// 16-bit code units.
70 ///
71 /// This is lossless: calling [`OsStrExt::encode_wide`] on the resulting string
72 /// will always return the original code units.
73 ///
74 /// # Examples
75 ///
76 #[cfg_attr(windows, doc = "```no_run")]
77 #[cfg_attr(not(windows), doc = "```ignore (needs windows)")]
78 /// use std::ffi::OsString;
79 /// use std::os::windows::prelude::*;
80 ///
81 /// // UTF-16 encoding for "Unicode".
82 /// let source = [0x0055, 0x006E, 0x0069, 0x0063, 0x006F, 0x0064, 0x0065];
83 ///
84 /// let string = OsString::from_wide(&source[..]);
85 /// ```
86 #[stable(feature = "rust1", since = "1.0.0")]
87 fn from_wide(wide: &[u16]) -> Self;
88}
89
90#[stable(feature = "rust1", since = "1.0.0")]
91impl OsStringExt for OsString {
92 #[rustdoc_skip_body]
93 fn from_wide(wide: &[u16]) -> OsString {
94 FromInner::from_inner(Buf { inner: Wtf8Buf::from_wide(wide) })
95 }
96}
97
98/// Windows-specific extensions to [`OsStr`].
99#[stable(feature = "rust1", since = "1.0.0")]
100pub impl(self) trait OsStrExt {
101 /// Re-encodes an `OsStr` as a wide character sequence, i.e., potentially
102 /// ill-formed UTF-16.
103 ///
104 /// This is lossless: calling [`OsStringExt::from_wide`] and then
105 /// `encode_wide` on the result will yield the original code units.
106 /// Note that the encoding does not add a final null terminator.
107 ///
108 /// # Examples
109 ///
110 #[cfg_attr(windows, doc = "```no_run")]
111 #[cfg_attr(not(windows), doc = "```ignore (needs windows)")]
112 /// use std::ffi::OsString;
113 /// use std::os::windows::prelude::*;
114 ///
115 /// // UTF-16 encoding for "Unicode".
116 /// let source = [0x0055, 0x006E, 0x0069, 0x0063, 0x006F, 0x0064, 0x0065];
117 ///
118 /// let string = OsString::from_wide(&source[..]);
119 ///
120 /// let result: Vec<u16> = string.encode_wide().collect();
121 /// assert_eq!(&source[..], &result[..]);
122 /// ```
123 #[stable(feature = "rust1", since = "1.0.0")]
124 fn encode_wide(&self) -> EncodeWide<'_>;
125}
126
127#[stable(feature = "rust1", since = "1.0.0")]
128impl OsStrExt for OsStr {
129 #[inline]
130 #[rustdoc_skip_body]
131 fn encode_wide(&self) -> EncodeWide<'_> {
132 EncodeWide { inner: self.as_inner().inner.encode_wide() }
133 }
134}
135
136/// Iterator returned by [`OsStrExt::encode_wide`].
137#[stable(feature = "rust1", since = "1.0.0")]
138#[derive(Clone)]
139pub struct EncodeWide<'a> {
140 inner: alloc::wtf8::EncodeWide<'a>,
141}
142#[stable(feature = "encode_wide_debug", since = "1.91.0")]
143impl fmt::Debug for EncodeWide<'_> {
144 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
145 fmt::Debug::fmt(&self.inner, f)
146 }
147}
148#[stable(feature = "rust1", since = "1.0.0")]
149impl Iterator for EncodeWide<'_> {
150 type Item = u16;
151
152 #[inline]
153 fn next(&mut self) -> Option<u16> {
154 self.inner.next()
155 }
156
157 #[inline]
158 fn size_hint(&self) -> (usize, Option<usize>) {
159 self.inner.size_hint()
160 }
161}
162#[stable(feature = "encode_wide_fused_iterator", since = "1.62.0")]
163impl FusedIterator for EncodeWide<'_> {}