mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Clarify OsStr is self-synchronizing

Browse Source
This commit is contained in:
Ed Page 2023-05-17 09:34:25 -05:00
parent f9aaad0939
commit 5d177afe95
1 changed files with 15 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
library/std/src/ffi/os_str.rs
View File

@ -670,18 +670,22 @@ impl OsStr {
/// Converts a slice of bytes to an OS string slice without checking that the string contains /// Converts a slice of bytes to an OS string slice without checking that the string contains
/// valid `OsStr`-encoded data. /// valid `OsStr`-encoded data.
/// ///
/// The byte encoding is an unspecified, platform-specific, self-synchronizing superset of UTF-8.
/// By being a self-synchronizing superset of UTF-8, this encoding is also a superset of 7-bit
/// ASCII.
///
/// See the [module's toplevel documentation about conversions][conversions] for safe, /// See the [module's toplevel documentation about conversions][conversions] for safe,
/// cross-platform [conversions] from/to native representations. /// cross-platform [conversions] from/to native representations.
/// ///
/// # Safety /// # Safety
/// ///
/// `OsStr`'s encoding is an unspecified superset of UTF-8 and callers must /// As the encoding is unspecified, callers must pass in bytes that originated as a mixture of
/// pass in bytes that originated as a mixture of validated UTF-8 and bytes from /// validated UTF-8 and bytes from [`OsStr::as_os_str_bytes`] from within the same rust version
/// [`OsStr::as_os_str_bytes`] from within the same rust version built for the same target /// built for the same target platform. For example, reconstructing an `OsStr` from bytes sent
/// platform. For example, reconstructing an `OsStr` from bytes sent over the network or stored /// over the network or stored in a file will likely violate these safety rules.
/// in a file will likely violate these safety rules. The bytes from `OsStr::as_os_str_bytes` ///
/// may be split either immediately before or immediately after some valid non-empty UTF-8 /// Due to the encoding being self-synchronizing, the bytes from [`OsStr::as_os_str_bytes`] can be
/// substring /// split either immediately before or immediately after any valid non-empty UTF-8 substring.
/// ///
/// # Example /// # Example
/// ///
@ -881,6 +885,10 @@ impl OsStr {
/// Converts an OS string slice to a byte slice. To convert the byte slice back into an OS /// Converts an OS string slice to a byte slice. To convert the byte slice back into an OS
/// string slice, use the [`OsStr::from_os_str_bytes_unchecked`] function. /// string slice, use the [`OsStr::from_os_str_bytes_unchecked`] function.
/// ///
/// The byte encoding is an unspecified, platform-specific, self-synchronizing superset of UTF-8.
/// By being a self-synchronizing superset of UTF-8, this encoding is also a superset of 7-bit
/// ASCII.
///
/// Note: As the encoding is unspecified, any sub-slice of bytes that is not valid UTF-8 should /// Note: As the encoding is unspecified, any sub-slice of bytes that is not valid UTF-8 should
/// be treated as opaque and only comparable within the same rust version built for the same /// be treated as opaque and only comparable within the same rust version built for the same
/// target platform. For example, sending the slice over the network or storing it in a file /// target platform. For example, sending the slice over the network or storing it in a file