stable-osstring-encoding 1.1.1

A stable way to convert OsString and OsStr to and from raw data.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

#![warn(missing_docs, clippy::all)]
#![doc = include_str!("../readme.md")]



#[cfg(not(any(unix, windows)))]
compile_error!(
	"This crate currently only supports Windows and Unix (Linux and Macos). Adding support for your platform is likely very easy, please consider opening an issue for it in \"stable-osstring-encoding\"'s issue tracker."
);



use std::{borrow::Cow, ffi::OsStr};



/// Contains the implementation for unix builds, including Linux and Macos
#[cfg(unix)]
pub mod impl_unix;
/// Contains the implementation for windows builds
#[cfg(windows)]
pub mod impl_windows;



/// Defines the encoding width
#[cfg(unix)]
pub type EncodingWidth = u8;
/// Defines the encoding width
#[cfg(windows)]
pub type EncodingWidth = u16;

/// A simple alias for `Vec<EncodingWidth>`
pub type StableOsString = Vec<EncodingWidth>;



/// Converts an `OsString` or `OsStr` to an encoding that is stable across rust compiler versions
pub trait ToStableEncoding {
	/// Converts an `OsString` or `OsStr` to an encoding that is stable across rust compiler versions
	fn to_stable_encoding(&self) -> StableOsString;
}

/// Converts an `OsString` from an encoding that is stable across rust compiler versions, bypassing data copies if possible
pub trait IntoStableEncoding {
	/// Converts an `OsString` from an encoding that is stable across rust compiler versions, bypassing data copies if possible
	fn into_stable_encoding(self) -> StableOsString;
}

/// Converts an `OsString` from an encoding that is stable across rust compiler versions, bypassing data copies if possible
pub trait FromStableEncoding {
	/// Converts an `OsString` from an encoding that is stable across rust compiler versions, bypassing data copies if possible
	///
	/// # Safety
	///
	/// The given bytes must be compatible with the underlying of the platform's `OsStr` encoding (reminder: this crate only make it safe to pass data between different rust versions)
	unsafe fn from_stable_encoding<'a>(encoded: impl Into<Cow<'a, [EncodingWidth]>>) -> Self;
}



impl<'a> IntoStableEncoding for Cow<'a, OsStr> {
	fn into_stable_encoding(self) -> StableOsString {
		match self {
			Cow::Borrowed(os_str) => os_str.to_stable_encoding(),
			Cow::Owned(os_string) => os_string.into_stable_encoding(),
		}
	}
}



#[cfg(test)]
mod test {
	use crate::{FromStableEncoding, IntoStableEncoding, ToStableEncoding};
	use std::ffi::OsString;

	#[test]
	fn basics() {
		let start = OsString::from("test");
		let as_stable_1 = start.to_stable_encoding();
		let as_stable_2 = start.into_stable_encoding();
		assert_eq!(as_stable_1, as_stable_2);

		let as_stable_1 = &*as_stable_1; // make sure &[EncodingWidth] can be given to from_stable_encoding()

		let as_os_string_1 = unsafe { OsString::from_stable_encoding(as_stable_1) };
		let as_os_string_2 = unsafe { OsString::from_stable_encoding(as_stable_2) };
		assert_eq!(as_os_string_1, as_os_string_2);

		let as_str = as_os_string_1.to_str();
		assert_eq!(as_str, Some("test"));
	}
}