1 //! Windows-specific extensions to the primitives in the `std::ffi` module.
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.
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.
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
28 //! # `OsStringExt` and `OsStrExt`
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.
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.
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.
49 //! [ill-formed-utf-16]: https://simonsapin.github.io/wtf-8/#ill-formed-utf-16
50 //! [`collect`]: crate::iter::Iterator::collect
51 //! [U+FFFD]: crate::char::REPLACEMENT_CHARACTER
53 #![stable(feature = "rust1", since = "1.0.0")]
55 use crate::ffi
::{OsStr, OsString}
;
56 use crate::sealed
::Sealed
;
57 use crate::sys
::os_str
::Buf
;
58 use crate::sys_common
::wtf8
::Wtf8Buf
;
59 use crate::sys_common
::{AsInner, FromInner}
;
61 #[stable(feature = "rust1", since = "1.0.0")]
62 pub use crate::sys_common
::wtf8
::EncodeWide
;
64 /// Windows-specific extensions to [`OsString`].
66 /// This trait is sealed: it cannot be implemented outside the standard library.
67 /// This is so that future additional methods are not breaking changes.
68 #[stable(feature = "rust1", since = "1.0.0")]
69 pub trait OsStringExt
: Sealed
{
70 /// Creates an `OsString` from a potentially ill-formed UTF-16 slice of
71 /// 16-bit code units.
73 /// This is lossless: calling [`OsStrExt::encode_wide`] on the resulting string
74 /// will always return the original code units.
79 /// use std::ffi::OsString;
80 /// use std::os::windows::prelude::*;
82 /// // UTF-16 encoding for "Unicode".
83 /// let source = [0x0055, 0x006E, 0x0069, 0x0063, 0x006F, 0x0064, 0x0065];
85 /// let string = OsString::from_wide(&source[..]);
87 #[stable(feature = "rust1", since = "1.0.0")]
88 fn from_wide(wide
: &[u16]) -> Self;
91 #[stable(feature = "rust1", since = "1.0.0")]
92 impl OsStringExt
for OsString
{
93 fn from_wide(wide
: &[u16]) -> OsString
{
94 FromInner
::from_inner(Buf { inner: Wtf8Buf::from_wide(wide) }
)
98 /// Windows-specific extensions to [`OsStr`].
100 /// This trait is sealed: it cannot be implemented outside the standard library.
101 /// This is so that future additional methods are not breaking changes.
102 #[stable(feature = "rust1", since = "1.0.0")]
103 pub trait OsStrExt
: Sealed
{
104 /// Re-encodes an `OsStr` as a wide character sequence, i.e., potentially
105 /// ill-formed UTF-16.
107 /// This is lossless: calling [`OsStringExt::from_wide`] and then
108 /// `encode_wide` on the result will yield the original code units.
109 /// Note that the encoding does not add a final null terminator.
114 /// use std::ffi::OsString;
115 /// use std::os::windows::prelude::*;
117 /// // UTF-16 encoding for "Unicode".
118 /// let source = [0x0055, 0x006E, 0x0069, 0x0063, 0x006F, 0x0064, 0x0065];
120 /// let string = OsString::from_wide(&source[..]);
122 /// let result: Vec<u16> = string.encode_wide().collect();
123 /// assert_eq!(&source[..], &result[..]);
125 #[stable(feature = "rust1", since = "1.0.0")]
126 fn encode_wide(&self) -> EncodeWide
<'_
>;
129 #[stable(feature = "rust1", since = "1.0.0")]
130 impl OsStrExt
for OsStr
{
131 fn encode_wide(&self) -> EncodeWide
<'_
> {
132 self.as_inner().inner
.encode_wide()